@fungi.computer/shiitake 0.3.0 → 0.4.0

package/README.md

@@ -143,6 +143,16 @@ a Session performs no I/O. A client uses `createShiitakeClient` from the
 `/client` entry with the host's authorized transport. Releasing that client does
 not cancel host work.
 
+`session.readSettlement(commandId, { timeoutMs, signal })` returns that exact
+command's `CommandSettlement` (terminal, answer, usage and tool-call count),
+independent of the selected transcript branch. `timeoutMs` defaults to zero and
+is bounded to 30,000 ms. A pending command returns `undefined` at the deadline;
+an unknown command fails. Aborting the read never cancels the command.
+`agents.wait` uses this read and settlement hints, not a watch or a transcript
+read. In-process and HTTP clients share the contract; the HTTP encoding is
+`GET /sessions/:sessionId/settlement?commandId=...&timeoutMs=...`, with `null`
+for a pending command.
+
 Cancellation targets an accepted `commandId`. `too_late` is an ordinary outcome
 when that work can no longer be withdrawn. `session.abort()` atomically requests
 cancellation of the running turn and every queued prompt in that Session.
@@ -553,14 +563,14 @@ is ordinary follow-up work: an idle parent wakes a new run, and an active parent
 queues it behind the running work, which it never interrupts, so it runs next.
 Each fact on that line has one setter:
 
-| Fact                                | Setter                                                                               | Rule                                                                                                                                                                                                                                                                         |
-| ----------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Content                             | BirdDog `settlementReplies`                                                          | The child's last assistant text, or the host's cancellation text such as `Work cancelled by Ada.`, verbatim; with neither, one sentence naming the outcome.                                                                                                                  |
-| `reply.commandId`                   | BirdDog, from the child's accepted command                                           | Equals the parent's `agents.send` receipt `commandId`.                                                                                                                                                                                                                       |
-| `reply.outcome`, `reply.diagnostic` | BirdDog, from the exact Watchdog outcome and the child Session's terminal diagnostic | `completed`, `failed`, `interrupted`, `cancelled` and `outcome_unknown` stay distinct. Only `failed`, `interrupted` and `outcome_unknown` carry a diagnostic, bounded by `boundedDiagnostic`.                                                                                |
-| Authentication                      | `fleet.authenticateReply(mail)` at the parent's host                                 | The key is the frozen send's `<key>:reply:0`, `replyTo` is empty, `from`/`to` mirror the frozen send exactly, BirdDog's facts are present and, once the send's receipt is recorded, name its `commandId`. Otherwise the result is `undefined` and the host refuses the mail. |
-| Author and `meta.delegation.reply`  | The parent's host, only after authentication                                         | The author is the replying child Agent. The settling actor, a human canceller and the parent never author a reply.                                                                                                                                                           |
-| Model-visible provenance            | Shiitake, from the `reply` the host passes to `acceptMail(mail, meta, reply)`        | The model sees the line inside `<fungi_agent_reply agent_id=… session_id=… command_id=… outcome=… [diagnostic=…]>`.                                                                                                                                                          |
+| Fact                                | Setter                                                                               | Rule                                                                                                                                                                                                                                                                                                                         |
+| ----------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Content                             | BirdDog `settlementReplies`                                                          | The child's last assistant text, or the host's cancellation text such as `Work cancelled by Ada.`, verbatim; with neither, one sentence naming the outcome.                                                                                                                                                                  |
+| `reply.commandId`                   | BirdDog, from the child's accepted command                                           | Settled work replies carry the parent's `agents.send` receipt `commandId`; undeliverable replies have no command ID.                                                                                                                                                                                                         |
+| `reply.outcome`, `reply.diagnostic` | BirdDog, from the exact Watchdog outcome and the child Session's terminal diagnostic | `completed`, `failed`, `interrupted`, `cancelled` and `outcome_unknown` stay distinct. Only `failed`, `interrupted` and `outcome_unknown` carry a diagnostic, bounded by `boundedDiagnostic`. `undeliverable` instead carries `recipient_offline` or `recipient_left`.                                                       |
+| Authentication                      | `fleet.authenticateReply(mail)` at the parent's host                                 | The key is the frozen send's `<key>:reply:0`, `replyTo` is empty, and `from`/`to` mirror the frozen send exactly. Settled replies correlate with the receipt's `commandId`; undeliverable replies correlate only by the frozen mail key and typed reason. Otherwise the result is `undefined` and the host refuses the mail. |
+| Author and `meta.delegation.reply`  | The parent's host, only after authentication                                         | The author is the replying child Agent. The settling actor, a human canceller and the parent never author a reply.                                                                                                                                                                                                           |
+| Model-visible provenance            | Shiitake, from the `reply` the host passes to `acceptMail(mail, meta, reply)`        | The model sees the line inside `<fungi_agent_reply agent_id=… session_id=… [command_id=…] outcome=… [diagnostic=…] [reason=…]>`.                                                                                                                                                                                             |
 
 The provider role stays `user`. Shiitake renders the tag from the verified
 facts, never from the text, and neutralizes the tag in every other user-role

package/dist/agent-control.d.ts

@@ -1,5 +1,5 @@
 import { type CapabilitySource, type CapabilitySession } from "@fungi.computer/mycelium";
-import type { Accepted, CancelResult, ShiitakeAgent, ShiitakeSession } from "./client.js";
+import type { Accepted, CancelResult, Held, ShiitakeAgent, ShiitakeSession } from "./client.js";
 import { type ModelPreference } from "./model-preference.js";
 /**
  * Why a host refuses an archive or restore: the caller did not create the
@@ -42,15 +42,19 @@ export type AgentControlModel = Readonly<{
 export type AgentDelegationInput = Readonly<{
     /** Target Agent in the host's authorized scope. */
     agentId: string;
-    /** Target conversation on that Agent. */
-    sessionId: string;
     /** Work to admit with the requested delivery. */
     text: string;
     /** Caller-owned identity reused for retries and request-based recall. */
     requestId: string;
-    /** Steer the live turn or queue follow-up work with a durable reply. */
-    delivery: "steer" | "followUp";
-}>;
+}> & (Readonly<{
+    /** An existing conversation is required for a live steer. */
+    sessionId: string;
+    delivery: "steer";
+}> | Readonly<{
+    /** Omitted for an Agent whose first Session is created on acceptance. */
+    sessionId?: string;
+    delivery: "followUp";
+}>);
 /** Exact authorized destination and caller's original send identity. */
 export type AgentRecallInput = Readonly<{
     /** The authorized target Agent. */
@@ -78,7 +82,7 @@ export type AgentControlDirectory = Readonly<{
         archived?: boolean;
     }>) => Promise<readonly AgentControlAgent[]>;
     /** Host-scoped sends; follow-up work replies to the invoking Session. */
-    send?: (input: AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: AgentDelegationInvocation) => Promise<Accepted>;
+    send?: (input: AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: AgentDelegationInvocation) => Promise<Accepted | Held>;
     /** Recall under the same host-owned request identity as send. Never abort active work. */
     recall?: (input: AgentRecallInput, sourceSessionId: string, signal: AbortSignal) => Promise<CancelResult>;
     /** Present only when this host authorizes ordinary Agent creation. */
@@ -113,7 +117,7 @@ export type AgentControlDirectory = Readonly<{
     /** Optional host admission check before accepting a model-backed send. */
     checkModel?: (input: Readonly<{
         agentId: string;
-        sessionId: string;
+        sessionId?: string;
     }>, signal: AbortSignal) => Promise<void>;
     /** Recheck authorization and open one addressed Agent for this operation. */
     open: (agentId: string, signal: AbortSignal) => Promise<Readonly<{
@@ -122,13 +126,13 @@ export type AgentControlDirectory = Readonly<{
         release: () => Promise<void>;
     }>>;
 }>;
-/** Observe one durable terminal; timeout or abort closes observation, not the work. */
-export declare function waitForAgentTerminal(session: ShiitakeSession, commandId: string, timeoutMs: number, signal: AbortSignal, startedAt?: number): Promise<Readonly<{
-    commandId: string;
-    outcome: "completed" | "cancelled" | "failed" | "interrupted";
-    sequence: number;
-    diagnostic: string | null;
-    meta?: import("./extensions.js").Json;
+/** Await one exact durable terminal without opening a transcript observation. */
+export declare function waitForAgentSettlement(session: ShiitakeSession, commandId: string, timeoutMs: number, signal: AbortSignal, startedAt?: number): Promise<Readonly<{
+    acceptedSender: string | null;
+    terminal: import("./client.js").SessionTerminal;
+    content: string;
+    usage: readonly Pick<import("@fungi.computer/mule/effect").AssistantMessage, "provider" | "model" | "usage">[];
+    toolCalls: number;
 }>>;
 /**
  * A host's refusal of an Agent creating an Agent: the creator asked to give the

package/dist/agent-control.js

@@ -1,7 +1,6 @@
 import { CapabilityFailed, Mycelium, } from "@fungi.computer/mycelium";
 import { z } from "zod";
 import { ShiitakeError } from "./errors.js";
-import { reportCatchFailure } from "./internal/failure.js";
 import { AGENT_REPLY_TAG } from "./internal/woodstock/index.js";
 import { modelReasoningLevels, parseModelAddress, } from "./model-preference.js";
 const id = z.string().min(1).max(256);
@@ -49,14 +48,28 @@ const readInput = sessionInput.extend({
     /** A page's `oldestCursor`: read the page strictly before it. */
     before: pageCursor.nullable().default(null),
 });
-const sendArgs = sessionInput.extend({
-    requestId,
-    text: z
-        .string()
-        .min(1)
-        .max(256 * 1024),
-    delivery: z.enum(["steer", "followUp"]),
-});
+const sendArgs = z.discriminatedUnion("delivery", [
+    z.strictObject({
+        agentId: id,
+        sessionId: id,
+        requestId,
+        text: z
+            .string()
+            .min(1)
+            .max(256 * 1024),
+        delivery: z.literal("steer"),
+    }),
+    z.strictObject({
+        agentId: id,
+        sessionId: id.optional(),
+        requestId,
+        text: z
+            .string()
+            .min(1)
+            .max(256 * 1024),
+        delivery: z.literal("followUp"),
+    }),
+]);
 const sendInput = sendArgs;
 const cancelInput = sessionInput.extend({ commandId: id });
 const recallInput = sessionInput.extend({ requestId });
@@ -113,8 +126,6 @@ const terminalIdentityOutput = z.strictObject({
 });
 /** Characters of a completed command's final assistant text that wait returns. */
 const finalTextLimit = 16_384;
-/** Messages scanned for that text: the same bound as one `read` page. */
-const finalTextReadLimit = 200;
 const diagnosticField = { diagnostic: z.string().max(200) };
 const finalTextFields = {
     text: z.string().max(finalTextLimit),
@@ -130,6 +141,12 @@ const acceptedOutput = z.strictObject({
     status: z.literal("accepted"),
     commandId: id,
 });
+const heldOutput = z.strictObject({
+    status: z.literal("held"),
+    reason: z.literal("recipient_offline"),
+    message: z.literal("waiting: recipient offline"),
+});
+const delegationReceiptOutput = z.union([acceptedOutput, heldOutput]);
 const cancelOutput = z.discriminatedUnion("status", [
     acceptedOutput,
     z.strictObject({ status: z.literal("unknown") }),
@@ -229,106 +246,15 @@ async function withAgent(directory, operation, agentId, signal, use) {
         await opened.release();
     }
 }
-function terminalFor(snapshot, commandId) {
-    return snapshot.terminals.find((terminal) => terminal.commandId === commandId);
-}
-function createCancellation(signal, timeoutMs) {
-    let timer;
-    let onAbort;
-    const promise = new Promise((_, reject) => {
-        onAbort = () => {
-            reject(signal.reason instanceof Error
-                ? signal.reason
-                : new Error("Agent wait cancelled"));
-        };
-        if (signal.aborted) {
-            onAbort();
-            return;
-        }
-        signal.addEventListener("abort", onAbort, { once: true });
-        timer = setTimeout(() => {
-            reject(new Error("Agent wait timed out"));
-        }, timeoutMs);
-    });
-    return {
-        promise,
-        dispose: () => {
-            if (timer !== undefined)
-                clearTimeout(timer);
-            if (onAbort !== undefined)
-                signal.removeEventListener("abort", onAbort);
-        },
-    };
-}
-async function raceCancellation(value, cancellation) {
-    return Promise.race([value, cancellation]);
-}
-/** The text of the command's newest assistant message in a bounded page, if it has any. */
-function finalAssistantText(snapshot, commandId) {
-    for (let index = snapshot.messages.length - 1; index >= 0; index -= 1) {
-        const { commandId: owner, value } = snapshot.messages[index] ?? {};
-        if (owner !== commandId || value?.role !== "assistant")
-            continue;
-        const text = value.content
-            .flatMap((block) => (block.type === "text" ? [block.text] : []))
-            .join("");
-        return text.length === 0 ? undefined : text;
-    }
-    return undefined;
-}
-/** Observe one durable terminal; timeout or abort closes observation, not the work. */
-export async function waitForAgentTerminal(session, commandId, timeoutMs, signal, startedAt = Date.now()) {
-    const remaining = Math.max(1, timeoutMs - (Date.now() - startedAt));
-    const cancellation = createCancellation(signal, remaining);
-    let watch;
-    let lateWatch;
-    let disposed = false;
-    const watchPromise = session.watch();
-    void watchPromise.then((resolvedWatch) => {
-        if (watch === undefined) {
-            if (disposed)
-                void resolvedWatch.close().catch((cause) => {
-                    reportCatchFailure("late-agent-watch-close", cause);
-                });
-            else
-                lateWatch = resolvedWatch;
-        }
-    }, () => {
-        return Promise.resolve();
+/** Await one exact durable terminal without opening a transcript observation. */
+export async function waitForAgentSettlement(session, commandId, timeoutMs, signal, startedAt = Date.now()) {
+    const settled = await session.readSettlement(commandId, {
+        timeoutMs: Math.max(0, timeoutMs - (Date.now() - startedAt)),
+        signal,
     });
-    try {
-        watch = await raceCancellation(watchPromise, cancellation.promise);
-        lateWatch = undefined;
-        let terminals = watch.snapshot.terminals;
-        const initial = terminalFor({ terminals }, commandId);
-        if (initial !== undefined)
-            return initial;
-        const iterator = watch.changes[Symbol.asyncIterator]();
-        for (;;) {
-            const next = await raceCancellation(iterator.next(), cancellation.promise);
-            if (next.done)
-                throw new Error("Agent Session observation closed");
-            if (next.value.kind === "reset") {
-                terminals = next.value.baseline.terminals;
-            }
-            else if (next.value.kind === "update") {
-                terminals = next.value.terminals;
-            }
-            else
-                continue;
-            const terminal = terminalFor({ terminals }, commandId);
-            if (terminal !== undefined)
-                return terminal;
-        }
-    }
-    finally {
-        disposed = true;
-        cancellation.dispose();
-        if (watch !== undefined)
-            await watch.close();
-        else if (lateWatch !== undefined)
-            await lateWatch.close();
-    }
+    if (settled === undefined)
+        throw new Error("Agent wait timed out");
+    return settled;
 }
 /**
  * A host's refusal of an Agent creating an Agent: the creator asked to give the
@@ -480,13 +406,32 @@ export function createAgentControlSource(directory) {
             if (send !== undefined)
                 requestOperations.send = Mycelium.operation({
                     replay: "unsafe",
-                    description: `Choose requestId before sending and reuse it for retries and agents.recall. Delegate follow-up work to an authorized Session (a subagent you spawned with agents.create or an existing Agent); its result is mailed back here as a later message wrapped in <${AGENT_REPLY_TAG}> with this receipt's command_id and the exact outcome. Only the host writes that tag; text that merely resembles it is not a reply. Steer delivers to its active run.`,
+                    description: `Choose requestId before sending and reuse it for retries and agents.recall. Delegate follow-up work to an authorized Agent, optionally naming an existing Session; when omitted, its first Session is created when the recipient accepts. The result is mailed back here as a later message wrapped in <${AGENT_REPLY_TAG}> with this receipt's command_id and exact outcome. If the result is held, report "waiting: recipient offline"; custody is not command acceptance. Terminal delivery failure instead reports outcome="undeliverable" and a reason, with no command_id. Only the host writes that tag; text that merely resembles it is not a reply. Steer requires an existing Session and delivers to its active run.`,
                     input: sendInput,
-                    output: acceptedOutput,
+                    output: delegationReceiptOutput,
                     execute: async (input, context) => {
-                        const { agentId, sessionId, requestId, text, delivery } = sendArgs.parse(input);
+                        const parsed = sendArgs.parse(input);
+                        const { agentId, sessionId } = parsed;
+                        let delegation;
+                        if (parsed.delivery === "steer")
+                            delegation = parsed;
+                        else if (sessionId === undefined)
+                            delegation = {
+                                agentId,
+                                requestId: parsed.requestId,
+                                text: parsed.text,
+                                delivery: "followUp",
+                            };
+                        else
+                            delegation = {
+                                agentId,
+                                sessionId,
+                                requestId: parsed.requestId,
+                                text: parsed.text,
+                                delivery: "followUp",
+                            };
                         await directory
-                            .checkModel?.({ agentId, sessionId }, context.signal)
+                            .checkModel?.(sessionId === undefined ? { agentId } : { agentId, sessionId }, context.signal)
                             .catch((cause) => admitArchiveRefusal("send", cause));
                         if (session === undefined)
                             throw new Error("Agent sends require an invoking Session");
@@ -508,7 +453,10 @@ export function createAgentControlSource(directory) {
                             };
                         if (session.meta !== undefined)
                             invocation = { ...invocation, meta: session.meta };
-                        return acceptedOutput.parse(await send({ agentId, sessionId, text, requestId, delivery }, session.sessionId, context.signal, invocation).catch((cause) => admitArchiveRefusal("send", cause)));
+                        const receipt = await send(delegation, session.sessionId, context.signal, invocation).catch((cause) => admitArchiveRefusal("send", cause));
+                        return delegationReceiptOutput.parse(receipt.status === "accepted"
+                            ? { status: receipt.status, commandId: receipt.commandId }
+                            : receipt);
                     },
                 });
             if (recall !== undefined)
@@ -603,23 +551,15 @@ export function createAgentControlSource(directory) {
                                     output: terminalOutput,
                                     execute: async ({ agentId, sessionId, commandId, timeoutMs }, context) => {
                                         const startedAt = Date.now();
-                                        const { settled, text } = await withAgent(directory, "wait", agentId, context.signal, async (agent) => {
-                                            const session = agent.session(sessionId);
-                                            const terminal = await waitForAgentTerminal(session, commandId, timeoutMs, context.signal, startedAt);
-                                            if (terminal.outcome !== "completed")
-                                                return { settled: terminal, text: undefined };
-                                            return {
-                                                settled: terminal,
-                                                text: finalAssistantText(await session.read({ limit: finalTextReadLimit }), terminal.commandId),
-                                            };
-                                        });
+                                        const settlement = await withAgent(directory, "wait", agentId, context.signal, (agent) => waitForAgentSettlement(agent.session(sessionId), commandId, timeoutMs, context.signal, startedAt));
+                                        const { terminal: settled, content: text } = settlement;
                                         const result = {
                                             commandId: settled.commandId,
                                             outcome: settled.outcome,
                                         };
                                         if (settled.diagnostic !== null)
                                             result.diagnostic = settled.diagnostic.slice(0, 200);
-                                        if (text !== undefined) {
+                                        if (settled.outcome === "completed" && text.length > 0) {
                                             result.text = text.slice(0, finalTextLimit);
                                             result.truncated = text.length > finalTextLimit;
                                         }

package/dist/client-wire.d.ts

@@ -1,9 +1,8 @@
+import type { CommandSettlement } from "./internal/contracts.js";
 import * as Schema from "effect/Schema";
-import type { Accepted, CancelResult, WithdrawResult, ForkedSession, SessionFrame, SessionPendingPrompt, SessionSnapshot, SessionSummaryPage, SessionTerminal } from "./client.js";
+import type { Accepted, DelegationReceipt, Held, CancelResult, WithdrawResult, ForkedSession, SessionFrame, SessionPendingPrompt, SessionSnapshot, SessionSummaryPage } from "./client.js";
 import { ShiitakeError } from "./errors.js";
 import type { ExtensionSlotV0, ExtensionStatusV0, Json } from "./extensions.js";
-/** Existing terminal wire grammar, shared by exact host settlement facts. */
-export declare const SessionTerminalSchema: Schema.Codec<SessionTerminal>;
 export declare const SessionSnapshotSchema: Schema.Struct<{
     readonly sessionId: Schema.String;
     readonly cursor: Schema.NullOr<Schema.String>;
@@ -185,6 +184,12 @@ export declare const SessionSnapshotSchema: Schema.Struct<{
 export declare const SessionFrameSchema: Schema.Codec<SessionFrame>;
 /** Decode a durable command acceptance value at an RPC boundary. */
 export declare const AcceptedSchema: Schema.Codec<Accepted>;
+/** Parse the relay's custody acknowledgment without implying Agent acceptance. */
+export declare const HeldSchema: Schema.Codec<Held>;
+/** A delegated send is accepted by its owner or held in durable mail custody. */
+export declare const DelegationReceiptSchema: Schema.Codec<DelegationReceipt>;
+/** Decode one delegated send's acceptance or durable-custody result. */
+export declare function parseDelegationReceipt(value: string): DelegationReceipt;
 /** Decode the owner's atomic request resolution. */
 export declare function parseWithdrawResult(value: string): WithdrawResult;
 /** Parse one serialized extension status. */
@@ -201,6 +206,10 @@ export declare function parseCancelResult(value: string): CancelResult;
 export declare function parseLatestPendingPrompt(value: string): SessionPendingPrompt | null;
 /** Parse one serialized fork result using Shiitake's public client grammar. */
 export declare function parseForkedSession(value: string): ForkedSession;
+/** Exact command facts shared by Session clients and host fleet transports. */
+export declare const commandSettlementSchema: Schema.Codec<CommandSettlement>;
+/** A timeout is null on the JSON wire and undefined at the client boundary. */
+export declare function parseCommandSettlement(value: string): CommandSettlement | undefined;
 /** Parse one serialized snapshot using Shiitake's public client grammar. */
 export declare function parseSessionSnapshot(value: string): SessionSnapshot;
 /** Parse one serialized frame using Shiitake's public client grammar. */

package/dist/client-wire.js

@@ -5,7 +5,7 @@ import * as Schema from "effect/Schema";
 import { ShiitakeError, ShiitakeErrorWireSchema } from "./errors.js";
 import { JsonValueSchema } from "./internal/json-value.js";
 import { HostMetaSchema } from "./internal/host-meta.js";
-import { StoredPiMessageSchema, ExtensionAdmissionOriginSchema, } from "./internal/woodstock/index.js";
+import { StoredPiMessageSchema, usage, ExtensionAdmissionOriginSchema, } from "./internal/woodstock/index.js";
 const ExtensionOriginSchema = ExtensionAdmissionOriginSchema.mapFields(({ extensionId, correlation }) => ({ extensionId, correlation }));
 const SessionMessageSchema = Schema.Struct({
     requestId: Schema.optionalKey(Schema.String),
@@ -82,14 +82,9 @@ const ExtensionStatusSchema = Schema.Struct({
     stoppedAt: Schema.NullOr(Schema.Number),
 });
 /** Existing terminal wire grammar, shared by exact host settlement facts. */
-export const SessionTerminalSchema = Schema.Struct({
+const SessionTerminalSchema = Schema.Struct({
     commandId: Schema.String,
-    outcome: Schema.Literals([
-        "completed",
-        "cancelled",
-        "failed",
-        "interrupted",
-    ]),
+    outcome: Schema.Literals(["completed", "cancelled", "failed", "interrupted"]),
     sequence: Schema.Int.check(Schema.isGreaterThan(0)),
     diagnostic: Schema.NullOr(Schema.String),
     meta: Schema.optionalKey(HostMetaSchema),
@@ -169,6 +164,10 @@ export const SessionSnapshotSchema = Schema.Struct({
     context: Schema.optionalKey(SessionContextSchema),
 });
 export const SessionFrameSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("activity"),
+        activity: SessionActivitySchema,
+    }),
     Schema.Struct({
         kind: Schema.Literal("tool_output"),
         toolOutput: ToolOutputSchema,
@@ -205,7 +204,21 @@ export const SessionFrameSchema = Schema.Union([
 export const AcceptedSchema = Schema.Struct({
     status: Schema.Literal("accepted"),
     commandId: Schema.String,
+    sessionId: Schema.optionalKey(Schema.String),
 });
+/** Parse the relay's custody acknowledgment without implying Agent acceptance. */
+export const HeldSchema = Schema.Struct({
+    status: Schema.Literal("held"),
+    reason: Schema.Literal("recipient_offline"),
+    message: Schema.Literal("waiting: recipient offline"),
+});
+/** A delegated send is accepted by its owner or held in durable mail custody. */
+export const DelegationReceiptSchema = Schema.Union([AcceptedSchema, HeldSchema]);
+const decodeDelegationReceipt = Schema.decodeUnknownSync(Schema.fromJsonString(DelegationReceiptSchema), { onExcessProperty: "error" });
+/** Decode one delegated send's acceptance or durable-custody result. */
+export function parseDelegationReceipt(value) {
+    return decodeDelegationReceipt(value);
+}
 const UnknownRequestSchema = Schema.Struct({
     status: Schema.Literal("unknown"),
 });
@@ -266,6 +279,18 @@ export function parseLatestPendingPrompt(value) {
 export function parseForkedSession(value) {
     return decodeForkedSession(value);
 }
+/** Exact command facts shared by Session clients and host fleet transports. */
+export const commandSettlementSchema = Schema.Struct({
+    acceptedSender: Schema.NullOr(Schema.String),
+    terminal: SessionTerminalSchema,
+    content: Schema.String,
+    usage: Schema.Array(Schema.Struct({ provider: Schema.String, model: Schema.String, usage })),
+    toolCalls: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+});
+/** A timeout is null on the JSON wire and undefined at the client boundary. */
+export function parseCommandSettlement(value) {
+    return (Schema.decodeUnknownSync(Schema.fromJsonString(Schema.NullOr(commandSettlementSchema)))(value) ?? undefined);
+}
 /** Parse one serialized snapshot using Shiitake's public client grammar. */
 export function parseSessionSnapshot(value) {
     return decodeSnapshot(value);

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import type { SessionAttention } from "./session-attention.js";
+import type { CommandSettlement } from "./internal/contracts.js";
+export type { CommandSettlement } from "./internal/contracts.js";
 export { type SessionAttention } from "./session-attention.js";
 import type { SandboxFailureEvent } from "@fungi.computer/mycelium";
 import type { ModelPreference } from "./internal/model-preference.js";
@@ -7,7 +9,7 @@ import type { ExtensionSlotV0, ExtensionStatusV0, Json } from "./extensions.js";
 import type { AbortCommand, BranchCommand, CompactCommand, OperatorCommand, TitleCommand, CancelCommand, ForkCommand, PromptCommand, PromptDelivery, SessionCommand } from "./internal/client-boundary.js";
 export { createShiitakeClient, type ShiitakeClientOptions, } from "./remote-client.js";
 export { bindAgentExtension, bindSessionExtension, type BoundAgentExtensionV0, type BoundCallV0, type BoundSessionExtensionV0, type ExtensionViewV0, type ScopedCommandsV0, } from "./extension-client.js";
-export { AcceptedSchema, parseAccepted, parseCancelResult, parseLatestPendingPrompt, parseWithdrawResult, parseForkedSession, parseSessionFrame, parseSessionSnapshot, parseSessionSummaryPage, parseShiitakeError, } from "./client-wire.js";
+export { AcceptedSchema, DelegationReceiptSchema, HeldSchema, parseAccepted, parseDelegationReceipt, parseCancelResult, parseLatestPendingPrompt, parseWithdrawResult, parseForkedSession, parseSessionFrame, parseSessionSnapshot, parseSessionSummaryPage, parseShiitakeError, } from "./client-wire.js";
 export type { AbortCommand, BranchCommand, CompactCommand, CancelCommand, ForkCommand, OperatorCommand, PromptCommand, PromptDelivery, SessionCommand, TitleCommand, } from "./internal/client-boundary.js";
 /** Semantic acknowledgement returned after one durable acceptance commit. */
 export type Accepted = Readonly<{
@@ -15,7 +17,17 @@ export type Accepted = Readonly<{
     status: "accepted";
     /** Owner-issued durable identity for the accepted work. */
     commandId: string;
+    /** The recipient's Session, when this is delegated mail acceptance. */
+    sessionId?: string;
 }>;
+/** Durable relay custody, not acceptance of a command by the recipient. */
+export type Held = Readonly<{
+    status: "held";
+    reason: "recipient_offline";
+    message: "waiting: recipient offline";
+}>;
+/** A delegation send can be accepted by the Agent or held by its relay. */
+export type DelegationReceipt = Accepted | Held;
 /**
  * Cancelling found nothing left to cancel: the command is unknown to this
  * Session, has already started (for an `onlyIfPending` cancel) or has already
@@ -311,11 +323,16 @@ export type SessionSnapshot = Readonly<{
     extensions: SessionExtensionSlots;
     /** Open requests for human attention from extensions. */
     attention: readonly SessionAttention[];
-    /** Context use at the cursor; absent until the Session has context. */
+    /** Context use at the tip; before reads carry this tip figure too, and it
+     * is absent before the Session has context. */
     context?: SessionContext;
 }>;
 /** One bounded replay or live frame. */
 export type SessionFrame = Readonly<{
+    /** Process-local activity change for the Session's current queue head. */
+    kind: "activity";
+    activity: SessionActivity;
+}> | Readonly<{
     kind: "tool_output";
     toolOutput: readonly SessionToolOutput[];
     activity: SessionActivity;
@@ -344,7 +361,12 @@ export type SessionFrame = Readonly<{
     extensions: SessionExtensionSlots;
     /** Open requests for human attention from extensions. */
     attention: readonly SessionAttention[];
-    /** Context use at this cursor; absent until the Session has context. */
+    /**
+     * Context use at the Session tip when the update moved history and is
+     * the final page; live pages with more to come and non-final replay pages
+     * carry no figure. Absent before the Session has context; absent figures
+     * leave the last one in place.
+     */
     context?: SessionContext;
 }> | Readonly<{
     /** Bounded process-local assistant progress. */
@@ -425,6 +447,15 @@ export type ShiitakeSession = Readonly<{
     }>;
     /** Read a bounded durable baseline. */
     read: (input?: ReadOptions) => Promise<SessionSnapshot>;
+    /**
+     * Read one exact command's settlement, independent of the selected lineage.
+     * Wait at most timeoutMs (0–30000, default 0) for a settlement hint.
+     * Timeout returns undefined; abort releases only the read, never the work.
+     */
+    readSettlement: (commandId: string, options?: Readonly<{
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }>) => Promise<CommandSettlement | undefined>;
     /** Subscribe to strict-after replay and live frames. */
     subscribe: (input: SubscribeOptions) => AsyncIterable<SessionFrame>;
     /** Open a race-safe baseline plus live changes resource. */

package/dist/client.js

@@ -1,4 +1,4 @@
 export {} from "./session-attention.js";
 export { createShiitakeClient, } from "./remote-client.js";
 export { bindAgentExtension, bindSessionExtension, } from "./extension-client.js";
-export { AcceptedSchema, parseAccepted, parseCancelResult, parseLatestPendingPrompt, parseWithdrawResult, parseForkedSession, parseSessionFrame, parseSessionSnapshot, parseSessionSummaryPage, parseShiitakeError, } from "./client-wire.js";
+export { AcceptedSchema, DelegationReceiptSchema, HeldSchema, parseAccepted, parseDelegationReceipt, parseCancelResult, parseLatestPendingPrompt, parseWithdrawResult, parseForkedSession, parseSessionFrame, parseSessionSnapshot, parseSessionSummaryPage, parseShiitakeError, } from "./client-wire.js";

package/dist/cloudflare.d.ts

@@ -133,7 +133,9 @@ export type CloudflareShiitake = ShiitakeOwnerAgent & Readonly<{
      * Admit host-authorized mail, preserving its parent address and opaque
      * metadata. `reply` is the host's authentication of a delegated reply.
      */
-    acceptMail: (mail: BirdDogMail, meta?: Json, reply?: VerifiedAgentReply) => Promise<Accepted>;
+    acceptMail: (mail: BirdDogMail, meta?: Json, reply?: VerifiedAgentReply, stageAcceptedNotice?: (mail: BirdDogMail) => void, 
+    /** Grants for a new Session, written in the acceptance transaction. */
+    sessionGrantDelivery?: (sessionId: string) => GrantsDelivery) => Promise<Accepted>;
     /** Deliver the native owner alarm to the bound runtime. */
     alarm: () => Promise<void>;
     /** Snapshot actual live executors, independent of instruction leases. */

package/dist/cloudflare.js

@@ -333,10 +333,10 @@ export function makeCloudflareShiitake(unnamed, options) {
         return Object.freeze({
             ...handle,
             readSettlement: (sessionId, commandId) => runShiitakePromise(readSettlement(sessionId, commandId)),
-            acceptMail: (mail, meta, reply) => {
+            acceptMail: (mail, meta, reply, stageAcceptedNotice, sessionGrantDelivery) => {
                 if (options.mailRoom === undefined)
                     return Promise.reject(runtimeFailure("unavailable", "Addressed mail is unavailable"));
-                return runShiitakePromise(acceptMail(mail, meta, reply));
+                return runShiitakePromise(acceptMail(mail, meta, reply, stageAcceptedNotice, sessionGrantDelivery));
             },
             alarm: host.alarm,
             activeSessions: () => runShiitakePromise(activeSessions),