@fungi.computer/shiitake 0.3.0 → 0.4.0

package/dist/testing.js

@@ -176,12 +176,14 @@ export async function memoryHost(options = {}) {
         return {
             agent,
             reconcile: async () => requireBound().reconcile(),
-            settle: async (sessionId, maxTicks) => {
+            settle: async (sessionId, maxTicks, beforeRead) => {
                 const budget = settlementBudgetSchema.parse(maxTicks);
                 for (let tick = 0; tick < budget; tick += 1) {
                     const host = requireBound();
-                    if (!(await host.pendingWork()).pending)
+                    if (!(await host.pendingWork()).pending) {
+                        await beforeRead?.();
                         return agent.session(sessionId).read();
+                    }
                     await host.reconcile();
                 }
                 throw new Error(`Memory host did not settle within ${String(budget)} reconciliation ticks`);

package/docs/api/agent-control.md

@@ -219,7 +219,12 @@ Host-only identity and admitted command metadata for one delegated send.
 ```ts
 type AgentControlDirectory = Readonly<{
   list: (signal, options?) => Promise<readonly AgentControlAgent[]>;
-  send?: (input, sourceSessionId, signal, invocation?) => Promise<Accepted>;
+  send?: (
+    input,
+    sourceSessionId,
+    signal,
+    invocation?,
+  ) => Promise<Accepted | Held>;
   recall?: (input, sourceSessionId, signal) => Promise<CancelResult>;
   create?: (input, signal) => Promise<AgentControlAgent>;
   setModel?: (input, signal) => Promise<void>;
@@ -262,10 +267,10 @@ report back, its store predates the current schema, or the Agent is archived.
 
 ## Functions
 
-### waitForAgentTerminal()
+### waitForAgentSettlement()
 
 ```ts
-function waitForAgentTerminal(
+function waitForAgentSettlement(
   session,
   commandId,
   timeoutMs,
@@ -273,16 +278,16 @@ function waitForAgentTerminal(
   startedAt?,
 ): Promise<
   Readonly<{
-    commandId: string;
-    outcome: "completed" | "failed" | "cancelled" | "interrupted";
-    sequence: number;
-    diagnostic: string | null;
-    meta?: Json;
+    acceptedSender: string | null;
+    terminal: SessionTerminal;
+    content: string;
+    usage: readonly Pick<AssistantMessage, "model" | "provider" | "usage">[];
+    toolCalls: number;
   }>
 >;
 ```
 
-Observe one durable terminal; timeout or abort closes observation, not the work.
+Await one exact durable terminal without opening a transcript observation.
 
 #### Parameters
 
@@ -296,9 +301,10 @@ Observe one durable terminal; timeout or abort closes observation, not the work.
 
 #### Returns
 
-`Promise`\<`Readonly`\<\{ `commandId`: `string`; `outcome`: `"completed"` \|
-`"failed"` \| `"cancelled"` \| `"interrupted"`; `sequence`: `number`;
-`diagnostic`: `string` \| `null`; `meta?`: [`Json`](extensions.md#json); \}\>\>
+`Promise`\<`Readonly`\<\{ `acceptedSender`: `string` \| `null`; `terminal`:
+[`SessionTerminal`](client.md#sessionterminal); `content`: `string`; `usage`:
+readonly `Pick`\<`AssistantMessage`, `"model"` \| `"provider"` \| `"usage"`\>[];
+`toolCalls`: `number`; \}\>\>
 
 ---
 

package/docs/api/client.md

@@ -23,6 +23,30 @@ Semantic acknowledgement returned after one durable acceptance commit.
 
 ---
 
+### Held
+
+```ts
+type Held = Readonly<{
+  status: "held";
+  reason: "recipient_offline";
+  message: "waiting: recipient offline";
+}>;
+```
+
+Durable relay custody, not acceptance of a command by the recipient.
+
+---
+
+### DelegationReceipt
+
+```ts
+type DelegationReceipt = Accepted | Held;
+```
+
+A delegation send can be accepted by the Agent or held by its relay.
+
+---
+
 ### TooLate
 
 ```ts
@@ -581,6 +605,10 @@ Bounded Session baseline at one opaque owner cursor.
 
 ```ts
 type SessionFrame =
+  | Readonly<{
+      kind: "activity";
+      activity: SessionActivity;
+    }>
   | Readonly<{
       kind: "tool_output";
       toolOutput: readonly SessionToolOutput[];
@@ -686,6 +714,10 @@ type ShiitakeSession = Readonly<{
     set: (preference) => Promise<void>;
   }>;
   read: (input?) => Promise<SessionSnapshot>;
+  readSettlement: (
+    commandId,
+    options?,
+  ) => Promise<CommandSettlement | undefined>;
   subscribe: (input) => AsyncIterable<SessionFrame>;
   watch: (input?) => Promise<SessionWatch>;
 }>;
@@ -924,8 +956,48 @@ const AcceptedSchema: Schema.Codec<Accepted>;
 
 Decode a durable command acceptance value at an RPC boundary.
 
+---
+
+### HeldSchema
+
+```ts
+const HeldSchema: Schema.Codec<Held>;
+```
+
+Parse the relay's custody acknowledgment without implying Agent acceptance.
+
+---
+
+### DelegationReceiptSchema
+
+```ts
+const DelegationReceiptSchema: Schema.Codec<DelegationReceipt>;
+```
+
+A delegated send is accepted by its owner or held in durable mail custody.
+
 ## Functions
 
+### parseDelegationReceipt()
+
+```ts
+function parseDelegationReceipt(value): DelegationReceipt;
+```
+
+Decode one delegated send's acceptance or durable-custody result.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `value`   | `string` |
+
+#### Returns
+
+[`DelegationReceipt`](#delegationreceipt)
+
+---
+
 ### parseWithdrawResult()
 
 ```ts
@@ -1145,6 +1217,12 @@ Connect to a remotely hosted Shiitake agent.
 
 ## References
 
+### CommandSettlement
+
+Re-exports [CommandSettlement](index.md#commandsettlement)
+
+---
+
 ### parseForkedSession
 
 Re-exports [parseForkedSession](index.md#parseforkedsession)

package/docs/api/delegation.md

@@ -24,9 +24,9 @@ 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)\>; \}\> |
+| 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`\<[`DelegationReceipt`](client.md#delegationreceipt)\>; `prepare`: (`mail`) => `Promise`\<`void`\>; `accept`: (`mail`, `reply?`) => `Promise`\<[`Accepted`](client.md#accepted)\>; \}\> |
 
 ###### Returns
 
@@ -79,10 +79,7 @@ send(
    sourceSessionId,
    signal,
    invocation?
-): Promise<Readonly<{
-  status: "accepted";
-  commandId: string;
-}>>;
+): Promise<DelegationReceipt>;
 ```
 
 Delegate work to an in-scope Agent: steer its Session, or start fleet
@@ -99,7 +96,7 @@ correspondence.
 
 ###### Returns
 
-`Promise`\<`Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\>\>
+`Promise`\<[`DelegationReceipt`](client.md#delegationreceipt)\>
 
 ##### recall()
 
@@ -205,13 +202,10 @@ new AgentMail(deps): AgentMail;
 ##### send()
 
 ```ts
-send(mail): Promise<Readonly<{
-  status: "accepted";
-  commandId: string;
-}>>;
+send(mail): Promise<DelegationReceipt>;
 ```
 
-Submit one mail and return the recipient's Accepted receipt.
+Submit one mail and return recipient acceptance or relay-held custody.
 
 ###### Parameters
 
@@ -221,7 +215,7 @@ Submit one mail and return the recipient's Accepted receipt.
 
 ###### Returns
 
-`Promise`\<`Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\>\>
+`Promise`\<[`DelegationReceipt`](client.md#delegationreceipt)\>
 
 ##### mailRoom()
 
@@ -297,11 +291,11 @@ 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. |
+| 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 valid acceptance or Held result. |
 
 ## Functions
 
@@ -324,11 +318,15 @@ function agentMailRoute(namespace, replySettlement): PostRoute<AgentMailAddress,
   content: string;
   createdAt: number;
   meta?: Json | undefined;
-  reply?: {
+  reply?:   | {
      commandId: string;
      outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
      diagnostic?: string;
-  };
+   }
+     | {
+     outcome: "undeliverable";
+     reason: "recipient_offline" | "recipient_left";
+   };
 }, {
   key: string;
   to: {
@@ -345,11 +343,15 @@ function agentMailRoute(namespace, replySettlement): PostRoute<AgentMailAddress,
   content: string;
   createdAt: number;
   meta?: Json | undefined;
-  reply?: {
+  reply?:   | {
      commandId: string;
      outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
      diagnostic?: string;
-  };
+   }
+     | {
+     outcome: "undeliverable";
+     reason: "recipient_offline" | "recipient_left";
+   };
 }, AgentMailAddress, {
   key: string;
   to: {
@@ -366,11 +368,15 @@ function agentMailRoute(namespace, replySettlement): PostRoute<AgentMailAddress,
   content: string;
   createdAt: number;
   meta?: Json | undefined;
-  reply?: {
+  reply?:   | {
      commandId: string;
      outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
      diagnostic?: string;
-  };
+   }
+     | {
+     outcome: "undeliverable";
+     reason: "recipient_offline" | "recipient_left";
+   };
 }, {
   key: string;
   to: {
@@ -387,13 +393,18 @@ function agentMailRoute(namespace, replySettlement): PostRoute<AgentMailAddress,
   content: string;
   createdAt: number;
   meta?: Json | undefined;
-  reply?: {
+  reply?:   | {
      commandId: string;
      outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
      diagnostic?: string;
-  };
+   }
+     | {
+     outcome: "undeliverable";
+     reason: "recipient_offline" | "recipient_left";
+   };
 }> & Omit<Readonly<{
   addressKind: string;
+  deadlineMs?: number;
   address: Codec<unknown, unknown>;
   event: Codec<unknown, unknown>;
   encodeEnvelope: (envelope) => object;
@@ -432,35 +443,41 @@ retries.
 `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"` \|
+`reply?`: \| \{ `commandId`: `string`; `outcome`: `"completed"` \| `"failed"` \|
+`"cancelled"` \| `"interrupted"` \| `"outcome_unknown"`; `diagnostic?`:
+`string`; \} \| \{ `outcome`: `"undeliverable"`; `reason`: `"recipient_offline"`
+\| `"recipient_left"`; \}; \}, \{ `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"`\>
+`string`; \} \| \{ `outcome`: `"undeliverable"`; `reason`: `"recipient_offline"`
+\| `"recipient_left"`; \}; \}, `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`; \} \| \{ `outcome`: `"undeliverable"`; `reason`:
+`"recipient_offline"` \| `"recipient_left"`; \}; \}, \{ `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`; \} \| \{ `outcome`: `"undeliverable"`; `reason`:
+`"recipient_offline"` \| `"recipient_left"`; \}; \}\> & `Omit`\<`Readonly`\<\{
+`addressKind`: `string`; `deadlineMs?`: `number`; `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"`\>
 
 ---
 

package/docs/api/effect.md

@@ -36,6 +36,7 @@ type ModelAcquisitionEffect = Readonly<{
   retryAfterMs?: (message) => number | undefined;
   retryable: (message) => boolean;
   failureReason?: (message) => string | undefined;
+  providerError?: (message) => string | undefined;
   release: Effect.Effect<void, ShiitakeError>;
 }>;
 ```
@@ -322,6 +323,10 @@ type ShiitakeEffectSession = Readonly<{
     set: (preference) => Effect.Effect<void, ShiitakeError>;
   }>;
   read: (input?) => Effect.Effect<SessionSnapshot, ShiitakeError>;
+  readSettlement: (
+    commandId,
+    timeoutMs?,
+  ) => Effect.Effect<CommandSettlement | undefined, ShiitakeError>;
   subscribe: (input) => Stream.Stream<SessionFrame, ShiitakeError>;
   watch: (input?) => Effect.Effect<ShiitakeEffectWatch, ShiitakeError>;
 }>;

package/docs/api/fleet.md

@@ -217,7 +217,7 @@ Exact settled Session facts, including Pi usage and tool-call records.
 ```ts
 type FleetDelegationOptions = Readonly<{
   storage: WatchdogSqliteOwner;
-  deliver: (mail) => Promise<Accepted>;
+  deliver: (mail) => Promise<DelegationReceipt>;
   readSettlement: (
     agentId,
     sessionId,
@@ -364,6 +364,16 @@ One idempotent prompt, using the Session owner's existing delivery grammar.
 
 ## Variables
 
+### commandSettlementSchema
+
+```ts
+const commandSettlementSchema: Schema.Codec<CommandSettlement>;
+```
+
+Exact command facts shared by Session clients and host fleet transports.
+
+---
+
 ### agentActionSchema
 
 ```ts
@@ -523,16 +533,6 @@ const agentDelegationTaskSchema: ZodLazy<
 
 Replay identity and work, with the parent supplied exclusively by the grant.
 
----
-
-### commandSettlementSchema
-
-```ts
-const commandSettlementSchema: Schema.Codec<CommandSettlement>;
-```
-
-Exact host facts encoded over internal transports, without transcript content.
-
 ## Functions
 
 ### assertAgentGrant()
@@ -700,11 +700,11 @@ Shiitake owns work deduplication, execution and settlement; Post owns replies.
 
 #### Returns
 
-| Name                  | Type                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `start()`             | (`grant`, `raw`) => `Promise`\<`Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\>\>                                                                                                                                                                                                                      | Submit frozen mail or reuse its recorded Session admission receipt.                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `authenticateReply()` | (`mail`) => \| `Readonly`\<\{ `ancestors`: readonly `string`[]; `maxDepth`: `number`; `reply`: \{ `commandId`: `string`; `outcome`: `"completed"` \| `"failed"` \| `"cancelled"` \| `"interrupted"` \| `"outcome_unknown"`; `diagnostic?`: `string`; `agentId`: `string`; `sessionId`: `string`; \}; \}\> \| `undefined` | Match a reply to frozen mail and restore the caller's delegation path. Authenticate one arriving reply against the frozen mail this owner sent. It must be BirdDog's single reply key for that mail, mirror its sender and recipient exactly, carry BirdDog's settlement facts and, once the send's receipt is recorded, name that receipt's `commandId`. The result restores the caller's own delegation path and the verified reply; it never reads the reply's text or any settlement metadata. |
-| `receipt()`           | (`requestId`) => \| `Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\> \| `undefined`                                                                                                                                                                                                                    | Read an existing acceptance receipt without reserving or delivering mail. Read only the existing acceptance receipt; do not reserve or deliver mail.                                                                                                                                                                                                                                                                                                                                               |
+| Name                  | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start()`             | (`grant`, `raw`) => `Promise`\<[`DelegationReceipt`](client.md#delegationreceipt)\>                                                                                                                                                                                                                                                                                                                                                                                   | Submit frozen mail or reuse its recorded Session admission receipt.                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `authenticateReply()` | (`mail`) => \| `Readonly`\<\{ `ancestors`: readonly `string`[]; `maxDepth`: `number`; `reply`: \| \{ `commandId`: `string`; `outcome`: `"completed"` \| `"failed"` \| `"cancelled"` \| `"interrupted"` \| `"outcome_unknown"`; `diagnostic?`: `string`; `agentId`: `string`; `sessionId`: `string`; \} \| \{ `outcome`: `"undeliverable"`; `reason`: `"recipient_offline"` \| `"recipient_left"`; `agentId`: `string`; `sessionId`: `string`; \}; \}\> \| `undefined` | Match a reply to frozen mail and restore the caller's delegation path. Authenticate one arriving reply against the frozen mail this owner sent. It must be BirdDog's single reply key for that mail, mirror its sender and recipient exactly, carry BirdDog's settlement facts and, once the send's receipt is recorded, name that receipt's `commandId`. The result restores the caller's own delegation path and the verified reply; it never reads the reply's text or any settlement metadata. |
+| `receipt()`           | (`requestId`) => \| `Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\> \| `undefined`                                                                                                                                                                                                                                                                                                                                                                 | Read an existing acceptance receipt without reserving or delivering mail. Read only the existing acceptance receipt; do not reserve or deliver mail.                                                                                                                                                                                                                                                                                                                                               |
 
 ---
 
@@ -725,13 +725,13 @@ it.
 
 #### Returns
 
-| Name                  | Type                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `start()`             | (`grant`, `raw`) => `Promise`\<`Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\>\>                                                                                                                                                                                                                      | Submit frozen mail or reuse its recorded Session admission receipt.                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `authenticateReply()` | (`mail`) => \| `Readonly`\<\{ `ancestors`: readonly `string`[]; `maxDepth`: `number`; `reply`: \{ `commandId`: `string`; `outcome`: `"completed"` \| `"failed"` \| `"cancelled"` \| `"interrupted"` \| `"outcome_unknown"`; `diagnostic?`: `string`; `agentId`: `string`; `sessionId`: `string`; \}; \}\> \| `undefined` | Match a reply to frozen mail and restore the caller's delegation path. Authenticate one arriving reply against the frozen mail this owner sent. It must be BirdDog's single reply key for that mail, mirror its sender and recipient exactly, carry BirdDog's settlement facts and, once the send's receipt is recorded, name that receipt's `commandId`. The result restores the caller's own delegation path and the verified reply; it never reads the reply's text or any settlement metadata. |
-| `receipt()`           | (`requestId`) => \| `Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\> \| `undefined`                                                                                                                                                                                                                    | Read an existing acceptance receipt without reserving or delivering mail. Read only the existing acceptance receipt; do not reserve or deliver mail.                                                                                                                                                                                                                                                                                                                                               |
-| `outstanding()`       | () => `Promise`\< \| `Readonly`\<\{ `agentId`: `string`; `sessionId`: `string`; `commandId`: `string`; `unreadable?`: `string`; \}\> \| `undefined`\>                                                                                                                                                                    | The delegated work this owner still waits on, if any. The newest delegation this owner sent whose work has not settled at its target, so the owner is still waiting for a reply; undefined when none.                                                                                                                                                                                                                                                                                              |
-| `delegate()`          | (`grant`, `task`) => `Promise`\< \| `Readonly`\<\{ `kind`: `"pending"`; `retryAfterMs`: `number`; \}\> \| [`AgentDelegationOutcome`](#agentdelegationoutcome)\>                                                                                                                                                          | Submit or poll the exact turn, yielding Agar Pending until settled.                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Name                  | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start()`             | (`grant`, `raw`) => `Promise`\<[`DelegationReceipt`](client.md#delegationreceipt)\>                                                                                                                                                                                                                                                                                                                                                                                   | Submit frozen mail or reuse its recorded Session admission receipt.                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `authenticateReply()` | (`mail`) => \| `Readonly`\<\{ `ancestors`: readonly `string`[]; `maxDepth`: `number`; `reply`: \| \{ `commandId`: `string`; `outcome`: `"completed"` \| `"failed"` \| `"cancelled"` \| `"interrupted"` \| `"outcome_unknown"`; `diagnostic?`: `string`; `agentId`: `string`; `sessionId`: `string`; \} \| \{ `outcome`: `"undeliverable"`; `reason`: `"recipient_offline"` \| `"recipient_left"`; `agentId`: `string`; `sessionId`: `string`; \}; \}\> \| `undefined` | Match a reply to frozen mail and restore the caller's delegation path. Authenticate one arriving reply against the frozen mail this owner sent. It must be BirdDog's single reply key for that mail, mirror its sender and recipient exactly, carry BirdDog's settlement facts and, once the send's receipt is recorded, name that receipt's `commandId`. The result restores the caller's own delegation path and the verified reply; it never reads the reply's text or any settlement metadata. |
+| `receipt()`           | (`requestId`) => \| `Readonly`\<\{ `status`: `"accepted"`; `commandId`: `string`; \}\> \| `undefined`                                                                                                                                                                                                                                                                                                                                                                 | Read an existing acceptance receipt without reserving or delivering mail. Read only the existing acceptance receipt; do not reserve or deliver mail.                                                                                                                                                                                                                                                                                                                                               |
+| `outstanding()`       | () => `Promise`\< \| `Readonly`\<\{ `agentId`: `string`; `sessionId`: `string`; `commandId`: `string`; `unreadable?`: `string`; \}\> \| `undefined`\>                                                                                                                                                                                                                                                                                                                 | The delegated work this owner still waits on, if any. The newest delegation this owner sent whose work has not settled at its target, so the owner is still waiting for a reply; undefined when none.                                                                                                                                                                                                                                                                                              |
+| `delegate()`          | (`grant`, `task`) => `Promise`\< \| `Readonly`\<\{ `kind`: `"pending"`; `retryAfterMs`: `number`; \}\> \| [`AgentDelegationOutcome`](#agentdelegationoutcome)\>                                                                                                                                                                                                                                                                                                       | Submit or poll the exact turn, yielding Agar Pending until settled.                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 ---
 

package/docs/api/http.md

@@ -88,6 +88,7 @@ function createShiitakeHttpRoutes(
     object &
     object &
     object &
+    object &
     object,
   "/",
   "/sessions/:sessionId/events"
@@ -110,5 +111,5 @@ Build Shiitake's typed HTTP routes around an existing Session owner.
 
 `Hono`\<[`ShiitakeHttpEnv`](#shiitakehttpenv), `object` & `object` & `object` &
 `object` & `object` & `object` & `object` & `object` & `object` & `object` &
-`object` & `object` & `object` & `object`, `"/"`,
+`object` & `object` & `object` & `object` & `object`, `"/"`,
 `"/sessions/:sessionId/events"`\>

package/docs/api/index.md

@@ -415,6 +415,7 @@ type ModelAcquisition = Readonly<{
   retryable: (message) => boolean;
   retryAfterMs?: (message) => number | undefined;
   failureReason?: (message) => string | undefined;
+  providerError?: (message) => string | undefined;
   release: () => Promise<void>;
 }>;
 ```
@@ -978,6 +979,18 @@ Re-exports [Accepted](client.md#accepted)
 
 ---
 
+### DelegationReceipt
+
+Re-exports [DelegationReceipt](client.md#delegationreceipt)
+
+---
+
+### Held
+
+Re-exports [Held](client.md#held)
+
+---
+
 ### ForkedSession
 
 Re-exports [ForkedSession](client.md#forkedsession)