@fungi.computer/shiitake 0.3.1 → 0.5.0

package/dist/fleet.d.ts

@@ -1,14 +1,34 @@
+export { commandSettlementSchema } from "./client-wire.js";
 import { type VerifiedAgentReply } from "./internal/woodstock/index.js";
 import type { CommandSettlement } from "./internal/contracts.js";
 import { type Pending } from "@fungi.computer/agar";
 import type { BirdDogMail } from "@fungi.computer/bird-dog";
-import * as Schema from "effect/Schema";
-import { type Accepted, type ShiitakeAgent } from "./client.js";
+import { type Accepted, type DelegationReceipt, type ShiitakeAgent } from "./client.js";
 import type { Json } from "./extensions.js";
 import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
 import { type CairnId } from "@fungi.computer/cairn/id";
 import { z } from "zod";
 import { type AuthorMeta } from "@fungi.computer/agar/agents";
+/** Inputs shared by Local and hosted delegation request identity. */
+export type AgentDelegationRequestKeyInput = Readonly<{
+    owner: Readonly<{
+        kind: "local";
+        agentId: string;
+    }> | Readonly<{
+        kind: "hosted";
+        scopeId: string;
+        agentId: string;
+    }>;
+    sourceSessionId: string;
+    targetAgentId: string;
+    requestId: string;
+}>;
+/**
+ * One idempotency identity for a caller-owned delegation request.
+ * The target Session is deliberately excluded: a sessionless send learns it
+ * only after acceptance, when recall must still resolve the original receipt.
+ */
+export declare function agentDelegationRequestKey(input: AgentDelegationRequestKeyInput): Promise<string>;
 /** Operations explicitly admitted by the host. */
 export declare const agentActionSchema: z.ZodEnum<{
     send: "send";
@@ -69,7 +89,7 @@ export declare class AgentGrantError extends Error {
 export declare function assertAgentGrant(grant: AgentGrant, action: AgentAction, agentId?: string): void;
 /** Stable Agent identities, retained across host compositions. */
 export declare const agentIds: Readonly<{
-    readonly agent: import("@fungi.computer/cairn/id").IdCodec<"agent", "agent", 1>;
+    readonly agent: import("@fungi.computer/cairn").IdCodec<"agent", "agent", 1>;
 }>;
 /** An ordinary Agent directory identity. */
 export type AgentId = CairnId<"agent", "agent">;
@@ -169,8 +189,6 @@ export declare const agentDelegationTaskSchema: z.ZodLazy<z.ZodObject<{
 }, z.core.$strict>>;
 /** A caller reuses this task unchanged while polling Pending. */
 export type AgentDelegationTask = z.infer<typeof agentDelegationTaskSchema>;
-/** Exact host facts encoded over internal transports, without transcript content. */
-export declare const commandSettlementSchema: Schema.Codec<CommandSettlement>;
 /** Exact settled Session facts, including Pi usage and tool-call records. */
 export type AgentDelegationOutcome = Readonly<{
     kind: "settled";
@@ -181,7 +199,7 @@ export type AgentDelegationOutcome = Readonly<{
 export type FleetDelegationOptions = Readonly<{
     storage: WatchdogSqliteOwner;
     /** Admit the frozen addressed mail through the destination owner. */
-    deliver: (mail: BirdDogMail) => Promise<Accepted>;
+    deliver: (mail: BirdDogMail) => Promise<DelegationReceipt>;
     /** Read exact work facts at the target owner, independent of transcript selection. */
     readSettlement: (agentId: string, sessionId: string, commandId: string) => Promise<CommandSettlement | undefined>;
     /** Acquire a Session client only when creating the delegated conversation. */
@@ -237,8 +255,9 @@ export declare function delegationSendMeta(sender: Readonly<{
     name: string;
 }>, invocationMeta?: Json): DelegationSendMeta;
 /**
- * The host metadata for one authenticated reply line: the replying Agent is
- * its author, and the verified reply rides beside the caller's own path.
+ * The host metadata for one authenticated reply line. An ordinary reply is
+ * authored by its replying Agent; a delivery failure is a Hub/system fact,
+ * while the verified reply retains the failed recipient's identity.
  */
 export declare function delegationReplyMeta(delegation: AuthenticatedDelegationReply, replierName: string): DelegationReplyMeta;
 /**
@@ -258,22 +277,30 @@ export type OutstandingDelegation = Readonly<{
  */
 export declare function createFleetCorrespondence(options: Omit<FleetDelegationOptions, "readSettlement">): {
     /** Submit frozen mail or reuse its recorded Session admission receipt. */
-    start: (grant: AgentGrant, raw: AgentDelegationTask) => Promise<Accepted>;
+    start: (grant: AgentGrant, raw: AgentDelegationTask) => Promise<DelegationReceipt>;
     /** Match a reply to frozen mail and restore the caller's delegation path. */
     authenticateReply: (mail: BirdDogMail) => AuthenticatedDelegationReply | undefined;
+    recordLocalUndeliverable: (original: BirdDogMail, reply: BirdDogMail) => boolean;
+    recordUndeliverableReply: (mailKey: string) => boolean;
     /** Read an existing acceptance receipt without reserving or delivering mail. */
     receipt: (requestId: string) => Accepted | undefined;
+    /** Consume a recipient's stable `<mailKey>:accepted` notice. */
+    recordAcceptedNotice: (mail: BirdDogMail) => Accepted | undefined;
 };
 /** Local hosts may observe exact work directly; remote correspondence never pulls it. */
 export declare function createFleetDelegation(options: FleetDelegationOptions): {
     /** Submit or poll the exact turn, yielding Agar Pending until settled. */
     delegate: (grant: AgentGrant, task: AgentDelegationTask) => Promise<Pending | AgentDelegationOutcome>;
     /** Submit frozen mail or reuse its recorded Session admission receipt. */
-    start: (grant: AgentGrant, raw: AgentDelegationTask) => Promise<Accepted>;
+    start: (grant: AgentGrant, raw: AgentDelegationTask) => Promise<DelegationReceipt>;
     /** Match a reply to frozen mail and restore the caller's delegation path. */
     authenticateReply: (mail: BirdDogMail) => AuthenticatedDelegationReply | undefined;
+    recordLocalUndeliverable: (original: BirdDogMail, reply: BirdDogMail) => boolean;
+    recordUndeliverableReply: (mailKey: string) => boolean;
     /** Read an existing acceptance receipt without reserving or delivering mail. */
     receipt: (requestId: string) => Accepted | undefined;
+    /** Consume a recipient's stable `<mailKey>:accepted` notice. */
+    recordAcceptedNotice: (mail: BirdDogMail) => Accepted | undefined;
     /** The delegated work this owner still waits on, if any. */
     outstanding: () => Promise<OutstandingDelegation | undefined>;
 };

package/dist/fleet.js

@@ -1,13 +1,31 @@
-import { SessionTerminalSchema } from "./client-wire.js";
-import { usage, createFleetDirectoryStore, createFleetDelegationStore, } from "./internal/woodstock/index.js";
+export { commandSettlementSchema } from "./client-wire.js";
+import { createFleetDirectoryStore, createFleetDelegationStore, } from "./internal/woodstock/index.js";
 import { pending } from "@fungi.computer/agar";
 import { BirdDogMailSchema } from "@fungi.computer/bird-dog/effect";
 import * as Schema from "effect/Schema";
-import { parseAccepted } from "./client.js";
+import { parseAccepted, parseDelegationReceipt, } from "./client.js";
 import { checkHostMeta } from "./internal/host-meta.js";
 import { defineIdFamily } from "@fungi.computer/cairn/id";
+import { deterministicReplayKey } from "@fungi.computer/cairn";
 import { z } from "zod";
 import { authorMeta, FungiMessageMetaSchema, } from "@fungi.computer/agar/agents";
+/**
+ * One idempotency identity for a caller-owned delegation request.
+ * The target Session is deliberately excluded: a sessionless send learns it
+ * only after acceptance, when recall must still resolve the original receipt.
+ */
+export async function agentDelegationRequestKey(input) {
+    const ownerIdentity = input.owner.kind === "hosted"
+        ? [input.owner.scopeId, input.owner.agentId]
+        : [input.owner.agentId];
+    return deterministicReplayKey("agent-delegation-request", [
+        input.owner.kind,
+        ...ownerIdentity,
+        input.sourceSessionId,
+        input.targetAgentId,
+        input.requestId,
+    ]);
+}
 const identity = z.string().min(1).max(256);
 /** Operations explicitly admitted by the host. */
 export const agentActionSchema = z.enum([
@@ -261,14 +279,6 @@ export const agentDelegationTaskSchema = z.lazy(() => z.strictObject({
         .min(1)
         .max(256 * 1024),
 }));
-/** Exact host facts encoded over internal transports, without transcript content. */
-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)),
-});
 /**
  * Provenance for one delegated send from the invoking Agent's Session. The
  * model program's digest is frozen with the replay input, so a retried tool
@@ -308,16 +318,21 @@ export function delegationSendMeta(sender, invocationMeta) {
         };
 }
 /**
- * The host metadata for one authenticated reply line: the replying Agent is
- * its author, and the verified reply rides beside the caller's own path.
+ * The host metadata for one authenticated reply line. An ordinary reply is
+ * authored by its replying Agent; a delivery failure is a Hub/system fact,
+ * while the verified reply retains the failed recipient's identity.
  */
 export function delegationReplyMeta(delegation, replierName) {
-    return {
-        ...authorMeta({
+    const author = delegation.reply.outcome === "undeliverable" &&
+        delegation.reply.reason === "recipient_offline"
+        ? authorMeta({ id: "hub/system", name: "Hub/system" })
+        : authorMeta({
             id: delegation.reply.agentId,
             name: replierName,
             kind: "agent",
-        }),
+        });
+    return {
+        ...author,
         delegation: {
             ancestors: [...delegation.ancestors],
             maxDepth: delegation.maxDepth,
@@ -331,9 +346,23 @@ const delegationMetadata = z.object({
 const delegationRowSchema = z.lazy(() => z.strictObject({
     input: z.string(),
     mail: z.string(),
+    state: z.enum(["pending", "held", "accepted", "undeliverable"]),
     receipt: z.string().nullable(),
 }));
+const heldRecipientOffline = {
+    status: "held",
+    reason: "recipient_offline",
+    message: "waiting: recipient offline",
+};
 const decodeMail = Schema.decodeUnknownSync(Schema.fromJsonString(BirdDogMailSchema));
+function bindRecipientSession(mail, sessionId) {
+    if (mail.from.kind !== "agent")
+        throw new DirectoryError(503, "partial_init");
+    return {
+        ...mail,
+        to: { ...mail.to, sessionId },
+    };
+}
 /**
  * BirdDog submission and reply authentication. The durable row freezes
  * correspondence before transport; an ambiguous delivery reuses that exact mail.
@@ -384,21 +413,20 @@ export function createFleetCorrespondence(options) {
         });
         let row = read(task.requestId);
         if (row === undefined) {
-            let sessionId = task.sessionId;
-            if (sessionId === undefined) {
-                const opened = await options.open(task.agentId);
-                try {
-                    sessionId = await opened.agent.createSession(task.requestId);
-                }
-                finally {
-                    await opened.release();
-                }
-            }
             const from = { kind: "agent", ...parent };
             let mail = {
                 key: task.requestId,
                 from,
-                to: { kind: "agent", agentId: task.agentId, sessionId },
+                to: task.sessionId === undefined
+                    ? {
+                        kind: "agent",
+                        agentId: task.agentId,
+                    }
+                    : {
+                        kind: "agent",
+                        agentId: task.agentId,
+                        sessionId: task.sessionId,
+                    },
                 replyTo: [from],
                 content: task.text,
                 createdAt: Date.now(),
@@ -411,11 +439,26 @@ export function createFleetCorrespondence(options) {
             throw new DirectoryError(503, "partial_init");
         if (row.input !== input)
             throw new DirectoryError(409, "request_conflict");
-        if (row.receipt !== null)
+        if (row.state === "held" || row.state === "undeliverable")
+            return heldRecipientOffline;
+        if (row.state === "accepted") {
+            if (row.receipt === null)
+                throw new DirectoryError(503, "partial_init");
             return parseAccepted(row.receipt);
+        }
         assertAgentGrant(grant, "delegate", task.agentId);
-        const receipt = parseAccepted(JSON.stringify(await options.deliver(decodeMail(row.mail))));
-        store.recordReceipt(task.requestId, JSON.stringify(receipt));
+        const receipt = parseDelegationReceipt(JSON.stringify(await options.deliver(decodeMail(row.mail))));
+        if (receipt.status === "held")
+            store.recordHeld(task.requestId);
+        else {
+            const sent = decodeMail(row.mail);
+            const sessionId = receipt.sessionId ?? sent.to.sessionId;
+            if (sessionId === undefined)
+                throw new DirectoryError(503, "partial_init");
+            const accepted = { ...receipt, sessionId };
+            store.recordReceipt(task.requestId, JSON.stringify(accepted), row.mail, JSON.stringify(bindRecipientSession(sent, sessionId)));
+            return accepted;
+        }
         return receipt;
     }
     /**
@@ -431,48 +474,165 @@ export function createFleetCorrespondence(options) {
         const suffix = ":reply:0";
         if (mail.replyTo.length !== 0 ||
             mail.reply === undefined ||
+            mail.reply.outcome === "accepted" ||
             !mail.key.endsWith(suffix))
             return undefined;
-        const row = read(mail.key.slice(0, -suffix.length));
-        if (row === undefined)
+        const mailKey = mail.key.slice(0, -suffix.length);
+        const row = read(mailKey);
+        if (row === undefined || row.state === "undeliverable")
             return undefined;
         const sent = decodeMail(row.mail);
-        if (mail.from.agentId !== sent.to.agentId ||
-            mail.from.sessionId !== sent.to.sessionId ||
-            mail.to.agentId !== sent.from.agentId ||
-            mail.to.sessionId !== sent.from.sessionId)
+        if (sent.key !== mailKey)
             return undefined;
-        if (row.receipt !== null &&
-            parseAccepted(row.receipt).commandId !== mail.reply.commandId)
+        const systemUndeliverable = mail.reply.outcome === "undeliverable" &&
+            mail.reply.reason === "recipient_offline" &&
+            mail.from.kind === "system";
+        if (systemUndeliverable) {
+            if (row.state !== "held" ||
+                sent.from.kind !== "agent" ||
+                mail.key !== `${sent.key}:reply:0` ||
+                mail.to.agentId !== sent.from.agentId ||
+                mail.to.sessionId !== sent.from.sessionId)
+                return undefined;
+        }
+        else {
+            if (sent.from.kind !== "agent" ||
+                mail.from.kind !== "agent" ||
+                mail.from.agentId !== sent.to.agentId ||
+                mail.from.sessionId !== sent.to.sessionId ||
+                mail.to.agentId !== sent.from.agentId ||
+                mail.to.sessionId !== sent.from.sessionId)
+                return undefined;
+        }
+        if (mail.reply.outcome === "undeliverable" &&
+            mail.reply.reason === "recipient_offline" &&
+            !systemUndeliverable)
             return undefined;
+        if (mail.reply.outcome !== "undeliverable" &&
+            row.state === "accepted" &&
+            row.receipt !== null) {
+            const sentResult = parseAccepted(row.receipt);
+            if (sentResult.commandId !== mail.reply.commandId)
+                return undefined;
+        }
         const path = delegationMetadata.parse(sent.meta).delegation;
         if (path === undefined)
             return undefined;
-        const reply = {
-            agentId: mail.from.agentId,
-            sessionId: mail.from.sessionId,
-            ...mail.reply,
-        };
+        let reply;
+        if (mail.reply.outcome === "undeliverable") {
+            const agentId = systemUndeliverable
+                ? sent.to.agentId
+                : mail.from.kind === "agent"
+                    ? mail.from.agentId
+                    : undefined;
+            if (agentId === undefined)
+                return undefined;
+            const undeliverable = { agentId, ...mail.reply };
+            const sessionId = systemUndeliverable
+                ? sent.to.sessionId
+                : mail.from.kind === "agent"
+                    ? mail.from.sessionId
+                    : undefined;
+            reply =
+                sessionId === undefined
+                    ? undeliverable
+                    : { ...undeliverable, sessionId };
+        }
+        else {
+            if (mail.from.kind !== "agent")
+                return undefined;
+            const sessionId = mail.from.sessionId;
+            reply = { agentId: mail.from.agentId, sessionId, ...mail.reply };
+        }
         return {
             ancestors: path.ancestors.slice(0, -1),
             maxDepth: path.maxDepth,
             reply,
         };
     }
+    /** Bind an exhausted local Carrier row to its frozen sender correspondence. */
+    function recordLocalUndeliverable(original, reply) {
+        const row = read(original.key);
+        if (row === undefined ||
+            (row.state !== "pending" && row.state !== "held") ||
+            original.from.kind !== "agent" ||
+            original.reply !== undefined ||
+            JSON.stringify(decodeMail(row.mail)) !== JSON.stringify(original) ||
+            reply.key !== `${original.key}:reply:0` ||
+            reply.from.kind !== "system" ||
+            reply.reply?.outcome !== "undeliverable" ||
+            reply.reply.reason !== "recipient_offline" ||
+            reply.to.agentId !== original.from.agentId ||
+            reply.to.sessionId !== original.from.sessionId ||
+            reply.replyTo.length !== 0)
+            return false;
+        store.recordHeld(original.key);
+        return read(original.key)?.state === "held";
+    }
+    /** Make a successfully admitted system disposition replay-ineligible. */
+    function recordUndeliverableReply(mailKey) {
+        return store.recordUndeliverable(mailKey);
+    }
     /** Read only the existing acceptance receipt; do not reserve or deliver mail. */
     function receipt(requestId) {
-        const encoded = read(requestId)?.receipt;
-        return encoded === undefined || encoded === null
+        const row = read(requestId);
+        return row?.state !== "accepted" || row.receipt === null
             ? undefined
-            : parseAccepted(encoded);
+            : parseAccepted(row.receipt);
+    }
+    /** Atomically bind the recipient Session carried by a late acceptance notice. */
+    function recordAcceptedNotice(mail) {
+        const suffix = ":accepted";
+        if (mail.from.kind !== "agent")
+            return undefined;
+        const sender = mail.from;
+        if (mail.replyTo.length !== 0 ||
+            mail.reply?.outcome !== "accepted" ||
+            !mail.key.endsWith(suffix))
+            return undefined;
+        const requestId = mail.key.slice(0, -suffix.length);
+        const row = read(requestId);
+        if (row === undefined)
+            return undefined;
+        const sent = decodeMail(row.mail);
+        if (sent.from.kind !== "agent")
+            return undefined;
+        const sentSender = sent.from;
+        const path = delegationMetadata.safeParse(sent.meta);
+        if (!path.success ||
+            path.data.delegation === undefined ||
+            mail.key !== `${sent.key}:accepted` ||
+            sender.agentId !== sent.to.agentId ||
+            (sent.to.sessionId !== undefined &&
+                sent.to.sessionId !== sender.sessionId) ||
+            mail.to.agentId !== sentSender.agentId ||
+            mail.to.sessionId !== sentSender.sessionId)
+            return undefined;
+        if (row.state === "accepted" && row.receipt !== null) {
+            const current = parseAccepted(row.receipt);
+            if (current.commandId !== mail.reply.commandId ||
+                current.sessionId !== sender.sessionId)
+                return undefined;
+        }
+        const accepted = {
+            status: "accepted",
+            commandId: mail.reply.commandId,
+            sessionId: sender.sessionId,
+        };
+        store.recordReceipt(requestId, JSON.stringify(accepted), row.mail, JSON.stringify(bindRecipientSession(sent, sender.sessionId)));
+        return accepted;
     }
     return {
         /** Submit frozen mail or reuse its recorded Session admission receipt. */
         start,
         /** Match a reply to frozen mail and restore the caller's delegation path. */
         authenticateReply,
+        recordLocalUndeliverable,
+        recordUndeliverableReply,
         /** Read an existing acceptance receipt without reserving or delivering mail. */
         receipt,
+        /** Consume a recipient's stable `<mailKey>:accepted` notice. */
+        recordAcceptedNotice,
     };
 }
 /** Local hosts may observe exact work directly; remote correspondence never pulls it. */
@@ -485,13 +645,18 @@ export function createFleetDelegation(options) {
         if (raw === undefined)
             throw new DirectoryError(503, "partial_init");
         const mail = decodeMail(delegationRowSchema.parse(raw).mail);
-        const settlement = await options.readSettlement(mail.to.agentId, mail.to.sessionId, accepted.commandId);
+        if (accepted.status === "held")
+            return pending(1000);
+        const sessionId = mail.to.sessionId ?? accepted.sessionId;
+        if (sessionId === undefined)
+            throw new DirectoryError(503, "partial_init");
+        const settlement = await options.readSettlement(mail.to.agentId, sessionId, accepted.commandId);
         return settlement === undefined
             ? pending(1000)
             : {
                 kind: "settled",
                 agentId: mail.to.agentId,
-                sessionId: mail.to.sessionId,
+                sessionId,
                 ...settlement,
             };
     }
@@ -504,8 +669,12 @@ export function createFleetDelegation(options) {
             const row = delegationRowSchema.parse(raw);
             if (row.receipt === null)
                 continue;
+            if (row.state !== "accepted")
+                continue;
             const { to } = decodeMail(row.mail);
             const { commandId } = parseAccepted(row.receipt);
+            if (to.sessionId === undefined)
+                throw new DirectoryError(503, "partial_init");
             const target = {
                 agentId: to.agentId,
                 sessionId: to.sessionId,

package/dist/http-routes.d.ts

@@ -297,6 +297,7 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
             output: {
                 readonly status: "accepted";
                 readonly commandId: string;
+                readonly sessionId?: string | undefined;
             } | {
                 readonly status: "unknown";
             };
@@ -453,6 +454,7 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
             output: {
                 readonly status: "accepted";
                 readonly commandId: string;
+                readonly sessionId?: string | undefined;
             } | {
                 readonly status: "unknown";
             } | {
@@ -465,6 +467,75 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
             status: 200;
         };
     };
+} & {
+    "/sessions/:sessionId/settlement": {
+        $get: {
+            input: {
+                query: {
+                    readonly commandId: string | string[];
+                    readonly timeoutMs: string | string[];
+                };
+            } & {
+                param: {
+                    sessionId: string;
+                };
+            };
+            output: {
+                readonly cause: "closed" | "conflict" | "incompatible" | "invalid" | "rejected" | "unavailable" | "state_reset_required" | "storage_pressure";
+                readonly _tag: "ShiitakeError";
+                readonly boundary: "contract" | "extensions" | "instructions" | "model" | "runtime" | "store" | "tools";
+                readonly message: string;
+                readonly requestId?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 400;
+        } | {
+            input: {
+                query: {
+                    readonly commandId: string | string[];
+                    readonly timeoutMs: string | string[];
+                };
+            } & {
+                param: {
+                    sessionId: string;
+                };
+            };
+            output: {
+                readonly acceptedSender: string | null;
+                readonly terminal: {
+                    readonly commandId: string;
+                    readonly outcome: "completed" | "cancelled" | "failed" | "interrupted";
+                    readonly sequence: number;
+                    readonly diagnostic: string | null;
+                    readonly meta?: any;
+                };
+                readonly content: string;
+                readonly usage: readonly {
+                    model: string;
+                    provider: import("@fungi.computer/mule/effect").ProviderId;
+                    usage: {
+                        input: number;
+                        output: number;
+                        cacheRead: number;
+                        cacheWrite: number;
+                        cacheWrite1h?: number | undefined;
+                        reasoning?: number | undefined;
+                        totalTokens: number;
+                        cost: {
+                            input: number;
+                            output: number;
+                            cacheRead: number;
+                            cacheWrite: number;
+                            total: number;
+                        };
+                    };
+                }[];
+                readonly toolCalls: number;
+            } | null;
+            outputFormat: "json";
+            status: 200;
+        };
+    };
 } & {
     "/sessions/:sessionId": {
         $get: {
@@ -626,6 +697,7 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
                             data?: any;
                         } | undefined;
                         errorMessage?: string | undefined;
+                        providerError?: string | undefined;
                         rawStopReason?: string | undefined;
                         endTurn?: boolean | undefined;
                         timestamp: number;
@@ -633,6 +705,17 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
                     } | {
                         toolCallId: string;
                         role: "toolResult";
+                        timestamp: number;
+                        content: ({
+                            type: "text";
+                            text: string;
+                            textSignature?: string | undefined;
+                        } | {
+                            type: "image";
+                            data: string;
+                            mimeType: string;
+                        })[];
+                        toolName: string;
                         usage?: {
                             input: number;
                             output: number;
@@ -649,18 +732,6 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
                                 total: number;
                             };
                         } | undefined;
-                        content: ({
-                            type: "text";
-                            text: string;
-                            textSignature?: string | undefined;
-                        } | {
-                            type: "image";
-                            data: string;
-                            mimeType: string;
-                        })[];
-                        timestamp: number;
-                        durationMs?: number | undefined;
-                        toolName: string;
                         nestedCalls?: {
                             calls: {
                                 id: string;
@@ -676,6 +747,7 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
                             complete: boolean;
                         } | undefined;
                         isError: boolean;
+                        durationMs?: number | undefined;
                     };
                 }[];
                 readonly terminals: readonly {

package/dist/http-routes.js

@@ -6,7 +6,7 @@ import { validator } from "hono/validator";
 import * as Schema from "effect/Schema";
 import { ShiitakeError, toShiitakeErrorWire } from "./errors.js";
 import { JsonValueSchema } from "./internal/json-value.js";
-import { decodeClientIdentity, decodeClientEventsQuery, decodeClientReadQuery, decodeClientSessionCommandRequest, decodeClientSessionCreationRequest, decodeClientPageCursor, decodeClientSessionId, } from "./internal/client-boundary.js";
+import { decodeClientIdentity, decodeClientEventsQuery, decodeClientReadQuery, decodeClientSettlementQuery, decodeClientSessionCommandRequest, decodeClientSessionCreationRequest, decodeClientPageCursor, decodeClientSessionId, } from "./internal/client-boundary.js";
 const decodeJsonValue = Schema.decodeUnknownResult(Schema.fromJsonString(JsonValueSchema));
 /** One encoded extension output; its contract, not Hono, types the value. */
 function jsonResponse(value) {
@@ -218,6 +218,20 @@ export function createShiitakeHttpRoutes(resolveSession, listSessions, createSes
             return context.body(null, 204);
         }
         return context.json(await session.command(command), 200);
+    })
+        .get("/sessions/:sessionId/settlement", validator("query", (value, context) => {
+        const decoded = decodeClientSettlementQuery(value);
+        if (decoded._tag === "Failure")
+            return context.json(toShiitakeErrorWire(invalidRequest("Settlement request is invalid")), 400);
+        return decoded.success;
+    }), async (context) => {
+        const session = await resolveSession(decodeClientSessionId(context.req.param("sessionId")), context.get("shiitakeMeta"));
+        const { commandId, timeoutMs } = context.req.valid("query");
+        const settled = await session.readSettlement(commandId, {
+            timeoutMs,
+            signal: context.req.raw.signal,
+        });
+        return context.json(settled ?? null, 200);
     })
         .get("/sessions/:sessionId", validator("query", (value, context) => {
         const decoded = decodeClientReadQuery(value);