@fungi.computer/shiitake 0.3.1 → 0.5.0

package/dist/internal/woodstock/session-entry.d.ts

@@ -70,13 +70,18 @@ declare const StoredSessionEntrySchema: Schema.Union<readonly [Schema.Struct<{
     readonly kind: Schema.Literal<"command">;
     readonly meta: Schema.optionalKey<Schema.Codec<import("../../extensions.js").Json, import("../../extensions.js").Json, never, never>>;
     /** Present only when the host admitted this line as a verified Agent reply. */
-    readonly reply: Schema.optionalKey<Schema.Struct<{
+    readonly reply: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
         readonly commandId: Schema.String;
         readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
         readonly diagnostic: Schema.optionalKey<Schema.String>;
         readonly agentId: Schema.String;
         readonly sessionId: Schema.String;
-    }>>;
+    }>, Schema.Struct<{
+        readonly outcome: Schema.Literal<"undeliverable">;
+        readonly reason: Schema.Literals<readonly ["recipient_offline", "recipient_left"]>;
+        readonly agentId: Schema.String;
+        readonly sessionId: Schema.optionalKey<Schema.String>;
+    }>]>>;
     readonly delivery: Schema.optionalKey<Schema.Literals<readonly ["steer", "followUp"]>>;
     readonly requestId: Schema.String;
     readonly targetWorkId: Schema.optionalKey<Schema.String>;
@@ -357,6 +362,11 @@ export declare function decodeStoredSessionEntry(value: string): Result.Result<{
         readonly outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
         readonly agentId: string;
         readonly diagnostic?: string;
+    } | {
+        readonly reason: "recipient_offline" | "recipient_left";
+        readonly outcome: "undeliverable";
+        readonly agentId: string;
+        readonly sessionId?: string;
     };
     readonly targetWorkId?: string;
 } | {
@@ -513,8 +523,8 @@ export declare function decodeStoredSessionEntry(value: string): Result.Result<{
     readonly workId: string;
     readonly result: "failed";
     readonly trigger: "manual" | "threshold" | "overflow";
-    readonly usage?: Usage;
     readonly diagnostic?: string;
+    readonly usage?: Usage;
 } | {
     readonly kind: "compaction_notice";
     readonly workId: string;

package/dist/internal/woodstock/session-entry.js

@@ -147,6 +147,7 @@ const assistantMessage = Schema.Struct({
         data: Schema.optionalKey(jsonValue),
     })),
     errorMessage: Schema.optionalKey(Schema.String),
+    providerError: Schema.optionalKey(Schema.String),
     rawStopReason: Schema.optionalKey(Schema.String),
     providerThinkingLevel: Schema.optionalKey(Schema.String),
     endTurn: Schema.optionalKey(Schema.Boolean),

package/dist/internal/woodstock/session-store.d.ts

@@ -254,6 +254,10 @@ export declare function readActiveToolForWork(owner: SqliteOwner, sessionId: str
 export declare function createStoredSession(owner: SqliteOwner, requestId: string, 
 /** Refuses a new Session under storage pressure; replays skip it. */
 admitNew: () => void): string;
+/** Reserve a Session while the caller owns the enclosing SQLite transaction. */
+export declare function createStoredSessionWithinTransaction(owner: SqliteOwner, requestId: string, 
+/** Refuses a new Session under storage pressure; replays skip it. */
+admitNew: () => void): string;
 /**
  * Permanently remove one idle Session: its entries, command admissions,
  * creation receipt and inbox row, so a retried creation request reserves a

package/dist/internal/woodstock/session-store.js

@@ -790,23 +790,27 @@ function ensureSession(owner, sessionId) {
 export function createStoredSession(owner, requestId, 
 /** Refuses a new Session under storage pressure; replays skip it. */
 admitNew) {
-    return owner.transactionSync(() => {
-        const existing = owner.sql
-            .exec("SELECT session_id FROM session_creation_receipts WHERE request_id = ?", requestId)
-            .toArray();
-        const first = existing[0];
-        if (first !== undefined) {
-            const decoded = decodeSessionCreationReceiptRow(first);
-            if (decoded._tag === "Failure")
-                throw unavailable("Session creation receipt is invalid");
-            return decoded.success.session_id;
-        }
-        admitNew();
-        const sessionId = sessionIds.session.generate();
-        ensureSession(owner, sessionId);
-        owner.sql.exec("INSERT INTO session_creation_receipts (request_id, session_id) VALUES (?, ?)", requestId, sessionId);
-        return sessionId;
-    });
+    return owner.transactionSync(() => createStoredSessionWithinTransaction(owner, requestId, admitNew));
+}
+/** Reserve a Session while the caller owns the enclosing SQLite transaction. */
+export function createStoredSessionWithinTransaction(owner, requestId, 
+/** Refuses a new Session under storage pressure; replays skip it. */
+admitNew) {
+    const existing = owner.sql
+        .exec("SELECT session_id FROM session_creation_receipts WHERE request_id = ?", requestId)
+        .toArray();
+    const first = existing[0];
+    if (first !== undefined) {
+        const decoded = decodeSessionCreationReceiptRow(first);
+        if (decoded._tag === "Failure")
+            throw unavailable("Session creation receipt is invalid");
+        return decoded.success.session_id;
+    }
+    admitNew();
+    const sessionId = sessionIds.session.generate();
+    ensureSession(owner, sessionId);
+    owner.sql.exec("INSERT INTO session_creation_receipts (request_id, session_id) VALUES (?, ?)", requestId, sessionId);
+    return sessionId;
 }
 /**
  * Permanently remove one idle Session: its entries, command admissions,
@@ -2280,9 +2284,12 @@ reply) {
 function sameReply(left, right) {
     return (left?.agentId === right?.agentId &&
         left?.sessionId === right?.sessionId &&
-        left?.commandId === right?.commandId &&
         left?.outcome === right?.outcome &&
-        left?.diagnostic === right?.diagnostic);
+        (left?.outcome === "undeliverable"
+            ? right?.outcome === "undeliverable" && left.reason === right.reason
+            : right?.outcome !== "undeliverable" &&
+                left?.commandId === right?.commandId &&
+                left?.diagnostic === right?.diagnostic));
 }
 /**
  * Write one decoded admission (a prompt or a compaction request) and its one

package/dist/remote-client.js

@@ -10,7 +10,7 @@ import * as Schema from "effect/Schema";
 import * as Scope from "effect/Scope";
 import * as Sink from "effect/Sink";
 import * as Stream from "effect/Stream";
-import { parseAccepted, parseWithdrawResult, parseCancelResult, parseLatestPendingPrompt, parseForkedSession, parseCreatedSession, parseDeletedSession, parseExtensionOutput, parseExtensionStatus, parseExtensionStatuses, parseSessionFrame, parseSessionSnapshot, parseSessionSummaryPage, parseShiitakeError, } from "./client-wire.js";
+import { parseAccepted, parseCommandSettlement, parseWithdrawResult, parseCancelResult, parseLatestPendingPrompt, parseForkedSession, parseCreatedSession, parseDeletedSession, parseExtensionOutput, parseExtensionStatus, parseExtensionStatuses, parseSessionFrame, parseSessionSnapshot, parseSessionSummaryPage, parseShiitakeError, } from "./client-wire.js";
 import { ShiitakeError } from "./errors.js";
 import { decodeClientReadOptions, decodeClientSessionCreationRequestId, decodeClientPageCursor, decodeClientSessionId, decodeClientSubscribeOptions, } from "./internal/client-boundary.js";
 import { toPromiseAgent } from "./internal/effect-client.js";
@@ -248,6 +248,10 @@ function makeRemoteEffectAgent(options) {
                     params.set("includeSandboxFailures", "true");
                 return request((signal) => fetch(`${addressedUrl}?${params.toString()}`, { signal }), parseSessionSnapshot, "Session read");
             })),
+            readSettlement: (commandId, timeoutMs = 0) => ensureOpen.pipe(Effect.andThen(request((signal) => fetch(`${addressedUrl}/settlement?${new URLSearchParams({
+                commandId,
+                timeoutMs: String(timeoutMs),
+            }).toString()}`, { signal }), parseCommandSettlement, "Command settlement"))),
             subscribe: (input) => Stream.unwrap(ensureOpen.pipe(Effect.andThen(Effect.try({
                 try: () => decodeClientSubscribeOptions(input),
                 catch: (error) => error instanceof ShiitakeError

package/dist/testing.d.ts

@@ -40,8 +40,11 @@ export type MemoryHost = Readonly<{
     agent: ShiitakeOwnerAgent;
     /** Invoke one canonical reconciliation tick; no timer runs in the background. */
     reconcile: () => Promise<void>;
-    /** Drain pending Agent work with a 1–1,000 tick budget (default 1,000). */
-    settle: (sessionId: string, maxTicks?: number) => Promise<SessionSnapshot>;
+    /** Drain pending Agent work with a 1–1,000 tick budget (default 1,000).
+     * The optional test hook runs after pending work ends, before the snapshot
+     * context read, so load tests can end a timed turn at the terminal.
+     */
+    settle: (sessionId: string, maxTicks?: number, beforeRead?: () => Promise<void>) => Promise<SessionSnapshot>;
     /** Close the Agent and only the database owned by this helper. */
     close: () => Promise<void>;
 }>;

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>;
 }>;