extensions

@fungi.computer/shiitake

@fungi.computer/shiitake / extensions

extensions

Classes

ExtensionRead

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

Extends

TagClassShape<"@fungi.computer/shiitake/ExtensionRead", Readonly<{ extensionId: string & Brand<"ExtensionId">; }>, this>

Constructors

Constructor

new ExtensionRead(_): ExtensionRead

Parameters

_

never

Returns

ExtensionRead

Inherited from

Context.Tag( "@fungi.computer/shiitake/ExtensionRead", )<ExtensionRead, Readonly<{ extensionId: ExtensionId }>>().constructor

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

TagClassShape<"@fungi.computer/shiitake/ExtensionTx", Readonly<{ extensionId: string & Brand<"ExtensionId">; }>, this>

Constructors

Constructor

new ExtensionTx(_): ExtensionTx

Parameters

_

never

Returns

ExtensionTx

Inherited from

Context.Tag( "@fungi.computer/shiitake/ExtensionTx", )<ExtensionTx, Readonly<{ extensionId: ExtensionId }>>().constructor

ExtensionStateError

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

Extends

YieldableError<this> & object & Readonly<{ reason: "decode" | "encode" | "bound" | "unavailable"; message: string; }>

Constructors

Constructor

new ExtensionStateError(args): ExtensionStateError

Parameters

args

reason

"decode" | "encode" | "bound" | "unavailable"

message

string

Returns

ExtensionStateError

Inherited from

Data.TaggedError( “ExtensionStateError”, )<{ reason: “decode” | “encode” | “bound” | “unavailable”; message: string; }>.constructor

Properties

reason

readonly reason: "decode" | "encode" | "bound" | "unavailable"

Inherited from

Data.TaggedError( "ExtensionStateError", ).reason

message

message: string

Inherited from

Data.TaggedError( "ExtensionStateError", ).message

AdmissionError

The door refused an extension admission.

Extends

YieldableError<this> & object & Readonly<{ reason: "invalid" | "conflict" | "closed"; message: string; }>

Constructors

Constructor

new AdmissionError(args): AdmissionError

Parameters

args

reason

"invalid" | "conflict" | "closed"

message

string

Returns

AdmissionError

Inherited from

Data.TaggedError(“AdmissionError”)<{ reason: “invalid” | “conflict” | “closed”; message: string; }>.constructor

Properties

reason

readonly reason: "invalid" | "conflict" | "closed"

Inherited from

Data.TaggedError("AdmissionError").reason

message

message: string

Inherited from

Data.TaggedError("AdmissionError").message

ExtensionCommandError

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

Extends

YieldableError<this> & object & Readonly<{ reason: "invalid" | "conflict" | "not_found" | "rejected"; message: string; }>

Constructors

Constructor

new ExtensionCommandError(args): ExtensionCommandError

Parameters

args

reason

"invalid" | "conflict" | "not_found" | "rejected"

message

string

Returns

ExtensionCommandError

Inherited from

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

Properties

reason

readonly reason: "invalid" | "conflict" | "not_found" | "rejected"

Inherited from

Data.TaggedError( "ExtensionCommandError", ).reason

message

message: string

Inherited from

Data.TaggedError( "ExtensionCommandError", ).message

ExtensionStop

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

Extends

YieldableError<this> & object & Readonly<{ reason: string; }>

Constructors

Constructor

new ExtensionStop(args): ExtensionStop

Parameters

args

reason

string

Returns

ExtensionStop

Inherited from

Data.TaggedError("ExtensionStop")<{ reason: string; }>.constructor

Properties

reason

readonly reason: string

Inherited from

Data.TaggedError("ExtensionStop").reason

ExtensionActivationError

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

Extends

YieldableError<this> & object & Readonly<{ message: string; }>

Constructors

Constructor

new ExtensionActivationError(args): ExtensionActivationError

Parameters

args

message

string

Returns

ExtensionActivationError

Inherited from

Data.TaggedError( "ExtensionActivationError", )<{ message: string }>.constructor

Properties

message

message: string

Inherited from

Data.TaggedError( "ExtensionActivationError", ).message

Type Aliases

ExtensionId

ExtensionId = Schema.Schema.Type<typeof ExtensionId>>

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

ExtensionRevision

ExtensionRevision = string & Brand.Brand<"ExtensionRevision">>

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

ExtensionFingerprint

ExtensionFingerprint = string & Brand.Brand<"ExtensionFingerprint">>

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

Json

Json = null | boolean | number | string | readonly Json[] | Readonly<{[key: string]: Json; }>

JSON value accepted as hashed extension configuration.

ExtensionCapabilityV1

ExtensionCapabilityV1 = "state" | "settled" | "admit" | "timers" | "commands" | "projection" | "run_tools" | "compaction_handoff"

Closed, versioned, feature-free capability vocabulary.

ExtensionManifestV1

ExtensionManifestV1 = Readonly<{ protocol: "shiitake.extension/v1"; id: ExtensionId; version: string; requests: readonly ExtensionCapabilityV1[]; }>

Static identity and requested capabilities of one v1 extension.

ExtensionGrantV1

ExtensionGrantV1 = Readonly<{ id: ExtensionId; capabilities: readonly ExtensionCapabilityV1[]; }>

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

HookError

HookError = ExtensionStop | ExtensionStateError | AdmissionError

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

CollectionSpecV1

CollectionSpecV1<A, I> > = Readonly<{ schema: Schema.Schema<A, I>>; key: (value) => string; index?: (value) => string | null; }>

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

Type Parameters

A

A

I

I

AnyCollectionSpecV1

AnyCollectionSpecV1 = Readonly<{ schema: Schema.Schema.AnyNoContext; key: (value) => string; index?: (value) => string | null; }>

Existential collection spec stored by core.

CollectionsV1

CollectionsV1 = Readonly<Record<string, AnyCollectionSpecV1>>>>

Collections declared by one extension.

StoredRecordV1

StoredRecordV1 = Readonly<{ collection: string; key: string; value: Json; }>

One stored record as seen by a pure migration.

StateSpecV1

StateSpecV1<C> > = Readonly<{ version: number; collections: C; migrations: Readonly<Record<number, (row) => readonly StoredRecordV1[]>>; }>

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

Type Parameters

C

C extends CollectionsV1

CollectionV1

CollectionV1<A> > = Readonly<{ 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

A

A

StateHandleV1

StateHandleV1<C> > = { readonly [K in keyof C]: CollectionV1<Schema.Schema.Type<C[K]["schema"]>> }

Typed handles for every declared collection.

Type Parameters

C

C extends CollectionsV1

RunOutcomeV1

RunOutcomeV1 = "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown"

Watchdog settlement or exact Woodstock terminal of one run.

RunOriginV1

RunOriginV1 = Readonly<{ extensionId: ExtensionId; correlation: string | null; }>

Extension that admitted a run, with its stored correlation.

SettledRunV1

SettledRunV1 = Readonly<{ sequence: number; sessionId: string; workId: string; outcome: RunOutcomeV1; terminal: RunOutcomeV1 | "missing"; origin: RunOriginV1 | null; }>

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

SettledPageV1

SettledPageV1 = readonly SettledRunV1[]

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

AdmitInputV1

AdmitInputV1 = Readonly<{ sessionId: string; prompt: Readonly<{ text: string; requestId: string; delivery: "followUp" | "steer"; }>; when: "now" | "idle"; correlation?: string; }>

One prompt admitted through the accepted-command door.

AdmitResultV1

AdmitResultV1 = Readonly<{ _tag: "Accepted"; commandId: string; delivery: "new" | "replay"; }> | Readonly<{ _tag: "NotReady"; }>

Door outcome for one extension admission.

TimersV1

TimersV1 = 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).

FiredTimerV1

FiredTimerV1 = Readonly<{ key: string; dueAt: number; firedAt: number; }>

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

CommandSpecV1

CommandSpecV1<S, I, II, O, OI> > = Readonly<{ scope: S; input: Schema.Schema<I, II>>; output: Schema.Schema<O, OI>>; }>

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

Type Parameters

S

S extends "session" | "agent"

I

I

II

II

O

O

OI

OI

AnyCommandSpecV1

AnyCommandSpecV1 = Readonly<{ scope: "session" | "agent"; input: Schema.Schema.AnyNoContext; output: Schema.Schema.AnyNoContext; }>

Existential command spec.

CommandsV1

CommandsV1 = Readonly<Record<string, AnyCommandSpecV1>>>>

Commands declared by one extension contract.

CommandHandlersV1

CommandHandlersV1<C> > = { readonly [K in keyof C]: (call: Readonly<{ sessionId: C[K][“scope”] extends “session” ? string : null; input: Schema.Schema.Type<C[K][“input”]> }>) => Effect.Effect<Schema.Schema.Type<C[K][“output”]>, ExtensionCommandError | ExtensionStateError | AdmissionError, ExtensionTx | ExtensionRead> }

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

Type Parameters

C

C extends CommandsV1

ProjectionSpecV1

ProjectionSpecV1<P, PI> > = Readonly<{ schema: Schema.Schema<P, PI>>; }>

The encoded Session projection slot.

Type Parameters

P

P

PI

PI

ExtensionContractV1

ExtensionContractV1<C, P, PI> > = Readonly<{ id: ExtensionId; commands: C; projection: ProjectionSpecV1<P, PI> > | null; }>

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

Type Parameters

C

C extends CommandsV1

P

P

PI

PI

ExtensionContextV1

ExtensionContextV1<S, Config> > = Readonly<{ manifest: ExtensionManifestV1; revision: ExtensionRevision; grants: readonly ExtensionCapabilityV1[]; config: Config; state: StateHandleV1<S>>; admit: (input) => Effect.Effect<AdmitResultV1, AdmissionError, ExtensionTx>>; timers: TimersV1; observe: (sessionId) => Effect.Effect<void, never, ExtensionTx>>; transact: <A, E>>(body) => Effect.Effect<A, E | ExtensionStop>>; }>

Everything core hands one activated extension.

Type Parameters

S

S extends CollectionsV1

Config

Config extends Json

RunIdentityV1

RunIdentityV1 = Readonly<{ sessionId: string; workId: string; origin: RunOriginV1 | null; }>

One run the extension may attach tools to.

AgentHooksV1

AgentHooksV1<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>>; project?: (sessionId) => Effect.Effect<Option.Option<P>>, HookError, ExtensionRead>>; compactionHandoff?: CompactionHandoffV1; commands: CommandHandlersV1<C>>; }>

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

Type Parameters

C

C extends CommandsV1

P

P

ShiitakeExtensionV1

ShiitakeExtensionV1<S, C, P, PI, Config> > = Readonly<{ manifest: ExtensionManifestV1; contract: ExtensionContractV1<C, P, PI>>; config: Config; state: StateSpecV1<S>>; activate: (context) => Effect.Effect<AgentHooksV1<NoInfer<C>>, NoInfer<P>>>>, ExtensionActivationError, Scope.Scope>>; }>

One trusted v1 extension definition.

Type Parameters

S

S extends CollectionsV1

C

C extends CommandsV1

P

P

PI

PI

Config

Config extends Json

RosteredExtensionV1

RosteredExtensionV1 = Readonly<{ manifest: ExtensionManifestV1; }> & Brand.Brand<"RosteredExtensionV1">>

Opaque rostered value; core reads the definition existentially.

AnyAgentHooksV1

AnyAgentHooksV1 = Readonly<{ onSettled?: NonNullable<AgentHooksV1<CommandsV1, never>>["onSettled"]>; onTimer?: NonNullable<AgentHooksV1<CommandsV1, never>>["onTimer"]>; moduleForRun?: NonNullable<AgentHooksV1<CommandsV1, never>>["moduleForRun"]>; project?: (sessionId) => Effect.Effect<Option.Option<unknown>>, HookError, ExtensionRead>>; compactionHandoff?: CompactionHandoffV1; commands: Readonly<Record<string, (call) => Effect.Effect<unknown, ExtensionCommandError | ExtensionStateError | AdmissionError, ExtensionTx | ExtensionRead>>>>>>; }>

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

AnyExtensionDefinitionV1

AnyExtensionDefinitionV1 = Readonly<{ manifest: ExtensionManifestV1; contract: Readonly<{ id: ExtensionId; commands: CommandsV1; projection: Readonly<{ schema: Schema.Schema.AnyNoContext; }> | null; }>; config: Json; state: StateSpecV1<CollectionsV1>>; activate: (context) => Effect.Effect<AnyAgentHooksV1, ExtensionActivationError, Scope.Scope>>; }>

Existential definition stored by core.

ExtensionRosterV1

ExtensionRosterV1 = Readonly<{ roster: readonly RosteredExtensionV1[]; grants: readonly ExtensionGrantV1[]; permitRunTools?: (input) => boolean; }>

A host’s explicit roster and grants.

ExtensionStatusV1

ExtensionStatusV1 = Readonly<{ id: string; version: string; revision: string; status: "running" | "stopped"; reason: string | null; stoppedAt: number | null; }>

Visible lifecycle of one rostered extension (wire representation).

ExtensionSlotV1

ExtensionSlotV1 = Readonly<{ status: "running"; revision: string; value: Json; }> | Readonly<{ status: "stopped"; revision: string; reason: string; }>

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

BorrowedCompactionViewV1

BorrowedCompactionViewV1 = Readonly<{ 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.

CompactionHandoffResultV1

CompactionHandoffResultV1 = Readonly<{ type: "accepted"; receipt: string; }> | Readonly<{ type: "discarded_by_policy"; }>

Result returned before a borrowed compaction view may be released.

CompactionHandoffErrorV1

CompactionHandoffErrorV1 = Readonly<{ _tag: "CompactionHandoffError"; message: string; }>

Typed failure returned by the compaction contribution.

CompactionHandoffV1

CompactionHandoffV1 = Readonly<{ consume: (view) => Effect.Effect<CompactionHandoffResultV1, CompactionHandoffErrorV1>>; }>

The exclusive compaction handoff callable of one extension.

Variables

ExtensionId

const ExtensionId: brand<filter<filter<filter<typeof String$>>>>>>, "ExtensionId">>

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

Functions

defineExtension()

defineExtension<S, C, P, PI, Config>>(definition): RosteredExtensionV1

Freeze one definition into an opaque roster entry.

Type Parameters

S

S extends Readonly<Record<string, Readonly<{ schema: AnyNoContext; key: (value) => string; index?: (value) => string | null; }>>>

C

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

P

P

PI

PI

Config

Config extends Json

Parameters

definition

ShiitakeExtensionV1<S, C, P, PI, Config>

Returns

RosteredExtensionV1

defineCollection()

defineCollection<A, I>>(schema, keys): CollectionSpecV1<A, I>>

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

Type Parameters

A

A

I

I

Parameters

schema

Schema<A, I>

keys

Readonly<{ key: (value) => string; index?: (value) => string | null; }>

Returns

CollectionSpecV1<A, I>