client

Type Aliases

Accepted

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

Semantic acknowledgement returned after one durable acceptance commit.

TooLate

TooLate = Readonly<{ status: "too_late"; commandId: string; }>

Cancelling found nothing left to cancel: the command is unknown to this Session, has already started (for an onlyIfPending cancel) or has already settled. It is an ordinary outcome, never an error.

CancelResult

CancelResult = Accepted | TooLate

Outcome of one cancel command.

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<CancelResult>>; (input): Promise<undefined>>; (input): Promise<Readonly<{ sessionId: string; }>>; (input): Promise<CancelResult | Readonly<{ sessionId: string; }> | undefined>>; }

Execute one retained type-discriminated Session command.

Call Signature

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

Accept a prompt.

Parameters

input

delivery

"followUp" | "steer" = PromptDeliverySchema

requestId

string = boundedId

type

"prompt" = ...

text

string = PromptTextSchema

Returns

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

Call Signature

(input): Promise<CancelResult>>

Cancel one accepted command, or report that it is too late.

Parameters

input

commandId

string = boundedId

onlyIfPending?

boolean = ...

type

"cancel" = ...

Returns

Promise<CancelResult>

Call Signature

(input): Promise<undefined>>

Abort the active run, select a lineage leaf, or record an operator line.

Parameters

input

{ type: "abort"; } | { type: "branch"; entryId: string; } | { type: "operator"; requestId: string; author: "operator" | "party"; text: 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<CancelResult | 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; } | { type: "operator"; requestId: string; author: "operator" | "party"; text: string; }

Returns

Promise<CancelResult | 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"; sequence: number; diagnostic: string | null; }>

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

SessionActivity

SessionActivity = Readonly<{ queue: Readonly<{ state: "idle"; }> | Readonly<{ state: "queued"; commandId: string; }> | Readonly<{ state: "running"; commandId: string; }>; cancellationRequested: boolean; retry: Readonly<{ attempt: number; maxAttempts: number; delayMs: number; errorMessage: string; scheduledAt: number; }> | null; activeTool: string | null; lastModelChoiceSequence: number | null; }>

Raw facts about what a Session is doing now. Shiitake publishes facts only; a client decides what they mean (see Parakeet’s sessionViewState).

SessionExtensionSlots

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

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 ExtensionStatusV0[]>; resume: (extensionId) => Promise<ExtensionStatusV0>>; 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.

SessionCompactionMarker

SessionCompactionMarker = Readonly<{ id: string; sequence: number; at: number; }>

Minimal full-history compaction boundary marker. sequence is the Woodstock order of the row this marker precedes (ties sort the marker first); at is when the compaction ran. The agent’s model context is unaffected by this marker; it exists only for the client timeline.

SessionSnapshot

SessionSnapshot = Readonly<{ sessionId: string; cursor: string | null; hasMore: boolean; oldestCursor?: string | null; messages: readonly SessionMessage[]; terminals: readonly SessionTerminal[]; compactions?: readonly SessionCompactionMarker[]; sandboxFailures?: readonly SandboxFailureEvent[]; pending: SessionPendingPrompts; activity: SessionActivity; 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[]; compactions?: readonly SessionCompactionMarker[]; sandboxFailures?: readonly SandboxFailureEvent[]; activity: SessionActivity; extensions: SessionExtensionSlots; }> | Readonly<{ kind: "progress"; progress: SessionProgress; activity: SessionActivity; }> | Readonly<{ kind: "reset"; reason: "history_unavailable"; cursor: string | null; baseline: SessionSnapshot; }>

One bounded replay or live frame.

SubscribeOptions

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

Strict-after replay request.

ReadOptions

ReadOptions = Readonly<{ includeSandboxFailures?: boolean; limit?: number; before?: string; }>

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<CancelResult>>; 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.

SessionInboxState

SessionInboxState = "needs_you" | "running" | "errored" | "done"

Owner-decided inbox state, from Watchdog’s queue head and latest outcome. running covers queued, thinking, streaming, retrying and cancelling; errored covers failed, interrupted and outcome_unknown; done covers completed, cancelled and never run. needs_you is reserved for a waiting kind supplied by approvals or channels.

SessionSummary

SessionSummary = Readonly<{ createdAt: number; lastActivityAt: number; settledAt?: number; title: string; state: SessionInboxState; }>

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

SessionSummaryRow

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

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: needs_you, then running, then settled rows, each newest activity first. next is an opaque owner cursor.

ShiitakeAgent

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

Constructed durable harness.

ExtensionViewV0

ExtensionViewV0<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

ScopedCommandsV0

ScopedCommandsV0<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 CommandsV0

S

S extends "session" | "agent"

BoundCallV0

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

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

Type Parameters

C

C extends CommandsV0

S

S extends "session" | "agent"

Type Parameters

K

K extends ScopedCommandsV0<C, S>

Parameters

name

K

input

C[K]["input"]["Type"]

Returns

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

BoundSessionExtensionV0

BoundSessionExtensionV0<C, P> > = Readonly<{ view: (observation) => ExtensionViewV0<P>>; call: BoundCallV0<C, "session">>; }>

One Session bound to one extension contract.

Type Parameters

C

C extends CommandsV0

P

P

BoundAgentExtensionV0

BoundAgentExtensionV0<C> > = Readonly<{ call: BoundCallV0<C, "agent">>; }>

One Agent bound to one extension contract.

Type Parameters

C

C extends CommandsV0

OperatorCommand

OperatorCommand = Extract<SessionCommand, Readonly<{ type: "operator"; }>>

Public command that records one operator or party line without a run.

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

parseCancelResult()

parseCancelResult(value): CancelResult

Parse one serialized cancel outcome: accepted, or too late.

Parameters

value

string

Returns

CancelResult

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): BoundSessionExtensionV0<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: Codec<unknown>; output: Codec<unknown>; }>>>

P

P

PI

PI

Parameters

session

Pick<ShiitakeSession, "extension">

contract

ExtensionContractV0<C, P, PI>

Returns

BoundSessionExtensionV0<C, P>

bindAgentExtension()

bindAgentExtension<C, P, PI>>(agent, contract): BoundAgentExtensionV0<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: Codec<unknown>; output: Codec<unknown>; }>>>