Skip to content
API reference

shiitake

Import
import * as api from "@fungi.computer/shiitake";
Kind Export Description
class ShiitakeError Sanitized failure from a parsed Shiitake boundary.
type alias ColdSessionRow One Session as the store keeper sees it: what it holds and how cold it is.
type alias ColdSessionPage One bounded page of Sessions, coldest first.
type alias ColdSessionPageRequest A page request: limit is a whole number from 1 to 200 (default 50).
type alias ShiitakeErrorBoundary Stable boundary that rejected a Shiitake operation.
type alias ShiitakeErrorCause Safe failure category exposed by both Shiitake facades.
type alias ExtensionCapabilityV0 Closed, versioned, feature-free capability vocabulary.
type alias ShiitakeApi Public construction namespace for the Promise-facing durable harness.
type alias ShiitakeHost Promise-facing host composition with addressed mail kept off Session.
type alias PromptDelivery Delivery policy for input accepted while a Session run is active.
type alias SessionCommand Public Session command inferred from its one runtime parser.
type alias PromptCommand Public prompt command accepted as durable Session work.
type alias AbortCommand Cancel the running turn and all queued prompts, retaining their text.
type alias CancelCommand Public command that cancels exactly one accepted request.
type alias BranchCommand Public command that selects one complete entry as the active lineage leaf.
type alias OperatorCommand Public command that records one operator or party line without a run.
type alias CompactCommand Public command that compacts the Session’s context as queued work.
type alias TitleCommand Public command that sets or clears the user’s Session title.
type alias ForkCommand Public command that creates a new Session from one complete entry lineage.
type alias SqliteValue Native SQLite scalar and row grammar shared with the work queue owner.
type alias SqliteRow Raw row grammar shared by Woodstock and Watchdog.
type alias SqliteCursor Native rows stay raw until the query’s maintained schema decodes them.
type alias SqliteOwner Synchronous SQL and transactions held by the surrounding runtime.
type alias ModelAcquisition Acquired Pi model and optional explicit Pi stream function.
type alias ModelSource Deterministic host seam for model selection and ready egress.
type alias ModelDescription What a Session’s footer may know about its selected model.
type alias InstructionSnapshot Immutable instruction snapshot captured for one run.
type alias InstructionSource Host seam for one bounded instruction snapshot.
type alias ToolSource Mycelium construction inputs captured by the Shiitake-owned run scope.
type alias RuntimePendingWork Promise host for scheduling the opaque durable reconciler.
type alias RuntimeHost Promise host for scheduling the opaque durable reconciler.
type alias StoragePressureCheck A host’s storage-pressure check. Shiitake owns the refusal door and the typed storage_pressure error; the host owns the numbers behind it, such as Zookeeper’s budget and thresholds. While the check reports pressure, new Sessions and new prompts are refused and admitted work finishes.
type alias CompactionBudget One model’s compaction token budgets; omitted fields fall back.
type alias CompactionOptions Pi’s compaction settings. Each budget resolves through the exact provider/modelId override, then the ordinary value, then Pi’s default (16384 reserve, 20000 kept, 32768 background). enabled is global and governs automatic compaction only; a manual compaction always runs.
type alias ShiitakeOptions Validated immutable construction bag for the durable harness.
type alias ToolAccess A host’s access data for its Agent’s tools. Grants are keyed by module id; a module an extension built is granted by that extension’s id. A missing id keeps full access, so a first-time host writes no permission code.
type alias ShiitakeOwnerAgent The in-process owner of a durable harness. Only the host holds it, so only the host can write a Session’s grants or attach metadata; no HTTP or remote client can.
type alias CommandSettlement Exact accepted-work facts, independent of the current Session branch or page.
type alias StandardHostMetaSchema Any Standard Schema, such as a Zod 4 schema, whose validate settles synchronously. Shiitake only asks whether a value is accepted.
type alias StandardHostMetaResult One Standard Schema validation outcome; only acceptance matters here.
type alias HostMetaOptions The one schema a host supplies at Agent creation for the metadata it attaches to prompts and operator lines: an Effect schema whose encoded side is JSON, or a synchronous Standard Schema. Shiitake checks each value against it before writing; it never reads the decoded form.
type alias ModelPreference Null at the Session boundary means inherit the Agent default.
type alias VerifiedAgentReply A delegated Agent’s reply after the admitting host authenticated it.
type alias GrantsDelivery One versioned delivery of a Session’s grants.
type alias GrantsDeliveryResult Whether a delivery replaced the stored grants or repeated them.
type alias DocumentForkPolicyV0 Which source value a new Session starts with.
type alias DocumentSpecV0 A typed JSON document, bounded by its encoded UTF-8 size.
type alias DocumentsV0 Existential declarations; each initial value is decoded by its own schema.
type alias DocumentHandleV0 Both operations require the declaring extension’s active core transaction.
type alias DocumentHandlesV0 Handles preserve the decoded type of each declared document.
constant Shiitake Construct the Promise facade over the canonical Effect program.
constant sqliteRowSchema A native row is a scalar record; each query owner decodes its own projection.
function parseForkedSession() Parse one serialized fork result using Shiitake’s public client grammar.
function parseSessionSnapshot() Parse one serialized snapshot using Shiitake’s public client grammar.
function parseSessionFrame() Parse one serialized frame using Shiitake’s public client grammar.
function makeHost() Construct the host-only Promise facade over the canonical Effect program.

Sanitized failure from a parsed Shiitake boundary.

  • Error
Signature
new ShiitakeError(
boundary,
category,
message,
requestId?,
cause?
): ShiitakeError;

Construct a sanitized boundary failure.

Parameter Type Description
boundary | "contract" | "extensions" | "instructions" | "model" | "runtime" | "store" | "tools" Boundary that rejected the operation.
category | "closed" | "conflict" | "incompatible" | "invalid" | "rejected" | "unavailable" | "state_reset_required" | "storage_pressure" Safe category describing why it was rejected.
message string Human-readable message safe for callers to display.
requestId? string Request identity recoverable when a send may have reached the owner.
cause? unknown The original thrown value, kept for server-side diagnosis only. It is never serialized: the wire encoder copies named fields only.

ShiitakeError

Signature
Error.constructor;
Signature
readonly _tag: "ShiitakeError";

Stable runtime tag for typed Shiitake failures.

Signature
readonly cause:
| "closed"
| "conflict"
| "incompatible"
| "invalid"
| "rejected"
| "unavailable"
| "state_reset_required"
| "storage_pressure";

Safe category describing why it was rejected.

Signature
Error.cause;
Signature
readonly optional underlying?: unknown;

Original cause retained only for server-side diagnosis.

Signature
readonly boundary:
| "contract"
| "extensions"
| "instructions"
| "model"
| "runtime"
| "store"
| "tools";

Boundary that rejected the operation.

Signature
readonly optional requestId?: string;

Request identity recoverable when a send may have reached the owner.

ColdSessionRowtype alias

Section titled “ColdSessionRow”
Signature
type ColdSessionRow = Readonly<{
sessionId: string;
bytes: number;
lastActivityAt: number;
idle: boolean;
}>;

One Session as the store keeper sees it: what it holds and how cold it is.


ColdSessionPagetype alias

Section titled “ColdSessionPage”
Signature
type ColdSessionPage = Readonly<{
sessions: readonly ColdSessionRow[];
next?: string;
}>;

One bounded page of Sessions, coldest first.


ColdSessionPageRequesttype alias

Section titled “ColdSessionPageRequest”
Signature
type ColdSessionPageRequest = Readonly<{
limit?: number;
after?: string;
}>;

A page request: limit is a whole number from 1 to 200 (default 50).


ShiitakeErrorBoundarytype alias

Section titled “ShiitakeErrorBoundary”
Signature
type ShiitakeErrorBoundary = Schema.Schema.Type<
typeof ShiitakeErrorBoundarySchema
>;

Stable boundary that rejected a Shiitake operation.


ShiitakeErrorCausetype alias

Section titled “ShiitakeErrorCause”
Signature
type ShiitakeErrorCause = Schema.Schema.Type<typeof ShiitakeErrorCauseSchema>;

Safe failure category exposed by both Shiitake facades.


ExtensionCapabilityV0type alias

Section titled “ExtensionCapabilityV0”
Signature
type ExtensionCapabilityV0 =
| "state"
| "attention"
| "settled"
| "send"
| "timers"
| "commands"
| "projection"
| "run_tools"
| "files"
| "prompt"
| "compaction_handoff";

Closed, versioned, feature-free capability vocabulary.


ShiitakeApitype alias

Section titled “ShiitakeApi”
Signature
type ShiitakeApi = Readonly<{
make: (options) => Promise<ShiitakeOwnerAgent>;
}>;

Public construction namespace for the Promise-facing durable harness.


ShiitakeHosttype alias

Section titled “ShiitakeHost”
Signature
type ShiitakeHost = Readonly<{
readSettlement: (
sessionId,
commandId,
) => Promise<CommandSettlement | undefined>;
agent: ShiitakeOwnerAgent;
acceptMail: (mail, meta?, reply?, stageAcceptedNotice?) => Promise<Accepted>;
}>;

Promise-facing host composition with addressed mail kept off Session.


PromptDeliverytype alias

Section titled “PromptDelivery”
Signature
type PromptDelivery = "steer" | "followUp";

Delivery policy for input accepted while a Session run is active.


SessionCommandtype alias

Section titled “SessionCommand”
Signature
type SessionCommand = Schema.Schema.Type<typeof SessionCommandSchema>;

Public Session command inferred from its one runtime parser.


PromptCommandtype alias

Section titled “PromptCommand”
Signature
type PromptCommand = Schema.Schema.Type<typeof PromptCommandSchema>;

Public prompt command accepted as durable Session work.


AbortCommandtype alias

Section titled “AbortCommand”
Signature
type AbortCommand = Schema.Schema.Type<typeof AbortCommandSchema>;

Cancel the running turn and all queued prompts, retaining their text.


CancelCommandtype alias

Section titled “CancelCommand”
Signature
type CancelCommand = Schema.Schema.Type<typeof CancelCommandSchema>;

Public command that cancels exactly one accepted request.


BranchCommandtype alias

Section titled “BranchCommand”
Signature
type BranchCommand = Extract<
SessionCommand,
Readonly<{
type: "branch";
}>
>;

Public command that selects one complete entry as the active lineage leaf.


OperatorCommandtype alias

Section titled “OperatorCommand”
Signature
type OperatorCommand = Extract<
SessionCommand,
Readonly<{
type: "operator";
}>
>;

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


CompactCommandtype alias

Section titled “CompactCommand”
Signature
type CompactCommand = Extract<
SessionCommand,
Readonly<{
type: "compact";
}>
>;

Public command that compacts the Session’s context as queued work.


TitleCommandtype alias

Section titled “TitleCommand”
Signature
type TitleCommand = Extract<
SessionCommand,
Readonly<{
type: "title";
}>
>;

Public command that sets or clears the user’s Session title.


ForkCommandtype alias

Section titled “ForkCommand”
Signature
type ForkCommand = Extract<
SessionCommand,
Readonly<{
type: "fork";
}>
>;

Public command that creates a new Session from one complete entry lineage.


SqliteValuetype alias

Section titled “SqliteValue”
Signature
type SqliteValue = WatchdogSqliteValue;

Native SQLite scalar and row grammar shared with the work queue owner.


SqliteRowtype alias

Section titled “SqliteRow”
Signature
type SqliteRow = WatchdogSqliteRow;

Raw row grammar shared by Woodstock and Watchdog.


SqliteCursortype alias

Section titled “SqliteCursor”
Signature
type SqliteCursor = WatchdogSqliteCursor &
Readonly<{
one: () => SqliteRow;
}>;

Native rows stay raw until the query’s maintained schema decodes them.


SqliteOwnertype alias

Section titled “SqliteOwner”
Signature
type SqliteOwner = Omit<WatchdogSqliteOwner, "sql"> &
Readonly<{
sql: Readonly<{
exec: (statement, ...bindings) => SqliteCursor;
}>;
storeName?: string;
}>;

Synchronous SQL and transactions held by the surrounding runtime.


ModelAcquisitiontype alias

Section titled “ModelAcquisition”
Signature
type ModelAcquisition = Readonly<{
model: Model<Api>;
stream?: MuleStreamFunction;
retryable: (message) => boolean;
retryAfterMs?: (message) => number | undefined;
failureReason?: (message) => string | undefined;
rejection?: (message) => ProviderRejection | undefined;
providerError?: (message) => string | undefined;
release: () => Promise<void>;
}>;

Acquired Pi model and optional explicit Pi stream function.


ModelSourcetype alias

Section titled “ModelSource”
Signature
type ModelSource = Readonly<{
acquire: (input) => Promise<ModelAcquisition>;
describe?: (input) => Promise<ModelDescription>;
}>;

Deterministic host seam for model selection and ready egress.


ModelDescriptiontype alias

Section titled “ModelDescription”
Signature
type ModelDescription = Readonly<{
contextWindow: number | null;
}>;

What a Session’s footer may know about its selected model.


InstructionSnapshottype alias

Section titled “InstructionSnapshot”
Signature
type InstructionSnapshot = Readonly<{
revision: string;
text: string;
modules?: readonly ModuleRegistration[];
release?: () => void;
}>;

Immutable instruction snapshot captured for one run.


InstructionSourcetype alias

Section titled “InstructionSource”
Signature
type InstructionSource = Readonly<{
load: (input) => Promise<InstructionSnapshot>;
}>;

Host seam for one bounded instruction snapshot.


ToolSourcetype alias

Section titled “ToolSource”
Signature
type ToolSource = Readonly<{
execution?: ExecutionOptions;
modules?: readonly ModuleRegistration[];
sources?: readonly CapabilitySource[];
sandbox: Sandbox;
access?: ToolAccess;
}>;

Mycelium construction inputs captured by the Shiitake-owned run scope.


RuntimePendingWorktype alias

Section titled “RuntimePendingWork”
Signature
type RuntimePendingWork = Readonly<{
pending: boolean;
nextWakeAt: number | null;
}>;

Promise host for scheduling the opaque durable reconciler.


RuntimeHosttype alias

Section titled “RuntimeHost”
Signature
type RuntimeHost = Readonly<{
bind: (input) => Promise<
Readonly<{
commit: <A>(mutation) => Promise<A>;
requestWake: () => Promise<void>;
close: () => Promise<void>;
}>
>;
}>;

Promise host for scheduling the opaque durable reconciler.


StoragePressureChecktype alias

Section titled “StoragePressureCheck”
Signature
type StoragePressureCheck = Readonly<{
underPressure: () => boolean;
}>;

A host’s storage-pressure check. Shiitake owns the refusal door and the typed storage_pressure error; the host owns the numbers behind it, such as Zookeeper’s budget and thresholds. While the check reports pressure, new Sessions and new prompts are refused and admitted work finishes.


CompactionBudgettype alias

Section titled “CompactionBudget”
Signature
type CompactionBudget = Readonly<{
reserveTokens?: number;
keepRecentTokens?: number;
backgroundTokens?: number;
}>;

One model’s compaction token budgets; omitted fields fall back.


CompactionOptionstype alias

Section titled “CompactionOptions”
Signature
type CompactionOptions = CompactionBudget &
Readonly<{
enabled?: boolean;
modelOverrides?: Readonly<Record<string, CompactionBudget>>;
}>;

Pi’s compaction settings. Each budget resolves through the exact provider/modelId override, then the ordinary value, then Pi’s default (16384 reserve, 20000 kept, 32768 background). enabled is global and governs automatic compaction only; a manual compaction always runs.


ShiitakeOptionstype alias

Section titled “ShiitakeOptions”
Signature
type ShiitakeOptions = Readonly<{
meta?: HostMetaOptions;
store: SqliteOwner;
storagePressure?: StoragePressureCheck;
compaction?: CompactionOptions;
runtime: RuntimeHost;
model: ModelSource;
instructions: InstructionSource;
tools?: ToolSource;
extensions: ExtensionRosterV0;
}>;

Validated immutable construction bag for the durable harness.


ToolAccesstype alias

Section titled “ToolAccess”
Signature
type ToolAccess = Pick<
AccessOptions,
"grants" | "required" | "confirm" | "onRefused"
>;

A host’s access data for its Agent’s tools. Grants are keyed by module id; a module an extension built is granted by that extension’s id. A missing id keeps full access, so a first-time host writes no permission code.


ShiitakeOwnerAgenttype alias

Section titled “ShiitakeOwnerAgent”
Signature
type ShiitakeOwnerAgent = ShiitakeAgent &
Readonly<{
prepareConfiguration: (configuration) => Promise<
Readonly<{
commit: () => void;
discard: () => Promise<void>;
}>
>;
grants: Readonly<{
deliver: (sessionId, delivery) => GrantsDeliveryResult;
read: (sessionId) => GrantsDelivery | null;
}>;
withMeta: (meta) => ShiitakeAgent;
}>;

The in-process owner of a durable harness. Only the host holds it, so only the host can write a Session’s grants or attach metadata; no HTTP or remote client can.


CommandSettlementtype alias

Section titled “CommandSettlement”
Signature
type CommandSettlement = Readonly<{
acceptedSender: string | null;
terminal: SessionTerminal;
content: string;
usage: readonly Pick<AssistantMessage, "provider" | "model" | "usage">[];
toolCalls: number;
}>;

Exact accepted-work facts, independent of the current Session branch or page.


StandardHostMetaSchematype alias

Section titled “StandardHostMetaSchema”
Signature
type StandardHostMetaSchema = Readonly<{
~standard: Readonly<{
validate: (value) =>
| StandardHostMetaResult
| PromiseLike<StandardHostMetaResult>;
}>;
}>;

Any Standard Schema, such as a Zod 4 schema, whose validate settles synchronously. Shiitake only asks whether a value is accepted.


StandardHostMetaResulttype alias

Section titled “StandardHostMetaResult”
Signature
type StandardHostMetaResult =
| Readonly<{
issues?: undefined;
}>
| Readonly<{
issues: readonly Readonly<{
message: string;
}>[];
}>;

One Standard Schema validation outcome; only acceptance matters here.


HostMetaOptionstype alias

Section titled “HostMetaOptions”
Signature
type HostMetaOptions = Readonly<{
schema: Schema.Codec<unknown, Json> | StandardHostMetaSchema;
identityPath?: string;
}>;

The one schema a host supplies at Agent creation for the metadata it attaches to prompts and operator lines: an Effect schema whose encoded side is JSON, or a synchronous Standard Schema. Shiitake checks each value against it before writing; it never reads the decoded form.


ModelPreferencetype alias

Section titled “ModelPreference”
Signature
type ModelPreference = Schema.Schema.Type<typeof ModelPreferenceSchema>;

Null at the Session boundary means inherit the Agent default.


VerifiedAgentReplytype alias

Section titled “VerifiedAgentReply”
Signature
type VerifiedAgentReply = typeof VerifiedAgentReplySchema.Type;

A delegated Agent’s reply after the admitting host authenticated it.


GrantsDeliverytype alias

Section titled “GrantsDelivery”
Signature
type GrantsDelivery = Readonly<{
version: number;
grants: Grants;
}>;

One versioned delivery of a Session’s grants.


GrantsDeliveryResulttype alias

Section titled “GrantsDeliveryResult”
Signature
type GrantsDeliveryResult = "applied" | "unchanged";

Whether a delivery replaced the stored grants or repeated them.


DocumentForkPolicyV0type alias

Section titled “DocumentForkPolicyV0”
Signature
type DocumentForkPolicyV0 = "inherit-at-fork-point" | "current" | "fresh";

Which source value a new Session starts with.


DocumentSpecV0type alias

Section titled “DocumentSpecV0”
Signature
type DocumentSpecV0<A, I> = Readonly<{
schema: Schema.Codec<A, I>;
initial: A;
fork: DocumentForkPolicyV0;
maxBytes: number;
}>;

A typed JSON document, bounded by its encoded UTF-8 size.

Type Parameter Default type
A -
I A

DocumentsV0type alias

Section titled “DocumentsV0”
Signature
type DocumentsV0 = Readonly<
Record<
string,
Readonly<{
schema: Schema.Codec<unknown>;
initial: unknown;
fork: DocumentForkPolicyV0;
maxBytes: number;
}>
>
>;

Existential declarations; each initial value is decoded by its own schema.


DocumentHandleV0type alias

Section titled “DocumentHandleV0”
Signature
type DocumentHandleV0<A> = Readonly<{
read: (sessionId) => A;
update: (sessionId, change) => void;
}>;

Both operations require the declaring extension’s active core transaction.

Type Parameter
A

DocumentHandlesV0type alias

Section titled “DocumentHandlesV0”
Signature
type DocumentHandlesV0<D> = {
readonly [K in keyof D]: DocumentHandleV0<D[K]["schema"]["Type"]>;
};

Handles preserve the decoded type of each declared document.

Type Parameter
D extends DocumentsV0

Shiitakeconstant

Section titled “Shiitake”
Signature
const Shiitake: ShiitakeApi;

Construct the Promise facade over the canonical Effect program.


sqliteRowSchemaconstant

Section titled “sqliteRowSchema”
Signature
const sqliteRowSchema: Schema.$Record<
Schema.String,
Schema.Union<
readonly [
Schema.instanceOf<ArrayBuffer, unknown>,
Schema.String,
Schema.Number,
Schema.Null,
]
>
>;

A native row is a scalar record; each query owner decodes its own projection.

parseForkedSession()function

Section titled “parseForkedSession()”
Signature
function parseForkedSession(value): ForkedSession;

Parse one serialized fork result using Shiitake’s public client grammar.

Parameter Type
value string

ForkedSession


parseSessionSnapshot()function

Section titled “parseSessionSnapshot()”
Signature
function parseSessionSnapshot(value): SessionSnapshot;

Parse one serialized snapshot using Shiitake’s public client grammar.

Parameter Type
value string

SessionSnapshot


parseSessionFrame()function

Section titled “parseSessionFrame()”
Signature
function parseSessionFrame(value): SessionFrame;

Parse one serialized frame using Shiitake’s public client grammar.

Parameter Type
value string

SessionFrame


Signature
function makeHost(options, mailRoom): Promise<Readonly<{
readSettlement: (sessionId, commandId) => Promise<
| Readonly<{
acceptedSender: string | null;
terminal: SessionTerminal;
content: string;
usage: readonly Pick<AssistantMessage, ... | ... | ...>[];
toolCalls: number;
}>
| undefined>;
agent: ShiitakeOwnerAgent;
acceptMail: (mail, meta?, reply?, stageAcceptedNotice?) => Promise<Readonly<{
status: "accepted";
commandId: string;
sessionId?: string;
}>>;
}>>;

Construct the host-only Promise facade over the canonical Effect program.

Parameter Type
options ShiitakeOptions
mailRoom BirdDogEffect

Promise<Readonly<{ readSettlement: (sessionId, commandId) => Promise< | Readonly<{ acceptedSender: string | null; terminal: SessionTerminal; content: string; usage: readonly Pick<AssistantMessage, … | … | …>[]; toolCalls: number; }> | undefined>; agent: ShiitakeOwnerAgent; acceptMail: (mail, meta?, reply?, stageAcceptedNotice?) => Promise<Readonly<{ status: "accepted"; commandId: string; sessionId?: string; }>>; }>>

Re-exports AgentExtensionControls


Re-exports CancelResult


Re-exports Accepted


Re-exports DelegationReceipt


Re-exports Held


Re-exports ForkedSession


Re-exports SendOptions


Re-exports ReadOptions


Re-exports SessionCommandHandler


Re-exports SessionExtensionControls


Re-exports SessionExtensionSlots


Re-exports SessionFrame


Re-exports SessionMessage


Re-exports SessionProgress


Re-exports SessionToolOutput


Re-exports SessionContext


Re-exports SessionSnapshot


Re-exports SessionInboxState


Re-exports SessionSummary


Re-exports SessionSummaryPage


Re-exports SessionSummaryRow


Re-exports SessionActivity


Re-exports AgentRunningWork


Re-exports SessionTerminal


Re-exports SessionCompactionMarker


Re-exports SessionCompactionNotice


Re-exports SessionCompactionTrigger


Re-exports ShiitakeEventSourceConstructor


Re-exports SessionWatch


Re-exports ShiitakeAgent


Re-exports ShiitakeSession


Re-exports SubscribeOptions


Re-exports TooLate


Re-exports UnknownRequest


Re-exports WatchOptions


Re-exports BorrowedCompactionViewV0


Re-exports CompactionHandoffErrorV0


Re-exports CompactionHandoffResultV0


Re-exports CompactionHandoffV0


Re-exports ExtensionGrantV0


Re-exports ExtensionRosterV0


Re-exports ExtensionSlotV0


Re-exports ExtensionStatusV0


Re-exports RosteredExtensionV0