@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/docs/api/effect.md

@@ -0,0 +1,884 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / effect
+
+# effect
+
+## Type Aliases
+
+### ShiitakeEffectHost
+
+```ts
+type ShiitakeEffectHost = Readonly<{
+  readSettlement: (
+    sessionId,
+    commandId,
+  ) => Effect.Effect<CommandSettlement | undefined, ShiitakeError>;
+  agent: ShiitakeEffectOwner;
+  acceptMail: (mail, meta?, reply?) => Effect.Effect<Accepted, ShiitakeError>;
+}>;
+```
+
+Effect-native host composition with addressed mail kept off Session.
+
+---
+
+### ModelAcquisitionEffect
+
+```ts
+type ModelAcquisitionEffect = Readonly<{
+  model: Model<Api>;
+  stream?: MuleStreamFunction;
+  retryAfterMs?: (message) => number | undefined;
+  release: Effect.Effect<void, ShiitakeError>;
+}>;
+```
+
+Effect-native acquired Pi model and finalizer.
+
+---
+
+### ModelSourceEffect
+
+```ts
+type ModelSourceEffect = Readonly<{
+  acquire: (input) => Effect.Effect<ModelAcquisitionEffect, ShiitakeError>;
+  describe?: (input) => Effect.Effect<ModelDescription, ShiitakeError>;
+}>;
+```
+
+Effect-native model acquisition owner.
+
+---
+
+### InstructionSourceEffect
+
+```ts
+type InstructionSourceEffect = Readonly<{
+  load: (
+    input,
+  ) => Effect.Effect<InstructionSnapshot, ShiitakeError, Scope.Scope>;
+}>;
+```
+
+Effect-native instruction snapshot owner.
+
+---
+
+### ToolSourceEffect
+
+```ts
+type ToolSourceEffect = Readonly<{
+  execution?: ExecutionOptions;
+  modules: readonly ModuleRegistration[];
+  sources: readonly CapabilitySource[];
+  sandbox: Sandbox;
+  access?: ToolAccess;
+}>;
+```
+
+Effect-native Mycelium construction inputs.
+
+---
+
+### RuntimeHostEffect
+
+```ts
+type RuntimeHostEffect = Readonly<{
+  bind: (input) => Effect.Effect<
+    Readonly<{
+      commit: <A>(mutation) => Effect.Effect<A, ShiitakeError>;
+      requestWake: Effect.Effect<void, ShiitakeError>;
+      close: Effect.Effect<void, ShiitakeError>;
+    }>,
+    ShiitakeError
+  >;
+}>;
+```
+
+Effect-native owner for scheduling the opaque durable reconciler.
+
+---
+
+### ShiitakeEffectOptions
+
+```ts
+type ShiitakeEffectOptions = Readonly<{
+  meta?: HostMetaOptions;
+  store: SqliteOwner;
+  storageBudget?: StorageBudget;
+  compaction?: CompactionOptions;
+  hostJobs?: Readonly<{
+    lane: string;
+    open: (runtime) => Readonly<{
+      execute: (job) => Effect.Effect<WatchdogExecutionDecision, WatchdogError>;
+    }>;
+  }>;
+  model: ModelSourceEffect;
+  instructions: InstructionSourceEffect;
+  tools?: ToolSourceEffect;
+  runtime: RuntimeHostEffect;
+  extensions: ExtensionRosterV0;
+  retry?: RetryPolicy;
+  modelStreamIdleTimeoutMs?: number;
+}>;
+```
+
+Validated construction bag for owned Effect composition.
+
+---
+
+### ShiitakeEffectWatch
+
+```ts
+type ShiitakeEffectWatch = Readonly<{
+  snapshot: SessionSnapshot;
+  changes: Stream.Stream<SessionFrame, ShiitakeError>;
+  close: Effect.Effect<void, ShiitakeError>;
+}>;
+```
+
+Effect-native race-safe watch result.
+
+---
+
+### ShiitakeEffectCommandHandler
+
+```ts
+type ShiitakeEffectCommandHandler = {
+  (input): Effect<
+    Readonly<{
+      status: "accepted";
+      commandId: string;
+    }>,
+    ShiitakeError
+  >;
+  (input): Effect<CancelResult, ShiitakeError>;
+  (input): Effect<undefined, ShiitakeError>;
+  (input): Effect<
+    Readonly<{
+      sessionId: string;
+    }>,
+    ShiitakeError
+  >;
+  (input): Effect<
+    | CancelResult
+    | Readonly<{
+        sessionId: string;
+      }>
+    | undefined,
+    ShiitakeError
+  >;
+};
+```
+
+Effect-native addressable Session handle.
+
+#### Call Signature
+
+```ts
+(input): Effect<Readonly<{
+  status: "accepted";
+  commandId: string;
+}>, ShiitakeError>;
+```
+
+Accept one durable prompt command.
+
+##### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                         |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`   | \| \{ `delivery`: `"followUp"` \| `"steer"`; `requestId`: `string`; `type`: `"prompt"`; `text`: `string`; `images?`: readonly `object`[]; \} \| \{ `type`: `"compact"`; `requestId`: `string`; `instructions?`: `string`; \} |
+
+##### Returns
+
+`Effect`\<`Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\>,
+[`ShiitakeError`](index.md#shiitakeerror)\>
+
+#### Call Signature
+
+```ts
+(input): Effect<CancelResult, ShiitakeError>;
+```
+
+Cancel one accepted command, or report that it is too late.
+
+##### Parameters
+
+| Parameter              | Type                                                                          |
+| ---------------------- | ----------------------------------------------------------------------------- |
+| `input`                | \{ `commandId`: `string`; `onlyIfPending?`: `boolean`; `type`: `"cancel"`; \} |
+| `input.commandId`      | `string`                                                                      |
+| `input.onlyIfPending?` | `boolean`                                                                     |
+| `input.type`           | `"cancel"`                                                                    |
+
+##### Returns
+
+`Effect`\<[`CancelResult`](client.md#cancelresult),
+[`ShiitakeError`](index.md#shiitakeerror)\>
+
+#### Call Signature
+
+```ts
+(input): Effect<undefined, ShiitakeError>;
+```
+
+Abort the active run, select a lineage leaf, or record an operator line.
+
+##### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`   | \| \{ `type`: `"abort"`; \} \| \{ `type`: `"branch"`; `entryId`: `string`; \} \| \{ `type`: `"operator"`; `requestId`: `string`; `author`: `"operator"` \| `"party"`; `text`: `string`; \} \| \{ `type`: `"title"`; `title`: `string` \| `null`; \} |
+
+##### Returns
+
+`Effect`\<`undefined`, [`ShiitakeError`](index.md#shiitakeerror)\>
+
+#### Call Signature
+
+```ts
+(input): Effect<Readonly<{
+  sessionId: string;
+}>, ShiitakeError>;
+```
+
+Fork one complete entry lineage into a new Session.
+
+##### Parameters
+
+| Parameter       | Type                                         |
+| --------------- | -------------------------------------------- |
+| `input`         | \{ `type`: `"fork"`; `entryId`: `string`; \} |
+| `input.type`    | `"fork"`                                     |
+| `input.entryId` | `string`                                     |
+
+##### Returns
+
+`Effect`\<`Readonly`\<\{ `sessionId`: `string`; \}\>,
+[`ShiitakeError`](index.md#shiitakeerror)\>
+
+#### Call Signature
+
+```ts
+(input): Effect<
+  | CancelResult
+  | Readonly<{
+  sessionId: string;
+}>
+| undefined, ShiitakeError>;
+```
+
+Execute an already-decoded command union.
+
+##### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`   | \| \{ `delivery`: `"followUp"` \| `"steer"`; `requestId`: `string`; `type`: `"prompt"`; `text`: `string`; `images?`: readonly `object`[]; \} \| \{ `type`: `"abort"`; \} \| \{ `commandId`: `string`; `onlyIfPending?`: `boolean`; `type`: `"cancel"`; \} \| \{ `type`: `"branch"`; `entryId`: `string`; \} \| \{ `type`: `"fork"`; `entryId`: `string`; \} \| \{ `type`: `"operator"`; `requestId`: `string`; `author`: `"operator"` \| `"party"`; `text`: `string`; \} \| \{ `type`: `"compact"`; `requestId`: `string`; `instructions?`: `string`; \} \| \{ `type`: `"title"`; `title`: `string` \| `null`; \} |
+
+##### Returns
+
+`Effect`\< \| [`CancelResult`](client.md#cancelresult) \| `Readonly`\<\{
+`sessionId`: `string`; \}\> \| `undefined`,
+[`ShiitakeError`](index.md#shiitakeerror)\>
+
+---
+
+### ShiitakeEffectSendOptions
+
+```ts
+type ShiitakeEffectSendOptions = Readonly<{
+  images?: PromptCommand["images"];
+  delivery?: PromptDelivery;
+  requestId?: string;
+}>;
+```
+
+Delivery intent and an optional private retry key for Effect-native sending.
+
+---
+
+### ShiitakeEffectSession
+
+```ts
+type ShiitakeEffectSession = Readonly<{
+  command: ShiitakeEffectCommandHandler;
+  abort: Effect.Effect<void, ShiitakeError>;
+  send: (text, options?) => Effect.Effect<Accepted, ShiitakeError>;
+  cancel: (input) => Effect.Effect<CancelResult, ShiitakeError>;
+  extension: (extensionId) => ShiitakeEffectSessionExtension;
+  modelPreference: Readonly<{
+    read: Effect.Effect<ModelPreference | null, ShiitakeError>;
+    set: (preference) => Effect.Effect<void, ShiitakeError>;
+  }>;
+  read: (input?) => Effect.Effect<SessionSnapshot, ShiitakeError>;
+  subscribe: (input) => Stream.Stream<SessionFrame, ShiitakeError>;
+  watch: (input?) => Effect.Effect<ShiitakeEffectWatch, ShiitakeError>;
+}>;
+```
+
+Effect-native addressable Session handle.
+
+---
+
+### ShiitakeEffectSessionExtension
+
+```ts
+type ShiitakeEffectSessionExtension = Readonly<{
+  call: (command, input) => Effect.Effect<Json, ShiitakeError>;
+}>;
+```
+
+Effect-native Session-scope extension commands.
+
+---
+
+### ShiitakeEffectAgentExtensions
+
+```ts
+type ShiitakeEffectAgentExtensions = Readonly<{
+  list: Effect.Effect<readonly ExtensionStatusV0[], ShiitakeError>;
+  resume: (extensionId) => Effect.Effect<ExtensionStatusV0, ShiitakeError>;
+  call: (extensionId, command, input) => Effect.Effect<Json, ShiitakeError>;
+}>;
+```
+
+Effect-native Agent-scope extension controls.
+
+---
+
+### ShiitakeEffectAgent
+
+```ts
+type ShiitakeEffectAgent = Readonly<{
+  createSession: (requestId) => Effect.Effect<string, ShiitakeError>;
+  deleteSession: (sessionId) => Effect.Effect<boolean, ShiitakeError>;
+  listSessions: (after?) => Effect.Effect<SessionSummaryPage, ShiitakeError>;
+  extensions: ShiitakeEffectAgentExtensions;
+  session: (sessionId) => ShiitakeEffectSession;
+  close: Effect.Effect<void, ShiitakeError>;
+}>;
+```
+
+Effect-native durable harness.
+
+---
+
+### ShiitakeEffectOwner
+
+```ts
+type ShiitakeEffectOwner = ShiitakeEffectAgent &
+  Readonly<{
+    grants: Readonly<{
+      deliver: (
+        sessionId,
+        delivery,
+      ) => Effect.Effect<GrantsDeliveryResult, ShiitakeError>;
+      read: (sessionId) => Effect.Effect<GrantsDelivery | null, ShiitakeError>;
+    }>;
+    withMeta: (meta) => ShiitakeEffectAgent;
+  }>;
+```
+
+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.
+
+---
+
+### StoredSessionSummary
+
+```ts
+type StoredSessionSummary = Readonly<{
+  createdAt: number;
+  updatedAt: number;
+  title: string;
+}>;
+```
+
+Persisted conversation facts; run status belongs to the Session's owner.
+
+---
+
+### StoredSessionSummaryRow
+
+```ts
+type StoredSessionSummaryRow =
+  | (StoredSessionSummary &
+      Readonly<{
+        kind: "session";
+        sessionId: string;
+      }>)
+  | Readonly<{
+      kind: "unavailable";
+      sessionId: string;
+    }>;
+```
+
+One persisted conversation's stored facts, or a row that could not be read.
+
+---
+
+### StoredSessionSummaryPage
+
+```ts
+type StoredSessionSummaryPage = Readonly<{
+  sessions: readonly StoredSessionSummaryRow[];
+  next: string | undefined;
+}>;
+```
+
+One page of stored conversation facts, in stable Session identity order.
+
+## Functions
+
+### make()
+
+```ts
+function make(options): Effect<ShiitakeEffectOwner, ShiitakeError>;
+```
+
+Construct the canonical Effect-native Shiitake scaffold.
+
+#### Parameters
+
+| Parameter | Type                                              |
+| --------- | ------------------------------------------------- |
+| `options` | [`ShiitakeEffectOptions`](#shiitakeeffectoptions) |
+
+#### Returns
+
+`Effect`\<[`ShiitakeEffectOwner`](#shiitakeeffectowner),
+[`ShiitakeError`](index.md#shiitakeerror)\>
+
+---
+
+### openHost()
+
+```ts
+function openHost(options, mailRoom): Effect<Readonly<{
+  readSettlement: (sessionId, commandId) => Effect<
+     | Readonly<{
+     terminal: SessionTerminal;
+     content: string;
+     usage: readonly Pick<AssistantMessage, ... | ... | ...>[];
+     toolCalls: number;
+   }>
+    | undefined, ShiitakeError>;
+  agent: ShiitakeEffectOwner;
+  acceptMail: (mail, meta?, reply?) => Effect<Readonly<{
+     status: "accepted";
+     commandId: string;
+  }>, ShiitakeError>;
+}>, ShiitakeError>;
+```
+
+Open the Effect-native host composition with addressed mail.
+
+#### Parameters
+
+| Parameter  | Type                                              |
+| ---------- | ------------------------------------------------- |
+| `options`  | [`ShiitakeEffectOptions`](#shiitakeeffectoptions) |
+| `mailRoom` | `BirdDogEffect`                                   |
+
+#### Returns
+
+`Effect`\<`Readonly`\<\{ `readSettlement`: (`sessionId`, `commandId`) =>
+`Effect`\< \| `Readonly`\<\{ `terminal`:
+[`SessionTerminal`](client.md#sessionterminal); `content`: `string`; `usage`:
+readonly `Pick`\<`AssistantMessage`, ... \| ... \| ...\>[]; `toolCalls`:
+`number`; \}\> \| `undefined`, [`ShiitakeError`](index.md#shiitakeerror)\>;
+`agent`: [`ShiitakeEffectOwner`](#shiitakeeffectowner); `acceptMail`: (`mail`,
+`meta?`, `reply?`) => `Effect`\<`Readonly`\<\{ `status`: `"accepted"`;
+`commandId`: `string`; \}\>, [`ShiitakeError`](index.md#shiitakeerror)\>; \}\>,
+[`ShiitakeError`](index.md#shiitakeerror)\>
+
+---
+
+### readSessionSummaries()
+
+```ts
+function readSessionSummaries(
+  owner,
+  after?,
+): Effect<
+  Readonly<{
+    sessions: readonly StoredSessionSummaryRow[];
+    next: string | undefined;
+  }>,
+  ShiitakeError,
+  never
+>;
+```
+
+Enumerate saved conversations' stored facts in bounded pages, for readers that
+hold only the store. Run status is not stored; use the Agent's `listSessions`
+for it. An unreadable Session is its own `unavailable` row.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `owner`   | [`SqliteOwner`](index.md#sqliteowner) |
+| `after?`  | `string`                              |
+
+#### Returns
+
+`Effect`\<`Readonly`\<\{ `sessions`: readonly
+[`StoredSessionSummaryRow`](#storedsessionsummaryrow)[]; `next`: `string` \|
+`undefined`; \}\>, [`ShiitakeError`](index.md#shiitakeerror), `never`\>
+
+## References
+
+### AbortCommand
+
+Re-exports [AbortCommand](index.md#abortcommand)
+
+---
+
+### BranchCommand
+
+Re-exports [BranchCommand](index.md#branchcommand)
+
+---
+
+### CompactCommand
+
+Re-exports [CompactCommand](index.md#compactcommand)
+
+---
+
+### CancelCommand
+
+Re-exports [CancelCommand](index.md#cancelcommand)
+
+---
+
+### CancelResult
+
+Re-exports [CancelResult](client.md#cancelresult)
+
+---
+
+### Accepted
+
+Re-exports [Accepted](client.md#accepted)
+
+---
+
+### ForkCommand
+
+Re-exports [ForkCommand](index.md#forkcommand)
+
+---
+
+### ForkedSession
+
+Re-exports [ForkedSession](client.md#forkedsession)
+
+---
+
+### PromptCommand
+
+Re-exports [PromptCommand](index.md#promptcommand)
+
+---
+
+### PromptDelivery
+
+Re-exports [PromptDelivery](index.md#promptdelivery)
+
+---
+
+### ReadOptions
+
+Re-exports [ReadOptions](client.md#readoptions)
+
+---
+
+### SessionCommand
+
+Re-exports [SessionCommand](index.md#sessioncommand)
+
+---
+
+### SessionCommandHandler
+
+Re-exports [SessionCommandHandler](client.md#sessioncommandhandler)
+
+---
+
+### SessionFrame
+
+Re-exports [SessionFrame](client.md#sessionframe)
+
+---
+
+### SessionMessage
+
+Re-exports [SessionMessage](client.md#sessionmessage)
+
+---
+
+### SessionProgress
+
+Re-exports [SessionProgress](client.md#sessionprogress)
+
+---
+
+### SessionSnapshot
+
+Re-exports [SessionSnapshot](client.md#sessionsnapshot)
+
+---
+
+### SessionActivity
+
+Re-exports [SessionActivity](client.md#sessionactivity)
+
+---
+
+### AgentRunningWork
+
+Re-exports [AgentRunningWork](client.md#agentrunningwork)
+
+---
+
+### SubscribeOptions
+
+Re-exports [SubscribeOptions](client.md#subscribeoptions)
+
+---
+
+### TooLate
+
+Re-exports [TooLate](client.md#toolate)
+
+---
+
+### WatchOptions
+
+Re-exports [WatchOptions](client.md#watchoptions)
+
+---
+
+### InstructionSnapshot
+
+Re-exports [InstructionSnapshot](index.md#instructionsnapshot)
+
+---
+
+### InstructionSource
+
+Re-exports [InstructionSource](index.md#instructionsource)
+
+---
+
+### ModelAcquisition
+
+Re-exports [ModelAcquisition](index.md#modelacquisition)
+
+---
+
+### ModelDescription
+
+Re-exports [ModelDescription](index.md#modeldescription)
+
+---
+
+### ModelSource
+
+Re-exports [ModelSource](index.md#modelsource)
+
+---
+
+### RuntimeHost
+
+Re-exports [RuntimeHost](index.md#runtimehost)
+
+---
+
+### RuntimePendingWork
+
+Re-exports [RuntimePendingWork](index.md#runtimependingwork)
+
+---
+
+### SqliteCursor
+
+Re-exports [SqliteCursor](index.md#sqlitecursor)
+
+---
+
+### SqliteOwner
+
+Re-exports [SqliteOwner](index.md#sqliteowner)
+
+---
+
+### SqliteValue
+
+Re-exports [SqliteValue](index.md#sqlitevalue)
+
+---
+
+### SqliteRow
+
+Re-exports [SqliteRow](index.md#sqliterow)
+
+---
+
+### GrantsDelivery
+
+Re-exports [GrantsDelivery](index.md#grantsdelivery)
+
+---
+
+### GrantsDeliveryResult
+
+Re-exports [GrantsDeliveryResult](index.md#grantsdeliveryresult)
+
+---
+
+### ShiitakeOptions
+
+Re-exports [ShiitakeOptions](index.md#shiitakeoptions)
+
+---
+
+### ToolAccess
+
+Re-exports [ToolAccess](index.md#toolaccess)
+
+---
+
+### HostMetaOptions
+
+Re-exports [HostMetaOptions](index.md#hostmetaoptions)
+
+---
+
+### StandardHostMetaResult
+
+Re-exports [StandardHostMetaResult](index.md#standardhostmetaresult)
+
+---
+
+### StandardHostMetaSchema
+
+Re-exports [StandardHostMetaSchema](index.md#standardhostmetaschema)
+
+---
+
+### ToolSource
+
+Re-exports [ToolSource](index.md#toolsource)
+
+---
+
+### SessionSummary
+
+Re-exports [SessionSummary](client.md#sessionsummary)
+
+---
+
+### BorrowedCompactionViewV0
+
+Re-exports [BorrowedCompactionViewV0](extensions.md#borrowedcompactionviewv0)
+
+---
+
+### CompactionHandoffErrorV0
+
+Re-exports [CompactionHandoffErrorV0](extensions.md#compactionhandofferrorv0)
+
+---
+
+### CompactionHandoffResultV0
+
+Re-exports [CompactionHandoffResultV0](extensions.md#compactionhandoffresultv0)
+
+---
+
+### CompactionHandoffV0
+
+Re-exports [CompactionHandoffV0](extensions.md#compactionhandoffv0)
+
+---
+
+### ExtensionCapabilityV0
+
+Re-exports [ExtensionCapabilityV0](index.md#extensioncapabilityv0)
+
+---
+
+### ExtensionGrantV0
+
+Re-exports [ExtensionGrantV0](extensions.md#extensiongrantv0)
+
+---
+
+### ExtensionRosterV0
+
+Re-exports [ExtensionRosterV0](extensions.md#extensionrosterv0)
+
+---
+
+### ExtensionSlotV0
+
+Re-exports [ExtensionSlotV0](extensions.md#extensionslotv0)
+
+---
+
+### ExtensionStatusV0
+
+Re-exports [ExtensionStatusV0](extensions.md#extensionstatusv0)
+
+---
+
+### RosteredExtensionV0
+
+Re-exports [RosteredExtensionV0](extensions.md#rosteredextensionv0)
+
+---
+
+### ShiitakeError
+
+Re-exports [ShiitakeError](index.md#shiitakeerror)
+
+---
+
+### ModelPreference
+
+Re-exports [ModelPreference](index.md#modelpreference)
+
+---
+
+### SessionSummaryPage
+
+Re-exports [SessionSummaryPage](client.md#sessionsummarypage)
+
+---
+
+### SessionSummaryRow
+
+Re-exports [SessionSummaryRow](client.md#sessionsummaryrow)
+
+---
+
+### sqliteRowSchema
+
+Re-exports [sqliteRowSchema](index.md#sqliterowschema)
+
+---
+
+### CommandSettlement
+
+Re-exports [CommandSettlement](index.md#commandsettlement)