client

@fungi.computer/shiitake

@fungi.computer/shiitake / client

client

Type Aliases

Accepted

Accepted = Readonly<{ status: "accepted"; commandId: string; }>

Semantic acknowledgement returned after one durable acceptance commit.

ForkedSession

ForkedSession = Readonly<{ sessionId: string; }>

Result returned after a fork commits a new cold-readable Session.

SessionCommandHandler

SessionCommandHandler = {(input): Promise<Readonly<{ status: "accepted"; commandId: string; }>>; (input): Promise<undefined>>; (input): Promise<Readonly<{ sessionId: string; }>>; (input): Promise<Readonly<{ status: "accepted"; commandId: string; }> | Readonly<{ sessionId: string; }> | undefined>>; }

Execute one retained type-discriminated Session command.

Call Signature

(input): Promise<Readonly<{ status: "accepted"; commandId: string; }>>

Accept a prompt or cancellation of one existing command.

Parameters

input

{ delivery: "followUp" | "steer"; requestId: string; type: "prompt"; text: string; } | { commandId: string; onlyIfPending?: boolean; type: "cancel"; }

Returns

Promise<Readonly<{ status: "accepted"; commandId: string; }>>

Call Signature

(input): Promise<undefined>>

Abort the active run or select a complete Session lineage leaf.

Parameters

input

{ type: "abort"; } | { type: "branch"; entryId: string; }

Returns

Promise<undefined>

Call Signature

(input): Promise<Readonly<{ sessionId: string; }>>

Fork one complete entry lineage into a new Session.

Parameters

input

type

"fork" = ...

entryId

string = boundedId

Returns

Promise<Readonly<{ sessionId: string; }>>

Call Signature

(input): Promise<Readonly<{ status: "accepted"; commandId: string; }> | Readonly<{ sessionId: string; }> | undefined>>

Execute an already-decoded command union.

Parameters

input

{ delivery: "followUp" | "steer"; requestId: string; type: "prompt"; text: string; } | { type: "abort"; } | { commandId: string; onlyIfPending?: boolean; type: "cancel"; } | { type: "branch"; entryId: string; } | { type: "fork"; entryId: string; }

Returns

Promise<Readonly<{ status: "accepted"; commandId: string; }> | Readonly<{ sessionId: string; }> | undefined>

SendOptions

SendOptions = Readonly<{ delivery?: PromptDelivery; requestId?: string; }>

Optional controls for the Promise-friendly text sender.

SessionMessage

SessionMessage = Readonly<{ id: string; sequence: number; commandId: string | null; value: Message; }>

One exact completed Pi message on the selected Session lineage.

ShiitakeEventSourceConstructor

ShiitakeEventSourceConstructor = (url) => Pick<EventTarget, "addEventListener"> > & Pick<EventSource, "close"> > & object

Minimal constructor seam for runtimes without a global EventSource.

Parameters

url

string

Returns

Pick<EventTarget, "addEventListener"> & Pick<EventSource, "close"> & object

SessionTerminal

SessionTerminal = Readonly<{ commandId: string; outcome: "completed" | "cancelled" | "failed" | "interrupted"; }>

Durable outcome for one accepted work item on the selected Session lineage.

SessionStatus

SessionStatus = "cancelling" | "idle" | "queued" | "retrying" | "streaming" | "thinking"

Compact current Session activity derived by Shiitake.

SessionExtensionSlots

SessionExtensionSlots = Readonly<Record<string, ExtensionSlotV1>>>>

Encoded extension slots keyed by extension identity; absent means unavailable.

SessionExtensionControls

SessionExtensionControls = Readonly<{ call: (command, input) => Promise<Json>>; }>

Generic Session-scope extension commands.

AgentExtensionControls

AgentExtensionControls = Readonly<{ list: () => Promise<readonly ExtensionStatusV1[]>; resume: (extensionId) => Promise<ExtensionStatusV1>>; call: (extensionId, command, input) => Promise<Json>>; }>

Generic Agent-scope extension controls.

SessionProgress

SessionProgress = Readonly<{ messageId: string; revision: number; text: string; thinking: string; textTruncated: boolean; thinkingTruncated: boolean; }>

Process-local assistant progress; never a durable Session fact.

SessionPendingPrompt

SessionPendingPrompt = Readonly<{ commandId: string; text: string; delivery: PromptDelivery; }>

Accepted prompt waiting to enter the conversation, not a scheduling command.

SessionPendingPrompts

SessionPendingPrompts = Readonly<{ prompts: readonly SessionPendingPrompt[]; hasMore: boolean; }>

Bounded current admission view, in acceptance order rather than execution order.

SessionSnapshot

SessionSnapshot = Readonly<{ sessionId: string; cursor: string | null; hasMore: boolean; messages: readonly SessionMessage[]; terminals: readonly SessionTerminal[]; pending: SessionPendingPrompts; status: SessionStatus; progress: SessionProgress | null; extensions: SessionExtensionSlots; }>

Bounded Session baseline at one opaque owner cursor.

SessionFrame

SessionFrame = Readonly<{ kind: "update"; delivery: "replay" | "live"; cursor: string | null; pending: SessionPendingPrompts; messages: readonly SessionMessage[]; terminals: readonly SessionTerminal[]; status: SessionStatus; extensions: SessionExtensionSlots; }> | Readonly<{ kind: "progress"; progress: SessionProgress; status: SessionStatus; }> | Readonly<{ kind: "reset"; reason: "history_unavailable"; cursor: string | null; baseline: SessionSnapshot; }>

One bounded replay or live frame.

SubscribeOptions

SubscribeOptions = Readonly<{ after?: string; }>

Strict-after replay request.

ReadOptions

ReadOptions = Readonly<{ limit?: number; }>

Bounded baseline request.

WatchOptions

WatchOptions = ReadOptions

Race-safe observation request.

SessionWatch

SessionWatch = Readonly<{ snapshot: SessionSnapshot; changes: AsyncIterable<SessionFrame>>; close: () => Promise<void>>; }>

Race-safe baseline plus live changes resource.

ShiitakeSession

ShiitakeSession = Readonly<{ address: string; command: SessionCommandHandler; abort: () => Promise<void>>; send: (text, options?) => Promise<Accepted>>; cancel: (input) => Promise<Accepted>>; extension: (extensionId) => SessionExtensionControls; modelPreference: Readonly<{ read: () => Promise<ModelPreference | null>>; set: (preference) => Promise<void>>; }>; read: (input?) => Promise<SessionSnapshot>>; subscribe: (input) => AsyncIterable<SessionFrame>>; watch: (input?) => Promise<SessionWatch>>; }>

Addressable Session interface. Addressing itself performs no I/O.

SessionSummary

SessionSummary = Readonly<{ createdAt: number; updatedAt: number; title: string; status: SessionStatus; }>

Read-only saved conversation projection; opening does not update recency.

SessionSummaryRow

SessionSummaryRow = SessionSummary & Readonly<{ kind: "session"; sessionId: string; }> | Readonly<{ kind: "unavailable"; sessionId: string; }>

One listed conversation, or a saved Session its owner could not read.

SessionSummaryPage

SessionSummaryPage = Readonly<{ sessions: readonly SessionSummaryRow[]; next: string | undefined; }>

One owner-bounded page, in stable Session identity order.

ShiitakeAgent

ShiitakeAgent = Readonly<{ createSession: (requestId) => Promise<string>>; listSessions: (after?) => Promise<SessionSummaryPage>>; extensions: AgentExtensionControls; session: (sessionId) => ShiitakeSession; close: () => Promise<void>>; }>

Constructed durable harness.

ExtensionViewV1

ExtensionViewV1<P> > = Readonly<{ status: "unavailable"; }> | Readonly<{ status: "stopped"; reason: string; }> | Readonly<{ status: "running"; value: P | null; }>

What one client sees of an extension in a Session observation.

Type Parameters

P

P

ScopedCommandsV1

ScopedCommandsV1<C, S> > = { [K in keyof C & string]: C[K]["scope"] extends S ? K : never }[keyof C & string]

Command names of one scope, typed by the shared contract.

Type Parameters

C

C extends CommandsV1

S

S extends "session" | "agent"

BoundCallV1

BoundCallV1<C, S> > = <K>>(name, input) => Promise<Schema.Schema.Type<C[K]["output"]>>

Typed call surface of one contract’s commands in one scope.

Type Parameters

C

C extends CommandsV1

S

S extends "session" | "agent"

Type Parameters

K

K extends ScopedCommandsV1<C, S>

Parameters

name

K

input

Schema.Schema.Type<C[K]["input"]>

Returns

Promise<Schema.Schema.Type<C[K]["output"]>>

BoundSessionExtensionV1

BoundSessionExtensionV1<C, P> > = Readonly<{ view: (observation) => ExtensionViewV1<P>>; call: BoundCallV1<C, "session">>; }>

One Session bound to one extension contract.

Type Parameters

C

C extends CommandsV1

P

P

BoundAgentExtensionV1

BoundAgentExtensionV1<C> > = Readonly<{ call: BoundCallV1<C, "agent">>; }>

One Agent bound to one extension contract.

Type Parameters

C

C extends CommandsV1

ShiitakeClientOptions

ShiitakeClientOptions = Readonly<{ baseUrl: string; fetch?: typeof globalThis.fetch; eventSource?: ShiitakeEventSourceConstructor; }>

Network location of one remotely hosted Shiitake agent.

Functions

parseAccepted()

parseAccepted(value): Accepted

Parse one serialized command acceptance using Shiitake’s public grammar.

Parameters

value

string

Returns

Accepted

parseShiitakeError()

parseShiitakeError(value): ShiitakeError

Parse one serialized canonical Shiitake failure.

Parameters

value

string

Returns

ShiitakeError

parseSessionSummaryPage()

parseSessionSummaryPage(value): SessionSummaryPage

Decode the existing bounded saved-conversation projection.

Parameters

value

string

Returns

SessionSummaryPage

bindSessionExtension()

bindSessionExtension<C, P, PI>>(session, contract): BoundSessionExtensionV1<C, P>>

Bind one Session to one extension contract; the contract’s schemas decode.

Type Parameters

C

C extends Readonly<Record<string, Readonly<{ scope: "session" | "agent"; input: AnyNoContext; output: AnyNoContext; }>>>

P

P

PI

PI

Parameters

session

Pick<ShiitakeSession, "extension">

contract

ExtensionContractV1<C, P, PI>

Returns

BoundSessionExtensionV1<C, P>

bindAgentExtension()

bindAgentExtension<C, P, PI>>(agent, contract): BoundAgentExtensionV1<C>>

Bind one Agent to one extension contract’s Agent-scope commands.

Type Parameters

C

C extends Readonly<Record<string, Readonly<{ scope: "session" | "agent"; input: AnyNoContext; output: AnyNoContext; }>>>

P

P

PI

PI

Parameters

agent

Pick<ShiitakeAgent, "extensions">

contract

ExtensionContractV1<C, P, PI>

Returns

BoundAgentExtensionV1<C>

createShiitakeClient()

createShiitakeClient(options): ShiitakeAgent

Connect to a remotely hosted Shiitake agent.

Parameters

options

ShiitakeClientOptions

Returns

ShiitakeAgent

References