Skip to content
Shiitake0.6.0
API reference

extensions

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/shiitake/extensions";

Exports

Section titled “Exports”
Kind Export Description
class ExtensionRead Present only inside a core-run read (projection, run tools, hooks).
class ExtensionTx Present only inside a core-run write transaction (hooks, commands, transact). Core runs these Effects synchronously inside the owner transaction; an asynchronous boundary is a defect that stops the extension.
class ExtensionStateError Durable record failure: stored or supplied values broke their schema or bounds.
class AdmissionError The door refused an extension admission.
class ExtensionCommandError Typed rejection of one extension command, returned to its caller.
class ExtensionStop Fail a hook with this (or die) to stop this extension with a visible reason.
class ExtensionActivationError Typed activation failure; the extension is stopped with this message.
class ExtensionBuilderV0 Configure typed metadata, then register callbacks against its actual values.
class ExtensionHookError An outside handler rejected or threw before Shiitake could use its result.
type alias ShiitakeExtensionProtocolV0 Host extension protocol; client-entry protocol is versioned independently.
type alias ExtensionId ASCII extension identity shared by the server definition and its clients.
type alias ExtensionManifestV0 Static identity and requested capabilities of one v0 extension.
type alias CommandSpecV0 One command’s scope and its encoded input and output schemas.
type alias AnyCommandSpecV0 Existential command spec.
type alias CommandsV0 Commands declared by one extension contract.
type alias ProjectionSpecV0 The encoded Session projection slot.
type alias ExtensionContractV0 Shared by the host definition and the client binding: one schema set.
type alias ExtensionRevision sha256:<64 hex> derived by core from a definition; never authored.
type alias ExtensionFingerprint sha256:<64 hex> over one revision and its sorted granted capabilities.
type alias Json JSON value accepted as hashed extension configuration.
type alias ExtensionGrantV0 Host decision: the exact subset of requested capabilities it grants.
type alias HookError Failures a background hook may return; each one stops only its extension.
type alias CollectionSpecV0 One namespaced collection: its row schema is the only stored-row decoder.
type alias AnyCollectionSpecV0 Existential collection spec stored by core.
type alias CollectionsV0 Collections declared by one extension.
type alias StoredRecordV0 One stored record as seen by a pure migration.
type alias StateSpecV0 Versioned state declaration; core runs pure row migrations at activation.
type alias StateDeclarationV0 The versioned state declaration as authored; version defaults to 1.
type alias CollectionV0 Typed access to one collection inside a core transaction.
type alias UpdateCollectionV0 The transaction-local interface used by plain synchronous state.update.
type alias UpdateStateV0 Transaction-scoped collections plus post-commit Session notification.
type alias ReadStateV0 Synchronous, read-only collection access inside state.read.
type alias StateHandleV0 Typed handles for every declared collection.
type alias RunOutcomeV0 Watchdog settlement or exact Woodstock terminal of one run.
type alias RunOriginV0 Extension that admitted a run, with its stored correlation.
type alias SettledRunV0 One settled run joined by core with its terminal and admission origin.
type alias SettledPageV0 1..64 records, ascending, each delivered to each running extension once.
type alias SendInputV0 One prompt sent through the accepted-command door.
type alias SendResultV0 Door outcome for one extension admission.
type alias TimersV0 Durable per-extension wake timers (the scheduling substrate).
type alias FiredTimerV0 A fired timer; its row is consumed unless the handler sets it again.
type alias CommandSessionIdsV0 A command’s scope fixes whether its invocation names a Session.
type alias ExtensionCommandCallerV0 Host-authenticated caller context; never decoded from command JSON or HTTP.
type alias CommandHandlersV0 Handlers for every declared command, run in one core transaction.
type alias AttentionV0 Transaction-scoped, extension-owned attention on an existing Session.
type alias ExtensionContextV0 Everything core hands one activated extension.
type alias RunIdentityV0 One run the extension may attach tools to.
type alias PromptSectionV0 A named, bounded system-prompt section; core orders by extension and name.
type alias AgentHooksV0 Hooks returned by one activation; each runs in its own isolation boundary.
type alias RosteredExtensionV0 Opaque rostered value; core reads the definition existentially.
type alias DefinedExtensionV0 A defined extension: its roster entry and the client contract it declares.
type alias ExtensionDefinitionV0 Contributions registered against the builder’s captured metadata.
type alias CheckedCommandHandlers Reject Promise-returning transactional commands even when output is {}.
type alias ExtensionAuthorDefinitionV0 Caller-owned extension metadata and handlers accepted by the v0 builder.
type alias EmptyExtensionFieldsV0 Concrete metadata with no declared fields.
type alias ExtensionIdentityV0 An extension id, or an id with an explicit SemVer version.
type alias AnyAgentHooksV0 Existential hooks as stored by core; each handler is re-typed by its schema.
type alias AnyExtensionDefinitionV0 Existential definition stored by core.
type alias ExtensionRosterV0 A host’s explicit roster and grants.
type alias ExtensionStatusV0 Visible lifecycle of one rostered extension (wire representation).
type alias ExtensionSlotV0 One extension’s encoded slot in a Session snapshot or frame.
type alias BorrowedCompactionViewV0 Borrowed view of the exact objects already built for compaction.
type alias CompactionHandoffResultV0 Result returned before a borrowed compaction view may be released.
type alias CompactionHandoffErrorV0 Typed failure returned by the compaction contribution.
type alias CompactionHandoffV0 The exclusive compaction handoff callable of one extension.
type alias RegisteredExtensionCommandV0 A parsed invocation retains its typed handler until the transaction runs.
type alias CommandToolOptionsV0 How one command appears to the model when exposed as a tool.
type alias CommandToolsV0 Expose declared commands as model tools, bound to the current run’s Session.
type alias CollectionBindingV0 Core retains only these erased results; the author retains each concrete factory.
type alias ExtensionRuntimePortV0 State operations capture their typed declaration before entering core.
type alias SyncResult A write callback must resolve before the owner commits its SQLite transaction.
type alias StateUpdate Public state-update shape: infer the return before rejecting async results.
type alias AttentionRecipient Decoded Agent Session an attention item waits on.
type alias AttentionItem Input to the granted attention door, scoped to the calling extension.
constant extensionIdentifier ASCII extension identity shared by the host definition and its clients.
constant extensionVersion SemVer spelling used by host admission.
constant ExtensionId ASCII extension identity shared by the host definition and its clients.
constant AttentionRecipientSchema The Agent Session that sent the work an item belongs to. The host derives it from the accepted mail; it is the only party the item waits on until it is escalated.
constant AttentionItemSchema An extension-owned request for human attention; expiry is owned by its timer. Items marked inbox: false remain visible without changing the inbox state. An item with waitingOn waits on that Agent first and is never a person’s inbox item until it is escalated past every Agent.
function parseExtensionJson() Parse a serialized extension value into the finite JSON contract.
function defineExtension() Begin with honest empty defaults; optional contributions are declared explicitly. The version defaults to 0.0.0 and any SemVer, including a pre-release, is valid. It is part of the extension’s revision, which already covers schemas, config and requested capabilities; a different version marks a behaviour change those do not show, such as a fixed hook.
function defineCollection() Declare one collection with its key inferred from the row schema.

ExtensionReadclass

Section titled “ExtensionRead”

Present only inside a core-run read (projection, run tools, hooks).

Extends

Section titled “Extends”
  • Shape<"@fungi.computer/shiitake/ExtensionRead", Readonly<{ extensionId: string & Brand<"ExtensionId">; }>, this>

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new ExtensionRead(_): ExtensionRead;
Parameters
Section titled “Parameters”
Parameter Type
_ never
Returns
Section titled “Returns”

ExtensionRead

Inherited from
Section titled “Inherited from”
Signature
Context.Service<ExtensionRead, Readonly<{ extensionId: ExtensionId }>>()(
  "@fungi.computer/shiitake/ExtensionRead",
).constructor;

ExtensionTxclass

Section titled “ExtensionTx”

Present only inside a core-run write transaction (hooks, commands, transact). Core runs these Effects synchronously inside the owner transaction; an asynchronous boundary is a defect that stops the extension.

Extends

Section titled “Extends”
  • Shape<"@fungi.computer/shiitake/ExtensionTx", Readonly<{ extensionId: string & Brand<"ExtensionId">; }>, this>

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new ExtensionTx(_): ExtensionTx;
Parameters
Section titled “Parameters”
Parameter Type
_ never
Returns
Section titled “Returns”

ExtensionTx

Inherited from
Section titled “Inherited from”
Signature
Context.Service<ExtensionTx, Readonly<{ extensionId: ExtensionId }>>()(
  "@fungi.computer/shiitake/ExtensionTx",
).constructor;

ExtensionStateErrorclass

Section titled “ExtensionStateError”

Durable record failure: stored or supplied values broke their schema or bounds.

Extends

Section titled “Extends”
  • YieldableError<this> & object & Readonly<{ reason: "unavailable" | "decode" | "encode" | "bound" | "session_absent"; message: string; }>

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new ExtensionStateError(args): ExtensionStateError;
Parameters
Section titled “Parameters”
Parameter Type
args { reason: "unavailable" | "decode" | "encode" | "bound" | "session_absent"; message: string; }
args.reason "unavailable" | "decode" | "encode" | "bound" | "session_absent"
args.message string
Returns
Section titled “Returns”

ExtensionStateError

Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError(
  "ExtensionStateError",
)<{
  reason: "decode" | "encode" | "bound" | "unavailable" | "session_absent";
  message: string;
}>.constructor

Properties

Section titled “Properties”

reason

Section titled “reason”
Signature
readonly reason: "unavailable" | "decode" | "encode" | "bound" | "session_absent";
Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("ExtensionStateError").reason;

message

Section titled “message”
Signature
message: string;
Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("ExtensionStateError").message;

AdmissionErrorclass

Section titled “AdmissionError”

The door refused an extension admission.

Extends

Section titled “Extends”
  • YieldableError<this> & object & Readonly<{ reason: "closed" | "conflict" | "invalid"; message: string; }>

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new AdmissionError(args): AdmissionError;
Parameters
Section titled “Parameters”
Parameter Type
args { reason: "closed" | "conflict" | "invalid"; message: string; }
args.reason "closed" | "conflict" | "invalid"
args.message string
Returns
Section titled “Returns”

AdmissionError

Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("AdmissionError")<{
  reason: "invalid" | "conflict" | "closed";
  message: string;
}>.constructor

Properties

Section titled “Properties”

reason

Section titled “reason”
Signature
readonly reason: "closed" | "conflict" | "invalid";
Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("AdmissionError").reason;

message

Section titled “message”
Signature
message: string;
Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("AdmissionError").message;

ExtensionCommandErrorclass

Section titled “ExtensionCommandError”

Typed rejection of one extension command, returned to its caller.

Extends

Section titled “Extends”
  • YieldableError<this> & object & Readonly<{ reason: "conflict" | "invalid" | "rejected" | "not_found"; message: string; }>

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new ExtensionCommandError(args): ExtensionCommandError;
Parameters
Section titled “Parameters”
Parameter Type
args { reason: "conflict" | "invalid" | "rejected" | "not_found"; message: string; }
args.reason "conflict" | "invalid" | "rejected" | "not_found"
args.message string
Returns
Section titled “Returns”

ExtensionCommandError

Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError(
  "ExtensionCommandError",
)<{
  reason: "invalid" | "conflict" | "not_found" | "rejected";
  message: string;
}>.constructor

Properties

Section titled “Properties”

reason

Section titled “reason”
Signature
readonly reason: "conflict" | "invalid" | "rejected" | "not_found";
Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("ExtensionCommandError").reason;

message

Section titled “message”
Signature
message: string;
Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("ExtensionCommandError").message;

ExtensionStopclass

Section titled “ExtensionStop”

Fail a hook with this (or die) to stop this extension with a visible reason.

Extends

Section titled “Extends”
  • YieldableError<this> & object & Readonly<{ reason: string; }>

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new ExtensionStop(args): ExtensionStop;
Parameters
Section titled “Parameters”
Parameter Type
args { reason: string; }
args.reason string
Returns
Section titled “Returns”

ExtensionStop

Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("ExtensionStop")<{
  reason: string;
}>.constructor

Properties

Section titled “Properties”

reason

Section titled “reason”
Signature
readonly reason: string;
Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("ExtensionStop").reason;

ExtensionActivationErrorclass

Section titled “ExtensionActivationError”

Typed activation failure; the extension is stopped with this message.

Extends

Section titled “Extends”
  • YieldableError<this> & object & Readonly<{ message: string; }>

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new ExtensionActivationError(args): ExtensionActivationError;
Parameters
Section titled “Parameters”
Parameter Type
args { message: string; }
args.message string
Returns
Section titled “Returns”

ExtensionActivationError

Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError(
  "ExtensionActivationError",
)<{ message: string }>.constructor

Properties

Section titled “Properties”

message

Section titled “message”
Signature
message: string;
Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("ExtensionActivationError").message;

ExtensionBuilderV0class

Section titled “ExtensionBuilderV0”

Configure typed metadata, then register callbacks against its actual values.

Type Parameters

Section titled “Type Parameters”
Type Parameter
S extends CollectionsV0
Config extends Json
D extends DocumentsV0

Methods

Section titled “Methods”

fromIdentity()

Section titled “fromIdentity()”
Signature
static fromIdentity(identity): ExtensionBuilderV0<Readonly<Record<never, never>>, Readonly<Record<never, never>>, Readonly<Record<never, never>>>;

Begin with concrete empty metadata and no requested capability.

Parameters
Section titled “Parameters”
Parameter Type
identity Readonly<{ id: ExtensionId; version: string; }>
Returns
Section titled “Returns”

ExtensionBuilderV0<Readonly<Record<never, never>>, Readonly<Record<never, never>>, Readonly<Record<never, never>>>

config()

Section titled “config()”
Signature
config<Next>(value): ExtensionBuilderV0<S, Next, D>;

Hash this explicit JSON configuration with the extension revision.

Type Parameters
Section titled “Type Parameters”
Type Parameter
Next extends Json
Parameters
Section titled “Parameters”
Parameter Type
value Next
Returns
Section titled “Returns”

ExtensionBuilderV0<S, Next, D>

state()

Section titled “state()”
Signature
state<Next>(value): ExtensionBuilderV0<Next, Config, D>;

Request state and bind handles to each collection’s declared schema. Pass the collections alone (state version 1, no migrations) or the full versioned declaration.

Type Parameters
Section titled “Type Parameters”
Type Parameter
Next extends Readonly<Record<string, Readonly<{ schema: Codec<unknown>; bind: (port, name) => CollectionBindingV0; indexFromEncoded: (value) => Result<string | null, SchemaError>; key: (value) => string; index?: (value) => string | null; }>>>
Parameters
Section titled “Parameters”
Parameter Type
value | Next | Readonly<{ version?: number; collections: Next; migrations?: Readonly<Record<number, (row) => readonly Readonly<{ collection: string; key: string; value: Json; }>[]>>; }>
Returns
Section titled “Returns”

ExtensionBuilderV0<Next, Config, D>

documents()

Section titled “documents()”
Signature
documents<Next>(value): ExtensionBuilderV0<S, Config, Next>;

Request bounded Session documents under the state grant.

Type Parameters
Section titled “Type Parameters”
Type Parameter
Next extends Readonly<Record<string, Readonly<{ schema: Codec<unknown>; initial: unknown; fork: DocumentForkPolicyV0; maxBytes: number; }>>>
Parameters
Section titled “Parameters”
Parameter Type
value Next
Returns
Section titled “Returns”

ExtensionBuilderV0<S, Config, Next>

define()

Section titled “define()”
Call Signature
Section titled “Call Signature”
Signature
define<C, P, PI, H>(definition): DefinedExtensionV0<C, P, PI>;

Register commands without a client entry.

Type Parameters
Section titled “Type Parameters”
Type Parameter Default type
C extends Readonly<Record<string, Readonly<{ scope: "session" | "agent"; input: Codec<unknown>; output: Codec<unknown>; }>>> -
P -
PI -
H extends CommandHandlersV0<C> CommandHandlersV0<C>
Parameters
Section titled “Parameters”
Parameter Type
definition Omit<Readonly<{ catalog?: Json; commands?: Readonly<{ specs: C; handlers: (context) => CommandHandlersV0<C>; }>; projection?: Readonly<{ schema: Codec<P, PI>; catalog?: (value) => Json; read: (context, sessionId) => P | Option<P> | undefined; }>; prompt?: (context, run) => | readonly Readonly<{ name: string; text: string; }>[] | Promise<readonly Readonly<{ name: …; text: …; }>[]> | Effect<readonly Readonly<{ name: …; text: …; }>[], HookError, ExtensionRead>; tools?: (context, run, commands) => | Readonly<{ [moduleBrand]: true; }> | Promise< | Readonly<{ [moduleBrand]: …; }> | null> | Effect< | Readonly<{ [moduleBrand]: …; }> | Option<Readonly<…>> | null, HookError, ExtensionRead> | null; files?: (context, run) => | readonly FileTool[] | Promise<readonly FileTool[] | null> | Effect<readonly FileTool[] | Option<readonly …[]> | null, HookError, ExtensionRead> | null; hooks?: Readonly<{ start?: (context) => void | Promise<…> | Effect<…, …, …>; onSettled?: (context, page) => void | Effect<…, …, …>; onTimer?: (context, timer) => void | Effect<…, …, …>; }>; timers?: true; attention?: true; compaction?: (context) => Readonly<{ consume: (view) => | CompactionHandoffResultV0 | Promise<…> | Effect.Effect<…, …>; }>; }>, "commands"> & Readonly<{ commands?: Readonly<{ specs: C; handlers: (context) => CommandHandlersV0<NoInfer<C>> & H & CheckedCommandHandlers<H>; }>; }> & object
Returns
Section titled “Returns”

DefinedExtensionV0<C, P, PI>

Call Signature
Section titled “Call Signature”
Signature
define<P, PI>(definition): DefinedExtensionV0<Readonly<Record<never, never>>, P, PI>;

Register contributions without commands or a client entry.

Type Parameters
Section titled “Type Parameters”
Type Parameter
P
PI
Parameters
Section titled “Parameters”
Parameter Type
definition Omit<Readonly<{ catalog?: Json; commands?: Readonly<{ specs: C; handlers: (context) => CommandHandlersV0<C>; }>; projection?: Readonly<{ schema: Codec<P, PI>; catalog?: (value) => Json; read: (context, sessionId) => P | Option<P> | undefined; }>; prompt?: (context, run) => | readonly Readonly<{ name: string; text: string; }>[] | Promise<readonly Readonly<{ name: …; text: …; }>[]> | Effect<readonly Readonly<{ name: …; text: …; }>[], HookError, ExtensionRead>; tools?: (context, run, commands) => | Readonly<{ [moduleBrand]: true; }> | Promise< | Readonly<{ [moduleBrand]: …; }> | null> | Effect< | Readonly<{ [moduleBrand]: …; }> | Option<Readonly<…>> | null, HookError, ExtensionRead> | null; files?: (context, run) => | readonly FileTool[] | Promise<readonly FileTool[] | null> | Effect<readonly FileTool[] | Option<readonly …[]> | null, HookError, ExtensionRead> | null; hooks?: Readonly<{ start?: (context) => void | Promise<…> | Effect<…, …, …>; onSettled?: (context, page) => void | Effect<…, …, …>; onTimer?: (context, timer) => void | Effect<…, …, …>; }>; timers?: true; attention?: true; compaction?: (context) => Readonly<{ consume: (view) => | CompactionHandoffResultV0 | Promise<…> | Effect.Effect<…, …>; }>; }>, "commands"> & Readonly<{ commands?: Readonly<{ specs: C; handlers: (context) => CommandHandlersV0<NoInfer<Readonly<…>>> & Readonly<Record<never, never>> & CheckedCommandHandlers<Readonly<Record<…, …>>>; }>; }> & object
Returns
Section titled “Returns”

DefinedExtensionV0<Readonly<Record<never, never>>, P, PI>

ExtensionHookErrorclass

Section titled “ExtensionHookError”

An outside handler rejected or threw before Shiitake could use its result.

Extends

Section titled “Extends”
  • YieldableError<this> & object & Readonly<{ cause: unknown; }>

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new ExtensionHookError(args): ExtensionHookError;
Parameters
Section titled “Parameters”
Parameter Type
args { cause: unknown; }
args.cause unknown
Returns
Section titled “Returns”

ExtensionHookError

Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("ExtensionHookError")<{
  cause: unknown;
}>.constructor

Properties

Section titled “Properties”

cause

Section titled “cause”
Signature
cause: unknown;
Inherited from
Section titled “Inherited from”
Signature
Data.TaggedError("ExtensionHookError").cause;

ShiitakeExtensionProtocolV0type alias

Section titled “ShiitakeExtensionProtocolV0”
Signature
type ShiitakeExtensionProtocolV0 = "shiitake.extension/v0";

Host extension protocol; client-entry protocol is versioned independently.

ExtensionIdtype alias

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

ASCII extension identity shared by the server definition and its clients.

ExtensionManifestV0type alias

Section titled “ExtensionManifestV0”
Signature
type ExtensionManifestV0 = Readonly<{
  protocol: ShiitakeExtensionProtocolV0;
  id: ExtensionId;
  version: string;
  requests: readonly ExtensionCapabilityV0[];
}>;

Static identity and requested capabilities of one v0 extension.

CommandSpecV0type alias

Section titled “CommandSpecV0”
Signature
type CommandSpecV0<S, I, II, O, OI> = Readonly<{
  scope: S;
  input: Schema.Codec<I, II>;
  output: Schema.Codec<O, OI>;
}>;

One command’s scope and its encoded input and output schemas.

Type Parameters

Section titled “Type Parameters”
Type Parameter
S extends "session" | "agent"
I
II
O
OI

AnyCommandSpecV0type alias

Section titled “AnyCommandSpecV0”
Signature
type AnyCommandSpecV0 = Readonly<{
  scope: "session" | "agent";
  input: Schema.Codec<unknown>;
  output: Schema.Codec<unknown>;
}>;

Existential command spec.

CommandsV0type alias

Section titled “CommandsV0”
Signature
type CommandsV0 = Readonly<Record<string, AnyCommandSpecV0>>;

Commands declared by one extension contract.

ProjectionSpecV0type alias

Section titled “ProjectionSpecV0”
Signature
type ProjectionSpecV0<P, PI> = Readonly<{
  schema: Schema.Codec<P, PI>;
}>;

The encoded Session projection slot.

Type Parameters

Section titled “Type Parameters”
Type Parameter
P
PI

ExtensionContractV0type alias

Section titled “ExtensionContractV0”
Signature
type ExtensionContractV0<C, P, PI> = Readonly<{
  id: ExtensionId;
  commands: C;
  projection: ProjectionSpecV0<P, PI> | null;
}>;

Shared by the host definition and the client binding: one schema set.

Type Parameters

Section titled “Type Parameters”
Type Parameter
C extends CommandsV0
P
PI

ExtensionRevisiontype alias

Section titled “ExtensionRevision”
Signature
type ExtensionRevision = typeof extensionRevisionSchema.Type;

sha256:<64 hex> derived by core from a definition; never authored.

ExtensionFingerprinttype alias

Section titled “ExtensionFingerprint”
Signature
type ExtensionFingerprint = typeof extensionFingerprintSchema.Type;

sha256:<64 hex> over one revision and its sorted granted capabilities.

Jsontype alias

Section titled “Json”
Signature
type Json =
  | null
  | boolean
  | number
  | string
  | readonly Json[]
  | Readonly<{
      [key: string]: Json;
    }>;

JSON value accepted as hashed extension configuration.

ExtensionGrantV0type alias

Section titled “ExtensionGrantV0”
Signature
type ExtensionGrantV0 = Readonly<{
  id: ExtensionId;
  capabilities: readonly ExtensionCapabilityV0[];
  grantKey?: string;
}>;

Host decision: the exact subset of requested capabilities it grants.

HookErrortype alias

Section titled “HookError”
Signature
type HookError =
  ExtensionStop | ExtensionStateError | AdmissionError | ExtensionHookError;

Failures a background hook may return; each one stops only its extension.

CollectionSpecV0type alias

Section titled “CollectionSpecV0”
Signature
type CollectionSpecV0<A, I> = Readonly<{
  schema: Schema.Codec<A, I>;
  bind: (
    port,
    name,
  ) => Readonly<{
    read: CollectionV0<A>;
    update: UpdateCollectionV0<A>;
  }>;
  indexFromEncoded: (value) => Result.Result<string | null, Schema.SchemaError>;
  key: (value) => string;
  index?: (value) => string | null;
}>;

One namespaced collection: its row schema is the only stored-row decoder.

Type Parameters

Section titled “Type Parameters”
Type Parameter
A
I

AnyCollectionSpecV0type alias

Section titled “AnyCollectionSpecV0”
Signature
type AnyCollectionSpecV0 = Readonly<{
  schema: Schema.Codec<unknown>;
  bind: (port, name) => CollectionBindingV0;
  indexFromEncoded: (value) => Result.Result<string | null, Schema.SchemaError>;
  key: (value) => string;
  index?: (value) => string | null;
}>;

Existential collection spec stored by core.

CollectionsV0type alias

Section titled “CollectionsV0”
Signature
type CollectionsV0 = Readonly<Record<string, AnyCollectionSpecV0>>;

Collections declared by one extension.

StoredRecordV0type alias

Section titled “StoredRecordV0”
Signature
type StoredRecordV0 = Readonly<{
  collection: string;
  key: string;
  value: Json;
}>;

One stored record as seen by a pure migration.

StateSpecV0type alias

Section titled “StateSpecV0”
Signature
type StateSpecV0<C> = Readonly<{
  version: number;
  collections: C;
  migrations: Readonly<Record<number, (row) => readonly StoredRecordV0[]>>;
}>;

Versioned state declaration; core runs pure row migrations at activation.

Type Parameters

Section titled “Type Parameters”
Type Parameter
C extends CollectionsV0

StateDeclarationV0type alias

Section titled “StateDeclarationV0”
Signature
type StateDeclarationV0<C> = Readonly<{
  version?: number;
  collections: C;
  migrations?: StateSpecV0<C>["migrations"];
}>;

The versioned state declaration as authored; version defaults to 1.

Type Parameters

Section titled “Type Parameters”
Type Parameter
C extends CollectionsV0

CollectionV0type alias

Section titled “CollectionV0”
Signature
type CollectionV0<A> = Readonly<{
  peek: (key) => Option.Option<A>;
  peekPage: (query) => readonly A[];
  get: (
    key,
  ) => Effect.Effect<Option.Option<A>, ExtensionStateError, ExtensionRead>;
  page: (
    query,
  ) => Effect.Effect<readonly A[], ExtensionStateError, ExtensionRead>;
  put: (value) => Effect.Effect<void, ExtensionStateError, ExtensionTx>;
  remove: (key) => Effect.Effect<void, ExtensionStateError, ExtensionTx>;
}>;

Typed access to one collection inside a core transaction.

Type Parameters

Section titled “Type Parameters”
Type Parameter
A

UpdateCollectionV0type alias

Section titled “UpdateCollectionV0”
Signature
type UpdateCollectionV0<A> = Readonly<{
  get: (key) => Option.Option<A>;
  page: (query) => readonly A[];
  put: (value) => void;
  remove: (key) => void;
}>;

The transaction-local interface used by plain synchronous state.update.

Type Parameters

Section titled “Type Parameters”
Type Parameter
A

UpdateStateV0type alias

Section titled “UpdateStateV0”
Signature
type UpdateStateV0<C> = {
  readonly [K in keyof C]: ReturnType<C[K]["bind"]>["update"];
} & Readonly<{
  observe: (sessionId) => void;
}>;

Transaction-scoped collections plus post-commit Session notification.

Type Parameters

Section titled “Type Parameters”
Type Parameter
C extends CollectionsV0

ReadStateV0type alias

Section titled “ReadStateV0”
Signature
type ReadStateV0<C> = {
  readonly [K in keyof C]: Pick<
    ReturnType<C[K]["bind"]>["update"],
    "get" | "page"
  >;
};

Synchronous, read-only collection access inside state.read.

Type Parameters

Section titled “Type Parameters”
Type Parameter
C extends CollectionsV0

StateHandleV0type alias

Section titled “StateHandleV0”
Signature
type StateHandleV0<C> = {
  readonly [K in keyof C]: ReturnType<C[K]["bind"]>["read"];
} & Readonly<{
  update: StateUpdate<UpdateStateV0<C>>;
  read: StateUpdate<ReadStateV0<C>>;
}>;

Typed handles for every declared collection.

Type Parameters

Section titled “Type Parameters”
Type Parameter
C extends CollectionsV0

RunOutcomeV0type alias

Section titled “RunOutcomeV0”
Signature
type RunOutcomeV0 =
  "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";

Watchdog settlement or exact Woodstock terminal of one run.

RunOriginV0type alias

Section titled “RunOriginV0”
Signature
type RunOriginV0 = Readonly<{
  extensionId: ExtensionId;
  correlation: string | null;
}>;

Extension that admitted a run, with its stored correlation.

SettledRunV0type alias

Section titled “SettledRunV0”
Signature
type SettledRunV0 = Readonly<{
  sequence: number;
  sessionId: string;
  workId: string;
  outcome: RunOutcomeV0;
  terminal: RunOutcomeV0 | "missing";
  toolCalls: number;
  origin: RunOriginV0 | null;
}>;

One settled run joined by core with its terminal and admission origin.

SettledPageV0type alias

Section titled “SettledPageV0”
Signature
type SettledPageV0 = readonly SettledRunV0[];

1..64 records, ascending, each delivered to each running extension once.

SendInputV0type alias

Section titled “SendInputV0”
Signature
type SendInputV0 = Readonly<{
  sessionId: string;
  requireExistingSession?: boolean;
  prompt: Readonly<{
    text: string;
    requestId: string;
    delivery: "followUp" | "steer";
  }>;
  when: "now" | "idle";
  correlation?: string;
  continuesWorkId?: string;
}>;

One prompt sent through the accepted-command door.

SendResultV0type alias

Section titled “SendResultV0”
Signature
type SendResultV0 =
  | Readonly<{
      _tag: "Accepted";
      commandId: string;
      delivery: "new" | "replay";
    }>
  | Readonly<{
      _tag: "NotReady";
    }>;

Door outcome for one extension admission.

TimersV0type alias

Section titled “TimersV0”
Signature
type TimersV0 = Readonly<{
  set: (key, dueAt) => Effect.Effect<void, ExtensionStateError, ExtensionTx>;
  cancel: (key) => Effect.Effect<void, ExtensionStateError, ExtensionTx>;
  read: (
    key,
  ) => Effect.Effect<Option.Option<number>, ExtensionStateError, ExtensionRead>;
}>;

Durable per-extension wake timers (the scheduling substrate).

FiredTimerV0type alias

Section titled “FiredTimerV0”
Signature
type FiredTimerV0 = Readonly<{
  key: string;
  dueAt: number;
  firedAt: number;
}>;

A fired timer; its row is consumed unless the handler sets it again.

CommandSessionIdsV0type alias

Section titled “CommandSessionIdsV0”
Signature
type CommandSessionIdsV0 = object;

A command’s scope fixes whether its invocation names a Session.

Properties

Section titled “Properties”

agent

Section titled “agent”
Signature
agent: null;

session

Section titled “session”
Signature
session: string;

ExtensionCommandCallerV0type alias

Section titled “ExtensionCommandCallerV0”
Signature
type ExtensionCommandCallerV0 = Readonly<{
  agentId: string;
  sessionId: string;
}>;

Host-authenticated caller context; never decoded from command JSON or HTTP.

CommandHandlersV0type alias

Section titled “CommandHandlersV0”
Signature
type CommandHandlersV0<C> = {
  readonly [K in keyof C]: (
    call: Readonly<{
      sessionId: CommandSessionIdsV0[C[K]["scope"]];
      input: C[K]["input"]["Type"];
      caller?: ExtensionCommandCallerV0;
    }>,
  ) =>
    | C[K]["output"]["Type"]
    | Effect.Effect<
        C[K]["output"]["Type"],
        ExtensionCommandError | ExtensionStateError | AdmissionError,
        ExtensionTx | ExtensionRead
      >;
};

Handlers for every declared command, run in one core transaction.

Type Parameters

Section titled “Type Parameters”
Type Parameter
C extends CommandsV0

AttentionV0type alias

Section titled “AttentionV0”
Signature
type AttentionV0 = Readonly<{
  set: (
    sessionId,
    item,
  ) => Effect.Effect<void, ExtensionStateError, ExtensionTx>;
  awaitsPerson: (
    sessionId,
  ) => Effect.Effect<boolean, ExtensionStateError, ExtensionRead>;
  clear: (
    sessionId,
    id,
  ) => Effect.Effect<void, ExtensionStateError, ExtensionTx>;
}>;

Transaction-scoped, extension-owned attention on an existing Session.

ExtensionContextV0type alias

Section titled “ExtensionContextV0”
Signature
type ExtensionContextV0<S, Config, D> = Readonly<{
  manifest: ExtensionManifestV0;
  revision: ExtensionRevision;
  grants: readonly ExtensionCapabilityV0[];
  config: Config;
  state: StateHandleV0<S>;
  documents: DocumentHandlesV0<D>;
  send: (input) => Effect.Effect<SendResultV0, AdmissionError, ExtensionTx>;
  timers: TimersV0;
  attention: AttentionV0;
  sessionPosition: (
    sessionId,
  ) => Effect.Effect<number, ExtensionStateError, ExtensionRead>;
  hasPendingSteer: (
    run,
  ) => Effect.Effect<boolean, ExtensionStateError, ExtensionRead>;
  workSender: (
    run,
  ) => Effect.Effect<
    AttentionRecipient | null,
    ExtensionStateError,
    ExtensionRead
  >;
  hasSuccessfulToolResult: (
    run,
    toolCallId,
  ) => Effect.Effect<boolean, ExtensionStateError, ExtensionRead>;
  observe: (sessionId) => Effect.Effect<void, never, ExtensionTx>;
  isObserved: (sessionId) => boolean;
  transact: <A, E>(body) => Effect.Effect<A, E | ExtensionStop | ShiitakeError>;
}>;

Everything core hands one activated extension.

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
S extends CollectionsV0 -
Config extends Json -
D extends DocumentsV0 DocumentsV0

RunIdentityV0type alias

Section titled “RunIdentityV0”
Signature
type RunIdentityV0 = Readonly<{
  sessionId: string;
  workId: string;
  origin: RunOriginV0 | null;
}>;

One run the extension may attach tools to.

PromptSectionV0type alias

Section titled “PromptSectionV0”
Signature
type PromptSectionV0 = Readonly<{
  name: string;
  text: string;
}>;

A named, bounded system-prompt section; core orders by extension and name.

AgentHooksV0type alias

Section titled “AgentHooksV0”
Signature
type AgentHooksV0<C, P> = Readonly<{
  onSettled?: (
    page,
  ) => Effect.Effect<void, HookError, ExtensionTx | ExtensionRead>;
  onTimer?: (
    timer,
  ) => Effect.Effect<void, HookError, ExtensionTx | ExtensionRead>;
  moduleForRun?: (
    run,
  ) => Effect.Effect<
    Option.Option<ModuleRegistration>,
    HookError,
    ExtensionRead
  >;
  filesForRun?: (
    run,
  ) => Effect.Effect<
    Option.Option<readonly FileTool[]>,
    HookError,
    ExtensionRead
  >;
  prompt?: (
    run,
  ) =>
    | readonly PromptSectionV0[]
    | Promise<readonly PromptSectionV0[]>
    | Effect.Effect<readonly PromptSectionV0[], HookError, ExtensionRead>;
  project?: (sessionId) => Option.Option<P>;
  compactionHandoff?: CompactionHandoffV0;
  commands: CommandHandlersV0<C>;
}>;

Hooks returned by one activation; each runs in its own isolation boundary.

Type Parameters

Section titled “Type Parameters”
Type Parameter
C extends CommandsV0
P

RosteredExtensionV0type alias

Section titled “RosteredExtensionV0”
Signature
type RosteredExtensionV0 = Readonly<{
  manifest: ExtensionManifestV0;
  [definitionReader]?: () => AnyExtensionDefinitionV0;
}> &
  Brand.Brand<"RosteredExtensionV0">;

Opaque rostered value; core reads the definition existentially.

DefinedExtensionV0type alias

Section titled “DefinedExtensionV0”
Signature
type DefinedExtensionV0<C, P, PI> = RosteredExtensionV0 &
  Readonly<{
    contract: ExtensionContractV0<C, P, PI>;
  }>;

A defined extension: its roster entry and the client contract it declares.

Type Parameters

Section titled “Type Parameters”
Type Parameter
C extends CommandsV0
P
PI

ExtensionDefinitionV0type alias

Section titled “ExtensionDefinitionV0”
Signature
type ExtensionDefinitionV0<S, C, P, PI, Config, D> = Readonly<{
  catalog?: Json;
  commands?: Readonly<{
    specs: C;
    handlers: (context) => CommandHandlersV0<C>;
  }>;
  projection?: Readonly<{
    schema: Schema.Codec<P, PI>;
    catalog?: (value) => Json;
    read: (context, sessionId) => P | Option.Option<P> | undefined;
  }>;
  prompt?: (
    context,
    run,
  ) =>
    | readonly PromptSectionV0[]
    | Promise<readonly PromptSectionV0[]>
    | Effect.Effect<readonly PromptSectionV0[], HookError, ExtensionRead>;
  tools?: (
    context,
    run,
    commands,
  ) =>
    | ModuleRegistration
    | null
    | Promise<ModuleRegistration | null>
    | Effect.Effect<
        ModuleRegistration | null | Option.Option<ModuleRegistration>,
        HookError,
        ExtensionRead
      >;
  files?: (
    context,
    run,
  ) =>
    | readonly FileTool[]
    | null
    | Promise<readonly FileTool[] | null>
    | Effect.Effect<
        readonly FileTool[] | null | Option.Option<readonly FileTool[]>,
        HookError,
        ExtensionRead
      >;
  hooks?: Readonly<{
    start?: (
      context,
    ) =>
      | void
      | Promise<void>
      | Effect.Effect<void, ExtensionActivationError, Scope.Scope>;
    onSettled?: (
      context,
      page,
    ) => void | Effect.Effect<void, HookError, ExtensionTx | ExtensionRead>;
    onTimer?: (
      context,
      timer,
    ) => void | Effect.Effect<void, HookError, ExtensionTx | ExtensionRead>;
  }>;
  timers?: true;
  attention?: true;
  compaction?: (context) => Readonly<{
    consume: (
      view,
    ) =>
      | CompactionHandoffResultV0
      | Promise<CompactionHandoffResultV0>
      | Effect.Effect<
          CompactionHandoffResultV0,
          CompactionHandoffErrorV0 | ExtensionHookError
        >;
  }>;
}>;

Contributions registered against the builder’s captured metadata.

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
S extends CollectionsV0 -
C extends CommandsV0 -
P -
PI -
Config extends Json -
D extends DocumentsV0 DocumentsV0

CheckedCommandHandlerstype alias

Section titled “CheckedCommandHandlers”
Signature
type CheckedCommandHandlers<H> = {
  readonly [K in keyof H]: H[K] extends (args: never[]) => infer Result
    ? Result extends Promise<unknown>
      ? never
      : H[K]
    : never;
};

Reject Promise-returning transactional commands even when output is {}.

Type Parameters

Section titled “Type Parameters”
Type Parameter
H

ExtensionAuthorDefinitionV0type alias

Section titled “ExtensionAuthorDefinitionV0”
Signature
type ExtensionAuthorDefinitionV0<S, C, P, PI, Config, D, H> = Omit<
  ExtensionDefinitionV0<S, C, P, PI, Config, D>,
  "commands"
> &
  Readonly<{
    commands?: Readonly<{
      specs: C;
      handlers: (
        context,
      ) => CommandHandlersV0<NoInfer<C>> & H & CheckedCommandHandlers<H>;
    }>;
  }>;

Caller-owned extension metadata and handlers accepted by the v0 builder.

Type Parameters

Section titled “Type Parameters”
Type Parameter
S extends CollectionsV0
C extends CommandsV0
P
PI
Config extends Json
D extends DocumentsV0
H extends CommandHandlersV0<C>

EmptyExtensionFieldsV0type alias

Section titled “EmptyExtensionFieldsV0”
Signature
type EmptyExtensionFieldsV0 = Readonly<Record<never, never>>;

Concrete metadata with no declared fields.

ExtensionIdentityV0type alias

Section titled “ExtensionIdentityV0”
Signature
type ExtensionIdentityV0 =
  | string
  | Readonly<{
      id: string;
      version?: string;
    }>;

An extension id, or an id with an explicit SemVer version.

AnyAgentHooksV0type alias

Section titled “AnyAgentHooksV0”
Signature
type AnyAgentHooksV0 = Readonly<{
  onSettled?: NonNullable<AgentHooksV0<CommandsV0, never>["onSettled"]>;
  onTimer?: NonNullable<AgentHooksV0<CommandsV0, never>["onTimer"]>;
  moduleForRun?: NonNullable<AgentHooksV0<CommandsV0, never>["moduleForRun"]>;
  filesForRun?: NonNullable<AgentHooksV0<CommandsV0, never>["filesForRun"]>;
  prompt?: NonNullable<AgentHooksV0<CommandsV0, never>["prompt"]>;
  project?: (sessionId) => Option.Option<unknown>;
  projectCatalog?: (value) => Json;
  compactionHandoff?: CompactionHandoffV0;
  commands: ReadonlyMap<string, RegisteredExtensionCommandV0>;
}>;

Existential hooks as stored by core; each handler is re-typed by its schema.

AnyExtensionDefinitionV0type alias

Section titled “AnyExtensionDefinitionV0”
Signature
type AnyExtensionDefinitionV0 = Readonly<{
  manifest: ExtensionManifestV0;
  contract: Readonly<{
    id: ExtensionId;
    commands: CommandsV0;
    projection: Readonly<{
      schema: Schema.Codec<unknown>;
    }> | null;
  }>;
  config: Json;
  state: StateSpecV0<CollectionsV0>;
  documents?: DocumentsV0;
  catalog?: Json;
  activate: (
    port,
  ) => Effect.Effect<
    AnyAgentHooksV0,
    ExtensionActivationError | ExtensionHookError,
    Scope.Scope
  >;
}>;

Existential definition stored by core.

ExtensionRosterV0type alias

Section titled “ExtensionRosterV0”
Signature
type ExtensionRosterV0 = Readonly<{
  roster: readonly RosteredExtensionV0[];
  grants: readonly ExtensionGrantV0[];
}>;

A host’s explicit roster and grants.

ExtensionStatusV0type alias

Section titled “ExtensionStatusV0”
Signature
type ExtensionStatusV0 = Readonly<{
  id: string;
  version: string;
  revision: string;
  status: "running" | "stopped";
  reason: string | null;
  stoppedAt: number | null;
}>;

Visible lifecycle of one rostered extension (wire representation).

ExtensionSlotV0type alias

Section titled “ExtensionSlotV0”
Signature
type ExtensionSlotV0 =
  | Readonly<{
      status: "running";
      revision: string;
      value: Json;
      catalog?: Json;
    }>
  | Readonly<{
      status: "stopped";
      revision: string;
      reason: string;
    }>;

One extension’s encoded slot in a Session snapshot or frame.

BorrowedCompactionViewV0type alias

Section titled “BorrowedCompactionViewV0”
Signature
type BorrowedCompactionViewV0 = Readonly<{
  sessionId: string;
  messagesToSummarize: readonly Message[];
  turnPrefixMessages: readonly Message[];
  result: Readonly<{
    summary: string;
    firstKeptEntryId: string;
    tokensBefore: number;
    usage: Usage;
    details?: Readonly<{
      readFiles: readonly string[];
      modifiedFiles: readonly string[];
    }>;
  }>;
  contextRevision: string;
}>;

Borrowed view of the exact objects already built for compaction.

CompactionHandoffResultV0type alias

Section titled “CompactionHandoffResultV0”
Signature
type CompactionHandoffResultV0 =
  | Readonly<{
      type: "accepted";
      receipt: string;
    }>
  | Readonly<{
      type: "discarded_by_policy";
    }>;

Result returned before a borrowed compaction view may be released.

CompactionHandoffErrorV0type alias

Section titled “CompactionHandoffErrorV0”
Signature
type CompactionHandoffErrorV0 = Readonly<{
  _tag: "CompactionHandoffError";
  message: string;
}>;

Typed failure returned by the compaction contribution.

CompactionHandoffV0type alias

Section titled “CompactionHandoffV0”
Signature
type CompactionHandoffV0 = Readonly<{
  consume: (
    view,
  ) => Effect.Effect<
    CompactionHandoffResultV0,
    CompactionHandoffErrorV0 | ExtensionHookError
  >;
}>;

The exclusive compaction handoff callable of one extension.

RegisteredExtensionCommandV0type alias

Section titled “RegisteredExtensionCommandV0”
Signature
type RegisteredExtensionCommandV0 = (
  frame,
) => Result.Result<
  () => Effect.Effect<
    Json,
    ExtensionCommandError | ExtensionStateError | AdmissionError,
    ExtensionTx | ExtensionRead
  >,
  Schema.SchemaError
>;

A parsed invocation retains its typed handler until the transaction runs.

Parameters

Section titled “Parameters”
Parameter Type
frame Readonly<{ sessionId: string | null; input: Json; caller?: ExtensionCommandCallerV0; }>

Returns

Section titled “Returns”

Result.Result<() => Effect.Effect<Json, | ExtensionCommandError | ExtensionStateError | AdmissionError, ExtensionTx | ExtensionRead>, Schema.SchemaError>

CommandToolOptionsV0type alias

Section titled “CommandToolOptionsV0”
Signature
type CommandToolOptionsV0 = Readonly<{
  description: string;
}>;

How one command appears to the model when exposed as a tool.

CommandToolsV0type alias

Section titled “CommandToolsV0”
Signature
type CommandToolsV0<C> = Readonly<{
  tool: (name, options) => OperationRegistration;
}>;

Expose declared commands as model tools, bound to the current run’s Session.

Type Parameters

Section titled “Type Parameters”
Type Parameter
C extends CommandsV0

CollectionBindingV0type alias

Section titled “CollectionBindingV0”
Signature
type CollectionBindingV0 = Readonly<{
  read: Omit<CollectionV0<unknown>, "put"> & Pick<CollectionV0<never>, "put">;
  update: Omit<UpdateCollectionV0<unknown>, "put"> &
    Pick<UpdateCollectionV0<never>, "put">;
}>;

Core retains only these erased results; the author retains each concrete factory.

ExtensionRuntimePortV0type alias

Section titled “ExtensionRuntimePortV0”
Signature
type ExtensionRuntimePortV0 = Readonly<{
  context: Omit<
    ExtensionContextV0<EmptyExtensionFieldsV0, Json, EmptyExtensionFieldsV0>,
    "config" | "state" | "documents"
  >;
  collection: <A, I>(name, spec) => CollectionV0<A>;
  updateCollection: <A, I>(name, spec) => UpdateCollectionV0<A>;
  document: <A, I>(name, spec) => DocumentHandleV0<A>;
  update: <A>(body) => A;
  observeUpdate: (sessionId) => void;
}>;

State operations capture their typed declaration before entering core.

SyncResulttype alias

Section titled “SyncResult”
Signature
type SyncResult<A> =
  A extends Option.Option<unknown>
    ? A
    : A extends Promise<unknown> | Effect.Effect<unknown, unknown, unknown>
      ? never
      : A;

A write callback must resolve before the owner commits its SQLite transaction.

Type Parameters

Section titled “Type Parameters”
Type Parameter
A

StateUpdatetype alias

Section titled “StateUpdate”
Signature
type StateUpdate<Tx> = <A>(handler) => A;

Public state-update shape: infer the return before rejecting async results.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Tx

Type Parameters

Section titled “Type Parameters”
Type Parameter
A

Parameters

Section titled “Parameters”
Parameter Type
handler (tx) => SyncResult<A>

Returns

Section titled “Returns”

A

AttentionRecipienttype alias

Section titled “AttentionRecipient”
Signature
type AttentionRecipient = typeof AttentionRecipientSchema.Type;

Decoded Agent Session an attention item waits on.

AttentionItemtype alias

Section titled “AttentionItem”
Signature
type AttentionItem = typeof AttentionItemSchema.Type;

Input to the granted attention door, scoped to the calling extension.

extensionIdentifierconstant

Section titled “extensionIdentifier”
Signature
const extensionIdentifier: String;

ASCII extension identity shared by the host definition and its clients.

extensionVersionconstant

Section titled “extensionVersion”
Signature
const extensionVersion: String;

SemVer spelling used by host admission.

ExtensionIdconstant

Section titled “ExtensionId”
Signature
const ExtensionId: brand<String, "ExtensionId">;

ASCII extension identity shared by the host definition and its clients.

AttentionRecipientSchemaconstant

Section titled “AttentionRecipientSchema”
Signature
const AttentionRecipientSchema: Struct<{
  agentId: NonEmptyString;
  sessionId: NonEmptyString;
  name: NonEmptyString;
}>;

The Agent Session that sent the work an item belongs to. The host derives it from the accepted mail; it is the only party the item waits on until it is escalated.

AttentionItemSchemaconstant

Section titled “AttentionItemSchema”
Signature
const AttentionItemSchema: Struct<{
  id: NonEmptyString;
  kind: NonEmptyString;
  summary: NonEmptyString;
  since: Int;
  expiresAt: optional<Int>;
  inbox: optional<Literal<false>>;
  waitingOn: optional<
    Struct<{
      agentId: NonEmptyString;
      sessionId: NonEmptyString;
      name: NonEmptyString;
    }>
  >;
}>;

An extension-owned request for human attention; expiry is owned by its timer. Items marked inbox: false remain visible without changing the inbox state. An item with waitingOn waits on that Agent first and is never a person’s inbox item until it is escalated past every Agent.

parseExtensionJson()function

Section titled “parseExtensionJson()”
Signature
function parseExtensionJson(source): Json;

Parse a serialized extension value into the finite JSON contract.

Parameters

Section titled “Parameters”
Parameter Type
source string

Returns

Section titled “Returns”

Json

defineExtension()function

Section titled “defineExtension()”
Signature
function defineExtension(
  identity,
): ExtensionBuilderV0<
  Readonly<Record<never, never>>,
  Readonly<Record<never, never>>,
  Readonly<Record<never, never>>
>;

Begin with honest empty defaults; optional contributions are declared explicitly. The version defaults to 0.0.0 and any SemVer, including a pre-release, is valid. It is part of the extension’s revision, which already covers schemas, config and requested capabilities; a different version marks a behaviour change those do not show, such as a fixed hook.

Parameters

Section titled “Parameters”
Parameter Type
identity ExtensionIdentityV0

Returns

Section titled “Returns”

ExtensionBuilderV0<Readonly<Record<never, never>>, Readonly<Record<never, never>>, Readonly<Record<never, never>>>

defineCollection()function

Section titled “defineCollection()”
Signature
function defineCollection<A, I>(schema, keys): CollectionSpecV0<A, I>;

Declare one collection with its key inferred from the row schema.

Type Parameters

Section titled “Type Parameters”
Type Parameter
A
I

Parameters

Section titled “Parameters”
Parameter Type
schema Codec<A, I>
keys Readonly<{ key: (value) => string; index?: (value) => string | null; }>

Returns

Section titled “Returns”

CollectionSpecV0<A, I>

References

Section titled “References”

SessionAttention

Section titled “SessionAttention”

Re-exports SessionAttention

ClientActivityStateV0

Section titled “ClientActivityStateV0”

Re-exports ClientActivityStateV0

ClientActivityV0

Section titled “ClientActivityV0”

Re-exports ClientActivityV0

ExtensionCapabilityV0

Section titled “ExtensionCapabilityV0”

Re-exports ExtensionCapabilityV0