@fungi.computer/shiitake 0.2.0 → 0.3.0

package/docs/api/delegation.md

@@ -0,0 +1,485 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/shiitake**](README.md)
+
+---
+
+[@fungi.computer/shiitake](README.md) / delegation
+
+# delegation
+
+## Classes
+
+### AgentDelegation
+
+Host-owned identity and admission around BirdDog's ordinary envelope.
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new AgentDelegation(deps): AgentDelegation;
+```
+
+###### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deps`    | `Readonly`\<\{ `storage`: `WatchdogSqliteOwner`; `expiresAt`: () => `number`; `identity`: () => \| [`DelegationIdentity`](#delegationidentity) \| `null` \| `Promise`\<[`DelegationIdentity`](#delegationidentity) \| `null`\>; `directory`: () => [`AgentControlDirectory`](agent-control.md#agentcontroldirectory); `deliver`: (`mail`) => `Promise`\<[`Accepted`](client.md#accepted)\>; `prepare`: (`mail`) => `Promise`\<`void`\>; `accept`: (`mail`, `reply?`) => `Promise`\<[`Accepted`](client.md#accepted)\>; \}\> |
+
+###### Returns
+
+[`AgentDelegation`](#agentdelegation)
+
+#### Methods
+
+##### settlement()
+
+```ts
+settlement(
+   sender,
+   sessionId,
+   commandId,
+   host
+): Promise<
+  | Readonly<{
+  acceptedSender: string | null;
+  terminal: SessionTerminal;
+  content: string;
+  usage: readonly Pick<AssistantMessage, "model" | "provider" | "usage">[];
+  toolCalls: number;
+}>
+| undefined>;
+```
+
+Recipient-local disclosure through the public host, never another Agent's RPC.
+
+###### Parameters
+
+| Parameter   | Type                                                                  |
+| ----------- | --------------------------------------------------------------------- |
+| `sender`    | [`DelegationIdentity`](#delegationidentity)                           |
+| `sessionId` | `string`                                                              |
+| `commandId` | `string`                                                              |
+| `host`      | `Pick`\<[`ShiitakeHost`](index.md#shiitakehost), `"readSettlement"`\> |
+
+###### Returns
+
+`Promise`\< \| `Readonly`\<\{ `acceptedSender`: `string` \| `null`; `terminal`:
+[`SessionTerminal`](client.md#sessionterminal); `content`: `string`; `usage`:
+readonly `Pick`\<`AssistantMessage`, `"model"` \| `"provider"` \| `"usage"`\>[];
+`toolCalls`: `number`; \}\> \| `undefined`\>
+
+##### send()
+
+```ts
+send(
+   input,
+   sourceSessionId,
+   signal,
+   invocation?
+): Promise<Readonly<{
+  status: "accepted";
+  commandId: string;
+}>>;
+```
+
+Delegate work to an in-scope Agent: steer its Session, or start fleet
+correspondence.
+
+###### Parameters
+
+| Parameter         | Type                                                                                                                                   |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`           | [`AgentDelegationInput`](agent-control.md#agentdelegationinput)                                                                        |
+| `sourceSessionId` | `string`                                                                                                                               |
+| `signal`          | `AbortSignal`                                                                                                                          |
+| `invocation?`     | `Readonly`\<\{ `toolCallId`: `string`; `sendIndex`: `number`; `commandId?`: `string`; `meta?`: `Json`; `toolCallCode?`: `string`; \}\> |
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\>\>
+
+##### recall()
+
+```ts
+recall(
+   input,
+   sourceSessionId,
+   signal
+): Promise<CancelResult>;
+```
+
+Resolve this sender's exact request, then let the recipient guard pending work.
+
+###### Parameters
+
+| Parameter         | Type                                                    |
+| ----------------- | ------------------------------------------------------- |
+| `input`           | [`AgentRecallInput`](agent-control.md#agentrecallinput) |
+| `sourceSessionId` | `string`                                                |
+| `signal`          | `AbortSignal`                                           |
+
+###### Returns
+
+`Promise`\<[`CancelResult`](client.md#cancelresult)\>
+
+##### receive()
+
+```ts
+receive(raw): Promise<PostDeliveryResult>;
+```
+
+Admit one addressed Agent mail for this Agent, or refuse it.
+
+###### Parameters
+
+| Parameter     | Type                                                                               |
+| ------------- | ---------------------------------------------------------------------------------- |
+| `raw`         | \{ `key`: `string`; `kind`: `string`; `address`: `unknown`; `event`: `unknown`; \} |
+| `raw.key`     | `string`                                                                           |
+| `raw.kind`    | `string`                                                                           |
+| `raw.address` | `unknown`                                                                          |
+| `raw.event`   | `unknown`                                                                          |
+
+###### Returns
+
+`Promise`\<`PostDeliveryResult`\>
+
+---
+
+### AgentDisclosureRefused
+
+A current correspondent no longer has disclosure authority.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new AgentDisclosureRefused(): AgentDisclosureRefused;
+```
+
+###### Returns
+
+[`AgentDisclosureRefused`](#agentdisclosurerefused)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+---
+
+### AgentMail
+
+Recipient-owned replies and receipt-bearing submissions over the host's one Post
+lane.
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new AgentMail(deps): AgentMail;
+```
+
+###### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deps`    | `Readonly`\<\{ `storage`: `WatchdogSqliteOwner`; `post`: () => [`AgentMailPost`](#agentmailpost); `identity`: () => \| [`DelegationIdentity`](#delegationidentity) \| `null` \| `Promise`\<[`DelegationIdentity`](#delegationidentity) \| `null`\>; `replySettlement`: [`AgentReplySettlement`](#agentreplysettlement); `drain`: () => `Promise`\<`void`\>; `wake`: () => `Promise`\<`void`\>; \}\> |
+
+###### Returns
+
+[`AgentMail`](#agentmail)
+
+#### Methods
+
+##### send()
+
+```ts
+send(mail): Promise<Readonly<{
+  status: "accepted";
+  commandId: string;
+}>>;
+```
+
+Submit one mail and return the recipient's Accepted receipt.
+
+###### Parameters
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `mail`    | `BirdDogMail` |
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\>\>
+
+##### mailRoom()
+
+```ts
+mailRoom(): BirdDogEffect;
+```
+
+BirdDog's mail room: disclosed settlement replies fan out over Post.
+
+###### Returns
+
+`BirdDogEffect`
+
+## Type Aliases
+
+### DelegationIdentity
+
+```ts
+type DelegationIdentity = Readonly<{
+  scopeId: string;
+  agentId: string;
+}>;
+```
+
+Shiitake host-pack identity; core consumes OysterAgents, never this engine.
+
+---
+
+### AgentReplySettlement
+
+```ts
+type AgentReplySettlement = (mail) => Promise<CommandSettlement | undefined>;
+```
+
+Undefined is an explicit disclosure refusal; missing facts and read errors must
+fail.
+
+#### Parameters
+
+| Parameter | Type          |
+| --------- | ------------- |
+| `mail`    | `BirdDogMail` |
+
+#### Returns
+
+`Promise`\<[`CommandSettlement`](index.md#commandsettlement) \| `undefined`\>
+
+---
+
+### AgentMailPost
+
+```ts
+type AgentMailPost = Pick<
+  PostRuntime<{
+    agentMail: ReturnType<typeof agentMailRoute>;
+  }>,
+  "send" | "read" | "nextWake"
+>;
+```
+
+The host's one Post lane, as Agent mail borrows it.
+
+## Variables
+
+### machineAgentCodecs
+
+```ts
+const machineAgentCodecs: object;
+```
+
+The Agent wire decoders a host lends Oyster's machine-link client, so the device
+link routes Agent work without owning Shiitake's grammar.
+
+#### Type Declaration
+
+| Name                | Type                                                                | Description                                                             |
+| ------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `sessionCreation()` | (`body`) => \| `Readonly`\<\{ `requestId`: `string`; \}\> \| `null` | The Session-creation intent, or null when the body is not one.          |
+| `settlement()`      | (`encoded`) => [`CommandSettlement`](index.md#commandsettlement)    | One serialized settlement from a hosted or machine-homed Agent.         |
+| `accepted()`        | (`receipt`) => `void`                                               | Throws unless an acknowledgment carries a well-formed Accepted receipt. |
+
+## Functions
+
+### agentMailRoute()
+
+```ts
+function agentMailRoute(namespace, replySettlement): PostRoute<AgentMailAddress, {
+  key: string;
+  to: {
+     kind: "agent";
+     agentId: string;
+     sessionId: string;
+  };
+  from: {
+     kind: "agent";
+     agentId: string;
+     sessionId: string;
+  };
+  replyTo: readonly object[];
+  content: string;
+  createdAt: number;
+  meta?: Json | undefined;
+  reply?: {
+     commandId: string;
+     outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
+     diagnostic?: string;
+  };
+}, {
+  key: string;
+  to: {
+     kind: "agent";
+     agentId: string;
+     sessionId: string;
+  };
+  from: {
+     kind: "agent";
+     agentId: string;
+     sessionId: string;
+  };
+  replyTo: readonly object[];
+  content: string;
+  createdAt: number;
+  meta?: Json | undefined;
+  reply?: {
+     commandId: string;
+     outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
+     diagnostic?: string;
+  };
+}, AgentMailAddress, {
+  key: string;
+  to: {
+     kind: "agent";
+     agentId: string;
+     sessionId: string;
+  };
+  from: {
+     kind: "agent";
+     agentId: string;
+     sessionId: string;
+  };
+  replyTo: readonly object[];
+  content: string;
+  createdAt: number;
+  meta?: Json | undefined;
+  reply?: {
+     commandId: string;
+     outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
+     diagnostic?: string;
+  };
+}, {
+  key: string;
+  to: {
+     kind: "agent";
+     agentId: string;
+     sessionId: string;
+  };
+  from: {
+     kind: "agent";
+     agentId: string;
+     sessionId: string;
+  };
+  replyTo: readonly object[];
+  content: string;
+  createdAt: number;
+  meta?: Json | undefined;
+  reply?: {
+     commandId: string;
+     outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
+     diagnostic?: string;
+  };
+}> & Omit<Readonly<{
+  addressKind: string;
+  address: Codec<unknown, unknown>;
+  event: Codec<unknown, unknown>;
+  encodeEnvelope: (envelope) => object;
+  parseDelivery: (envelope) => object;
+  prepareEnvelope?: (envelope, signal) => Promise<{
+     key: string;
+     kind: string;
+     address: unknown;
+     event: unknown;
+  }>;
+  recordDelivered?: (envelope) => void;
+  nameOf: (envelope) => string;
+  namespace: Readonly<{
+     getByName: (name) => Readonly<{
+        deliver: (envelope) => Promise<...>;
+     }>;
+  }>;
+  recordCursor?: (envelope, cursor) => void;
+  recordRefused?: (envelope) => void;
+}>, "event" | "address">;
+```
+
+Current disclosure admission runs at every transport attempt, including frozen
+retries.
+
+#### Parameters
+
+| Parameter         | Type                                                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `namespace`       | `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<`PostDeliveryResult`\>; \}\>; \}\> |
+| `replySettlement` | [`AgentReplySettlement`](#agentreplysettlement)                                                                                 |
+
+#### Returns
+
+`PostRoute`\<`AgentMailAddress`, \{ `key`: `string`; `to`: \{ `kind`: `"agent"`;
+`agentId`: `string`; `sessionId`: `string`; \}; `from`: \{ `kind`: `"agent"`;
+`agentId`: `string`; `sessionId`: `string`; \}; `replyTo`: readonly `object`[];
+`content`: `string`; `createdAt`: `number`; `meta?`: Json \| undefined;
+`reply?`: \{ `commandId`: `string`; `outcome`: `"completed"` \| `"failed"` \|
+`"cancelled"` \| `"interrupted"` \| `"outcome_unknown"`; `diagnostic?`:
+`string`; \}; \}, \{ `key`: `string`; `to`: \{ `kind`: `"agent"`; `agentId`:
+`string`; `sessionId`: `string`; \}; `from`: \{ `kind`: `"agent"`; `agentId`:
+`string`; `sessionId`: `string`; \}; `replyTo`: readonly `object`[]; `content`:
+`string`; `createdAt`: `number`; `meta?`: Json \| undefined; `reply?`: \{
+`commandId`: `string`; `outcome`: `"completed"` \| `"failed"` \| `"cancelled"`
+\| `"interrupted"` \| `"outcome_unknown"`; `diagnostic?`: `string`; \}; \},
+`AgentMailAddress`, \{ `key`: `string`; `to`: \{ `kind`: `"agent"`; `agentId`:
+`string`; `sessionId`: `string`; \}; `from`: \{ `kind`: `"agent"`; `agentId`:
+`string`; `sessionId`: `string`; \}; `replyTo`: readonly `object`[]; `content`:
+`string`; `createdAt`: `number`; `meta?`: Json \| undefined; `reply?`: \{
+`commandId`: `string`; `outcome`: `"completed"` \| `"failed"` \| `"cancelled"`
+\| `"interrupted"` \| `"outcome_unknown"`; `diagnostic?`: `string`; \}; \}, \{
+`key`: `string`; `to`: \{ `kind`: `"agent"`; `agentId`: `string`; `sessionId`:
+`string`; \}; `from`: \{ `kind`: `"agent"`; `agentId`: `string`; `sessionId`:
+`string`; \}; `replyTo`: readonly `object`[]; `content`: `string`; `createdAt`:
+`number`; `meta?`: Json \| undefined; `reply?`: \{ `commandId`: `string`;
+`outcome`: `"completed"` \| `"failed"` \| `"cancelled"` \| `"interrupted"` \|
+`"outcome_unknown"`; `diagnostic?`: `string`; \}; \}\> & `Omit`\<`Readonly`\<\{
+`addressKind`: `string`; `address`: `Codec`\<`unknown`, `unknown`\>; `event`:
+`Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`: (`envelope`) => `object`;
+`parseDelivery`: (`envelope`) => `object`; `prepareEnvelope?`: (`envelope`,
+`signal`) => `Promise`\<\{ `key`: `string`; `kind`: `string`; `address`:
+`unknown`; `event`: `unknown`; \}\>; `recordDelivered?`: (`envelope`) => `void`;
+`nameOf`: (`envelope`) => `string`; `namespace`: `Readonly`\<\{ `getByName`:
+(`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<...\>; \}\>;
+\}\>; `recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`:
+(`envelope`) => `void`; \}\>, `"event"` \| `"address"`\>
+
+---
+
+### machineAgentReservations()
+
+```ts
+function machineAgentReservations(sql): (reservation) => object;
+```
+
+Machine-homed Agent identities in the ordinary directory over the enrollment's
+own store: one Team identity per enrollment receipt, reserved without opening a
+hosted Agent. The enrolling member is the grant actor.
+
+#### Parameters
+
+| Parameter | Type                                                                                |
+| --------- | ----------------------------------------------------------------------------------- |
+| `sql`     | `Readonly`\<\{ `exec`: (`statement`, ...`bindings`) => `WatchdogSqliteCursor`; \}\> |
+
+#### Returns
+
+(`reservation`) => `object`

package/docs/api/effect.md

@@ -34,6 +34,8 @@ type ModelAcquisitionEffect = Readonly<{
   model: Model<Api>;
   stream?: MuleStreamFunction;
   retryAfterMs?: (message) => number | undefined;
+  retryable: (message) => boolean;
+  failureReason?: (message) => string | undefined;
   release: Effect.Effect<void, ShiitakeError>;
 }>;
 ```
@@ -110,7 +112,7 @@ Effect-native owner for scheduling the opaque durable reconciler.
 type ShiitakeEffectOptions = Readonly<{
   meta?: HostMetaOptions;
   store: SqliteOwner;
-  storageBudget?: StorageBudget;
+  storagePressure?: StoragePressureCheck;
   compaction?: CompactionOptions;
   hostJobs?: Readonly<{
     lane: string;
@@ -309,9 +311,11 @@ Delivery intent and an optional private retry key for Effect-native sending.
 ```ts
 type ShiitakeEffectSession = Readonly<{
   command: ShiitakeEffectCommandHandler;
+  withdraw: (requestId) => Effect.Effect<WithdrawResult, ShiitakeError>;
   abort: Effect.Effect<void, ShiitakeError>;
   send: (text, options?) => Effect.Effect<Accepted, ShiitakeError>;
   cancel: (input) => Effect.Effect<CancelResult, ShiitakeError>;
+  latestPending: Effect.Effect<SessionPendingPrompt | null, ShiitakeError>;
   extension: (extensionId) => ShiitakeEffectSessionExtension;
   modelPreference: Readonly<{
     read: Effect.Effect<ModelPreference | null, ShiitakeError>;
@@ -375,6 +379,13 @@ Effect-native durable harness.
 ```ts
 type ShiitakeEffectOwner = ShiitakeEffectAgent &
   Readonly<{
+    prepareConfiguration: (configuration) => Effect.Effect<
+      Readonly<{
+        commit: Effect.Effect<void, ShiitakeError>;
+        discard: Effect.Effect<void>;
+      }>,
+      ShiitakeError
+    >;
     grants: Readonly<{
       deliver: (
         sessionId,
@@ -465,6 +476,7 @@ Construct the canonical Effect-native Shiitake scaffold.
 function openHost(options, mailRoom): Effect<Readonly<{
   readSettlement: (sessionId, commandId) => Effect<
      | Readonly<{
+     acceptedSender: string | null;
      terminal: SessionTerminal;
      content: string;
      usage: readonly Pick<AssistantMessage, ... | ... | ...>[];
@@ -491,7 +503,7 @@ Open the Effect-native host composition with addressed mail.
 #### Returns
 
 `Effect`\<`Readonly`\<\{ `readSettlement`: (`sessionId`, `commandId`) =>
-`Effect`\< \| `Readonly`\<\{ `terminal`:
+`Effect`\< \| `Readonly`\<\{ `acceptedSender`: `string` \| `null`; `terminal`:
 [`SessionTerminal`](client.md#sessionterminal); `content`: `string`; `usage`:
 readonly `Pick`\<`AssistantMessage`, ... \| ... \| ...\>[]; `toolCalls`:
 `number`; \}\> \| `undefined`, [`ShiitakeError`](index.md#shiitakeerror)\>;
@@ -633,6 +645,12 @@ Re-exports [SessionProgress](client.md#sessionprogress)
 
 ---
 
+### SessionToolOutput
+
+Re-exports [SessionToolOutput](client.md#sessiontooloutput)
+
+---
+
 ### SessionSnapshot
 
 Re-exports [SessionSnapshot](client.md#sessionsnapshot)

package/docs/api/extensions.md

@@ -93,8 +93,8 @@ Durable record failure: stored or supplied values broke their schema or bounds.
 #### Extends
 
 - `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `reason`:
-  `"unavailable"` \| `"decode"` \| `"encode"` \| `"bound"`; `message`: `string`;
-  \}\>
+  `"unavailable"` \| `"decode"` \| `"encode"` \| `"bound"` \|
+  `"session_absent"`; `message`: `string`; \}\>
 
 #### Constructors
 
@@ -106,11 +106,11 @@ new ExtensionStateError(args): ExtensionStateError;
 
 ###### Parameters
 
-| Parameter      | Type                                                                                           |
-| -------------- | ---------------------------------------------------------------------------------------------- |
-| `args`         | \{ `reason`: `"unavailable"` \| `"decode"` \| `"encode"` \| `"bound"`; `message`: `string`; \} |
-| `args.reason`  | `"unavailable"` \| `"decode"` \| `"encode"` \| `"bound"`                                       |
-| `args.message` | `string`                                                                                       |
+| Parameter      | Type                                                                                                                 |
+| -------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `args`         | \{ `reason`: `"unavailable"` \| `"decode"` \| `"encode"` \| `"bound"` \| `"session_absent"`; `message`: `string`; \} |
+| `args.reason`  | `"unavailable"` \| `"decode"` \| `"encode"` \| `"bound"` \| `"session_absent"`                                       |
+| `args.message` | `string`                                                                                                             |
 
 ###### Returns
 
@@ -122,7 +122,7 @@ new ExtensionStateError(args): ExtensionStateError;
 Data.TaggedError(
   "ExtensionStateError",
 )<{
-  reason: "decode" | "encode" | "bound" | "unavailable";
+  reason: "decode" | "encode" | "bound" | "unavailable" | "session_absent";
   message: string;
 }>.constructor
 ```
@@ -132,7 +132,7 @@ Data.TaggedError(
 ##### reason
 
 ```ts
-readonly reason: "unavailable" | "decode" | "encode" | "bound";
+readonly reason: "unavailable" | "decode" | "encode" | "bound" | "session_absent";
 ```
 
 ###### Inherited from
@@ -1221,6 +1221,9 @@ type ExtensionContextV0<S, Config, D> = Readonly<{
   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>;
@@ -1632,6 +1635,7 @@ One extension's encoded slot in a Session snapshot or frame.
 
 ```ts
 type BorrowedCompactionViewV0 = Readonly<{
+  sessionId: string;
   messagesToSummarize: readonly Message[];
   turnPrefixMessages: readonly Message[];
   result: Readonly<{
@@ -1899,10 +1903,12 @@ const AttentionItemSchema: Struct<{
   summary: NonEmptyString;
   since: Int;
   expiresAt: optional<Int>;
+  inbox: optional<Literal<false>>;
 }>;
 ```
 
 An extension-owned request for human attention; expiry is owned by its timer.
+Items marked `inbox: false` remain visible without changing the inbox state.
 
 ## Functions
 
@@ -1992,6 +1998,12 @@ Re-exports [SessionAttention](client.md#sessionattention)
 
 ---
 
+### ClientActivityStateV0
+
+Re-exports [ClientActivityStateV0](client-entry.md#clientactivitystatev0)
+
+---
+
 ### ClientActivityV0
 
 Re-exports [ClientActivityV0](client-entry.md#clientactivityv0)