@fungi.computer/shiitake 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import type { VerifiedAgentReply } from "./internal/woodstock/index.js";
 import type { BirdDogEffect } from "@fungi.computer/bird-dog/effect";
 import type { Accepted } from "./client.js";
 import type { ShiitakeOptions, ShiitakeOwnerAgent } from "./internal/contracts.js";
-export type { AbortCommand, AgentExtensionControls, BranchCommand, CompactCommand, CancelCommand, CancelResult, Accepted, ForkCommand, ForkedSession, OperatorCommand, TitleCommand, PromptCommand, PromptDelivery, SendOptions, ReadOptions, SessionCommand, SessionCommandHandler, SessionExtensionControls, SessionExtensionSlots, SessionFrame, SessionMessage, SessionProgress, SessionToolOutput, SessionContext, SessionSnapshot, SessionInboxState, SessionSummary, SessionSummaryPage, SessionSummaryRow, SessionActivity, AgentRunningWork, SessionTerminal, SessionCompactionMarker, SessionCompactionNotice, SessionCompactionTrigger, ShiitakeEventSourceConstructor, SessionWatch, ShiitakeAgent, ShiitakeSession, SubscribeOptions, TooLate, UnknownRequest, WatchOptions, } from "./client.js";
+export type { AbortCommand, AgentExtensionControls, BranchCommand, CompactCommand, CancelCommand, CancelResult, Accepted, DelegationReceipt, Held, ForkCommand, ForkedSession, OperatorCommand, TitleCommand, PromptCommand, PromptDelivery, SendOptions, ReadOptions, SessionCommand, SessionCommandHandler, SessionExtensionControls, SessionExtensionSlots, SessionFrame, SessionMessage, SessionProgress, SessionToolOutput, SessionContext, SessionSnapshot, SessionInboxState, SessionSummary, SessionSummaryPage, SessionSummaryRow, SessionActivity, AgentRunningWork, SessionTerminal, SessionCompactionMarker, SessionCompactionNotice, SessionCompactionTrigger, ShiitakeEventSourceConstructor, SessionWatch, ShiitakeAgent, ShiitakeSession, SubscribeOptions, TooLate, UnknownRequest, WatchOptions, } from "./client.js";
 export type { ColdSessionPage, ColdSessionPageRequest, ColdSessionRow, } from "./cold-sessions.js";
 export { parseForkedSession, parseSessionFrame, parseSessionSnapshot, } from "./client.js";
 export type { InstructionSnapshot, InstructionSource, ModelAcquisition, ModelDescription, ModelSource, RuntimeHost, RuntimePendingWork, SqliteCursor, SqliteOwner, SqliteValue, SqliteRow, StoragePressureCheck, CompactionBudget, CompactionOptions, GrantsDelivery, GrantsDeliveryResult, ShiitakeOptions, ShiitakeOwnerAgent, ToolAccess, HostMetaOptions, StandardHostMetaResult, StandardHostMetaSchema, ToolSource, } from "./internal/contracts.js";
@@ -22,7 +22,7 @@ export type ShiitakeHost = Readonly<{
     readSettlement: (sessionId: string, commandId: string) => Promise<CommandSettlement | undefined>;
     agent: ShiitakeOwnerAgent;
     /** Durably admit one addressed mail item through the host owner. */
-    acceptMail: (mail: BirdDogMail, meta?: HostJson, reply?: VerifiedAgentReply) => Promise<Accepted>;
+    acceptMail: (mail: BirdDogMail, meta?: HostJson, reply?: VerifiedAgentReply, stageAcceptedNotice?: (mail: BirdDogMail) => void) => Promise<Accepted>;
 }>;
 /** Construct the host-only Promise facade over the canonical Effect program. */
 export declare function makeHost(options: ShiitakeOptions, mailRoom: BirdDogEffect): Promise<ShiitakeHost>;

package/dist/internal/admission-door.d.ts

@@ -32,6 +32,8 @@ export type AdmitRequest = Readonly<{
      * host passes it, after checking the reply against the mail it sent.
      */
     reply?: VerifiedAgentReply;
+    /** Synchronous owner-local side effect committed with a mail admission. */
+    onAccepted?: (sessionId: string, commandId: string) => void;
 }>;
 /** Outcome of one door admission. */
 export type AdmitResult = Readonly<{

package/dist/internal/admission-door.js

@@ -16,9 +16,14 @@ function decodeReply(request) {
         return undefined;
     const reply = requireDecoded(decodeVerifiedReply(request.reply), "Verified Agent reply is invalid");
     const mail = request.mail;
+    const agentAuthored = mail?.from.kind === "agent" &&
+        mail.from.agentId === reply.agentId &&
+        mail.from.sessionId === reply.sessionId;
+    const systemUndeliverable = mail?.from.kind === "system" &&
+        reply.outcome === "undeliverable" &&
+        reply.reason === "recipient_offline";
     if (mail?.replyTo.length !== 0 ||
-        mail.from.agentId !== reply.agentId ||
-        mail.from.sessionId !== reply.sessionId ||
+        (!agentAuthored && !systemUndeliverable) ||
         request.command.type !== "prompt" ||
         request.command.delivery !== "steer")
         throw new ShiitakeError("contract", "invalid", "Verified Agent reply does not match its mail");
@@ -35,6 +40,7 @@ export function openAdmissionDoor(input) {
         when: request.when,
         mail: request.mail,
         reply: decodeReply(request),
+        onAccepted: request.onAccepted,
         meta: request.meta === undefined
             ? undefined
             : checkHostMeta(input.hostMeta, request.meta),
@@ -69,6 +75,7 @@ export function openAdmissionDoor(input) {
                 input.enqueue(work, request.mail);
             }
             : undefined, targetWorkId, request.reply);
+        request.onAccepted?.(sessionId, accepted.accepted.commandId);
         touched.set(sessionId, (touched.get(sessionId) ?? false) || accepted.delivery === "new");
         return Object.freeze({
             status: "accepted",

package/dist/internal/client-boundary.d.ts

@@ -8,6 +8,16 @@ export declare const PromptImageSchema: Schema.Struct<{
 }>;
 /** Delivery policy for input accepted while a Session run is active. */
 export type PromptDelivery = "steer" | "followUp";
+/** One bounded exact-command read, shared by the in-process and HTTP doors. */
+export declare const decodeClientSettlementRequest: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Result.Result<{
+    readonly commandId: string;
+    readonly timeoutMs: number;
+}, Schema.SchemaError>;
+/** Query encoding of the same bounded exact-command read. */
+export declare const decodeClientSettlementQuery: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Result.Result<{
+    readonly commandId: string;
+    readonly timeoutMs: number;
+}, Schema.SchemaError>;
 declare const SessionCreationRequestSchema: Schema.Struct<{
     readonly requestId: Schema.String;
 }>;

package/dist/internal/client-boundary.js

@@ -27,6 +27,16 @@ export const PromptImageSchema = Schema.Struct({
 const PromptImagesSchema = Schema.Array(PromptImageSchema).check(Schema.isMinLength(1), Schema.isMaxLength(8));
 const PromptDeliverySchema = Schema.Literals(["steer", "followUp"]);
 const SessionIdSchema = boundedId;
+/** One bounded exact-command read, shared by the in-process and HTTP doors. */
+export const decodeClientSettlementRequest = Schema.decodeUnknownResult(Schema.Struct({
+    commandId: boundedId,
+    timeoutMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(30_000)),
+}), { onExcessProperty: "error" });
+/** Query encoding of the same bounded exact-command read. */
+export const decodeClientSettlementQuery = Schema.decodeUnknownResult(Schema.Struct({
+    commandId: boundedId,
+    timeoutMs: Schema.NumberFromString.check(Schema.isInt(), Schema.isBetween({ minimum: 0, maximum: 30_000 })),
+}), { onExcessProperty: "error" });
 const decodeSessionPageCursorValue = Schema.decodeUnknownResult(boundedText(512));
 const SessionCreationRequestSchema = Schema.Struct({ requestId: boundedId });
 const PromptCommandSchema = Schema.Struct({

package/dist/internal/compaction/compaction.js

@@ -8,7 +8,7 @@ import { uuidv7 } from "@earendil-works/pi-ai/utils/uuid";
 import * as Effect from "effect/Effect";
 import { ShiitakeError } from "../../errors.js";
 import { computeFileLists, createFileOps, extractFileOpsFromMessage, formatFileOperations, serializeConversation, SUMMARIZATION_PROMPT, SUMMARIZATION_SYSTEM_PROMPT, TURN_PREFIX_SUMMARIZATION_PROMPT, UPDATE_SUMMARIZATION_PROMPT, compactionSummaryText, summaryFailure, } from "./utils.js";
-/** A summary is a model call: its bounded provider message is shown. */
+/** A summary uses the stream failure diagnostic, never failed-turn provider prose. */
 function failure(message) {
     return new ShiitakeError("model", "rejected", message);
 }

package/dist/internal/contracts.d.ts

@@ -47,6 +47,8 @@ export type ModelAcquisition = Readonly<{
      * Unknown messages must return undefined.
      */
     failureReason?: (message: AssistantMessage) => string | undefined;
+    /** Provider prose for this door's exact failed turn; never a diagnostic. */
+    providerError?: (message: AssistantMessage) => string | undefined;
     /** Release the acquired model resources. */
     release: () => Promise<void>;
 }>;

package/dist/internal/coordinator.d.ts

@@ -5,6 +5,7 @@ import { ShiitakeError } from "../errors.js";
 import type { Json } from "../extensions.js";
 import type { ShiitakeEffectOwner, ShiitakeEffectOptions } from "./effect-contracts.js";
 import type { RuntimeCoordinator } from "./runtime-coordinator.js";
+import { type GrantsDelivery } from "./woodstock/index.js";
 /** Construct the Effect-native coordinator over the private owner modules. */
 export declare function openCoordinator(options: ShiitakeEffectOptions, runtime: RuntimeCoordinator): ShiitakeEffectOwner;
 /**
@@ -12,7 +13,8 @@ export declare function openCoordinator(options: ShiitakeEffectOptions, runtime:
  * is the host's authentication of a delegated Agent's reply; only then does
  * the model see the line inside the verified-reply tag.
  */
-export declare function acceptAddressedMail(runtime: RuntimeCoordinator, mail: BirdDogMail, meta?: Json, reply?: VerifiedAgentReply): Effect.Effect<Readonly<{
+export declare function acceptAddressedMail(runtime: RuntimeCoordinator, mail: BirdDogMail, meta?: Json, reply?: VerifiedAgentReply, stageMail?: (mail: BirdDogMail) => void, sessionGrantDelivery?: (sessionId: string) => GrantsDelivery): Effect.Effect<Readonly<{
     status: "accepted";
     commandId: string;
+    sessionId?: string;
 }>, ShiitakeError, never>;

package/dist/internal/coordinator.js

@@ -1,15 +1,16 @@
 import { nanoid } from "@fungi.computer/cairn";
 import { parseModelPreference } from "./model-preference.js";
+import { acceptedNotice } from "@fungi.computer/bird-dog/effect";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
 import { ShiitakeError } from "../errors.js";
-import { decodeClientReadOptions, decodeClientSessionCommand, decodeClientSessionId, decodeClientSubscribeOptions, } from "./client-boundary.js";
+import { decodeClientReadOptions, decodeClientSettlementRequest, requireDecoded, decodeClientSessionCommand, decodeClientSessionId, decodeClientSubscribeOptions, } from "./client-boundary.js";
 import { mergeObservationSignals, openObservationKernel, publishOwnerObservation, } from "./observation-kernel.js";
 import { checkHostMeta } from "./host-meta.js";
 import { readSessionActivity } from "./session-status.js";
 import { readSessionContext } from "./session-context.js";
-import { abortSession, cancelSession, branchSession, recordOperatorLine, forkSession, readSession, readSessionModelPreference, readSessionReplayPage, readSessionInbox, readLatestPendingPrompt, createSession, deleteSession, deliverSessionGrants, readSessionGrants, setSessionModelPreference, setSessionTitle, readAdmissionIdentity, assertAdmissionIdentity, } from "./woodstock/index.js";
+import { abortSession, cancelSession, branchSession, recordOperatorLine, forkSession, readSession, readCommandSettlement, readSessionModelPreference, readSessionReplayPage, readSessionInbox, readLatestPendingPrompt, createSession, deleteSession, deliverSessionGrants, readSessionGrants, setSessionModelPreference, setSessionTitle, readAdmissionIdentity, assertAdmissionIdentity, } from "./woodstock/index.js";
 /** Generic Agent-scope extension controls over the runtime's one call door. */
 function agentExtensions(runtime) {
     return Object.freeze({
@@ -33,7 +34,7 @@ function withContext(snapshot, context) {
 }
 /** Read the baseline and its context use for one Session. */
 function readSessionWithContext(options, runtime, sessionId, input) {
-    return currentSessionActivity(options, runtime, sessionId).pipe(Effect.flatMap((activity) => readSession(options.store, sessionId, activity, input, () => runtime.extensions.project(sessionId))), Effect.flatMap((snapshot) => readSessionContext(options, sessionId).pipe(Effect.map((context) => withContext(snapshot, context)))));
+    return currentSessionActivity(options, runtime, sessionId).pipe(Effect.flatMap((activity) => readSession(options.store, sessionId, activity, input, () => runtime.extensions.project(sessionId))), Effect.flatMap((snapshot) => readSessionContext(options, sessionId, snapshot.cursor, input?.before === undefined).pipe(Effect.map((context) => withContext(snapshot, context)))));
 }
 function sessionOwnerOperation(runtime, sessionId, operation) {
     return runtime.assertOpen.pipe(Effect.andThen(Effect.try({
@@ -106,6 +107,12 @@ function subscriptionFrames(options, runtime, registration, sessionId, after, de
         if (signal === "reset")
             return resetFrame(options, runtime, sessionId, includeSandboxFailures).pipe(Effect.map(continueFromReset));
         return runtime.assertOpen.pipe(Effect.andThen(currentSessionActivity(options, runtime, sessionId)), Effect.flatMap((activity) => {
+            registration.setQueued(activity.facts.queue.state === "queued");
+            if (signal === "activity" && state.delivery === "live")
+                return Effect.succeed([
+                    [{ kind: "activity", activity: activity.facts }],
+                    Option.some({ ...state, awaitSignal: true }),
+                ]);
             if (signal === "progress" && state.delivery === "live") {
                 return Effect.succeed([
                     [
@@ -132,6 +139,7 @@ function subscriptionFrames(options, runtime, registration, sessionId, after, de
                     return resetFrame(options, runtime, sessionId, includeSandboxFailures).pipe(Effect.map(continueFromReset));
                 const latestCursor = page.frames
                     .flatMap((frame) => frame.kind === "progress" ||
+                    frame.kind === "activity" ||
                     frame.kind === "tool_output"
                     ? []
                     : [frame.cursor])
@@ -141,13 +149,18 @@ function subscriptionFrames(options, runtime, registration, sessionId, after, de
                     delivery: page.hasMore ? state.delivery : "live",
                     awaitSignal: !page.hasMore,
                 };
-                // Every update carries the context use it settles on.
-                return (page.frames.some((frame) => frame.kind === "update")
-                    ? readSessionContext(options, sessionId)
+                // Only a final update that moves the cursor gets a
+                // figure. A wake that moved nothing never re-reads the
+                // whole kept window.
+                const movedHistory = page.frames.some((frame) => frame.kind === "update" &&
+                    frame.cursor !== state.after);
+                return (movedHistory && !page.hasMore
+                    ? readSessionContext(options, sessionId, latestCursor ?? null)
                     : Effect.succeed(undefined)).pipe(Effect.map((context) => [
                     context === undefined
                         ? page.frames
-                        : page.frames.map((frame) => frame.kind === "update"
+                        : page.frames.map((frame) => frame.kind === "update" &&
+                            frame.cursor === latestCursor
                             ? Object.freeze({ ...frame, context })
                             : frame),
                     Option.some(next),
@@ -173,11 +186,14 @@ function decodeWatchInput(sessionId, input) {
 function watchSession(options, runtime, observation, sessionId, input) {
     return runtime.assertOpen.pipe(Effect.andThen(decodeWatchInput(sessionId, input)), Effect.flatMap((decoded) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
         const registration = yield* observation.register(decoded.sessionId);
-        return yield* restore(runtime.assertOpen.pipe(Effect.andThen(readSessionWithContext(options, runtime, decoded.sessionId, decoded.options)), Effect.map((snapshot) => Object.freeze({
-            snapshot,
-            changes: subscriptionFrames(options, runtime, registration, decoded.sessionId, snapshot.cursor ?? undefined, "live", decoded.options.includeSandboxFailures === true).pipe(Stream.ensuring(Effect.sync(registration.close))),
-            close: Effect.sync(registration.close),
-        })))).pipe(Effect.onError(() => Effect.sync(registration.close)));
+        return yield* restore(runtime.assertOpen.pipe(Effect.andThen(readSessionWithContext(options, runtime, decoded.sessionId, decoded.options)), Effect.map((snapshot) => {
+            registration.setQueued(snapshot.activity.queue.state === "queued");
+            return Object.freeze({
+                snapshot,
+                changes: subscriptionFrames(options, runtime, registration, decoded.sessionId, snapshot.cursor ?? undefined, "live", decoded.options.includeSandboxFailures === true).pipe(Stream.ensuring(Effect.sync(registration.close))),
+                close: Effect.sync(registration.close),
+            });
+        }))).pipe(Effect.onError(() => Effect.sync(registration.close)));
     }))));
 }
 /**
@@ -335,6 +351,35 @@ export function openCoordinator(options, runtime) {
                 call: (command, input) => runtime.assertOpen.pipe(Effect.andThen(runtime.extensions.call({ scope: "session", sessionId }, extensionId, command, input))),
             }),
             read: (input) => runtime.assertOpen.pipe(Effect.andThen(readSessionWithContext(options, runtime, sessionId, input))),
+            readSettlement: (commandId, timeoutMs = 0) => Effect.scoped(Effect.gen(function* () {
+                yield* runtime.assertOpen;
+                const decoded = yield* Effect.try({
+                    try: () => ({
+                        sessionId: decodeClientSessionId(sessionId),
+                        ...requireDecoded(decodeClientSettlementRequest({ commandId, timeoutMs }), "Settlement request is invalid"),
+                    }),
+                    catch: (cause) => cause instanceof ShiitakeError
+                        ? cause
+                        : new ShiitakeError("contract", "invalid", "Settlement request is invalid"),
+                });
+                // Subscribe before reading: a commit racing the first read cannot
+                // be missed. Only settlement hints reach this registration.
+                const registration = yield* Effect.acquireRelease(observation.register(decoded.sessionId, "settlement"), (value) => Effect.sync(value.close));
+                const read = readCommandSettlement(options.store, decoded.sessionId, decoded.commandId);
+                const initial = yield* read;
+                if (initial !== undefined || decoded.timeoutMs === 0)
+                    return initial;
+                return yield* Effect.gen(function* () {
+                    for (;;) {
+                        const hint = yield* registration.awaitSignal;
+                        if (hint === "closed")
+                            return yield* Effect.fail(new ShiitakeError("runtime", "closed", "Shiitake is closed"));
+                        const settled = yield* read;
+                        if (settled !== undefined)
+                            return settled;
+                    }
+                }).pipe(Effect.timeoutOption(decoded.timeoutMs), Effect.map(Option.getOrUndefined));
+            })),
             subscribe: (input) => subscribeSession(options, runtime, observation, sessionId, input),
             watch: (input) => watchSession(options, runtime, observation, sessionId, input),
         });
@@ -370,7 +415,47 @@ export function openCoordinator(options, runtime) {
  * is the host's authentication of a delegated Agent's reply; only then does
  * the model see the line inside the verified-reply tag.
  */
-export function acceptAddressedMail(runtime, mail, meta, reply) {
+export function acceptAddressedMail(runtime, mail, meta, reply, stageMail, sessionGrantDelivery) {
+    if (mail.to.sessionId === undefined) {
+        if (reply !== undefined || mail.replyTo.length === 0)
+            throw new Error("Only delegated work can create a recipient Session");
+        return runtime.door.transact((admit) => {
+            const sessionId = runtime.createSessionWithinTransaction(mail.key);
+            const grants = sessionGrantDelivery?.(sessionId);
+            if (grants !== undefined)
+                runtime.stageSessionGrantsWithinTransaction(sessionId, grants);
+            const addressed = {
+                ...mail,
+                to: { ...mail.to, sessionId },
+            };
+            const request = {
+                sessionId,
+                requireExistingSession: true,
+                command: {
+                    requestId: mail.key,
+                    delivery: "followUp",
+                    type: "prompt",
+                    text: mail.content,
+                },
+                when: "now",
+                origin: { kind: "user" },
+                mail: addressed,
+                onAccepted: (_acceptedSessionId, commandId) => {
+                    if (stageMail === undefined)
+                        throw new Error("Recipient Agent mail outbox is unavailable");
+                    stageMail(acceptedNotice(mail, sessionId, commandId, Date.now()));
+                },
+            };
+            const result = admit(meta === undefined ? request : { ...request, meta });
+            if (result.status !== "accepted")
+                throw new Error("Sessionless addressed mail was not admitted");
+            return {
+                status: "accepted",
+                commandId: result.commandId,
+                sessionId,
+            };
+        });
+    }
     return admitUserWork(runtime, mail.to.sessionId, {
         requestId: mail.key,
         delivery: reply === undefined ? "followUp" : "steer",

package/dist/internal/effect-client.d.ts

@@ -5,7 +5,9 @@ import type { ShiitakeOwnerAgent, ShiitakeOptions } from "./contracts.js";
 /** Adapt a Promise tool configuration for both initial open and reload. */
 export declare function liftTools(toolSource: NonNullable<ShiitakeOptions["tools"]>): NonNullable<ShiitakeEffectOptions["tools"]>;
 /** Run one Shiitake Effect through its sole Promise error adaptation. */
-export declare function runShiitakePromise<A, E>(effect: Effect.Effect<A, E>): Promise<A>;
+export declare function runShiitakePromise<A, E>(effect: Effect.Effect<A, E>, options?: Readonly<{
+    signal?: AbortSignal;
+}>): Promise<A>;
 /** Adapt one canonical Effect agent to Shiitake's ordinary web interface. */
 export declare function toPromiseAgent(agent: ShiitakeEffectAgent, suppliedAddress?: string): ShiitakeAgent;
 /**

package/dist/internal/effect-client.js

@@ -19,8 +19,8 @@ export function liftTools(toolSource) {
         : { ...tools, execution: toolSource.execution };
 }
 /** Run one Shiitake Effect through its sole Promise error adaptation. */
-export function runShiitakePromise(effect) {
-    return Effect.runPromiseExit(effect).then((exit) => {
+export function runShiitakePromise(effect, options) {
+    return Effect.runPromiseExit(effect, options).then((exit) => {
         if (Exit.isSuccess(exit))
             return exit.value;
         const failure = Option.getOrUndefined(Cause.findErrorOption(exit.cause));
@@ -76,6 +76,7 @@ function sessionFacade(address, session) {
             });
         },
         read: (input) => runShiitakePromise(session.read(input)),
+        readSettlement: (commandId, options) => runShiitakePromise(session.readSettlement(commandId, options?.timeoutMs), options),
         subscribe: (input) => observationAsyncIterable(session.subscribe(input)),
         watch: (input) => runShiitakePromise(session.watch(input)).then((watch) => Object.freeze({
             snapshot: watch.snapshot,

package/dist/internal/effect-contracts.d.ts

@@ -2,7 +2,7 @@ import type { HostMetaOptions } from "./host-meta.js";
 import type { ExtensionRosterV0 } from "../extensions.js";
 import type { Api, AssistantMessage, Model, MuleStreamFunction, RetryPolicy } from "@fungi.computer/mule/effect";
 import type { CapabilitySource, ExecutionOptions, ModuleRegistration } from "@fungi.computer/mycelium";
-import type { GrantsDelivery, GrantsDeliveryResult, ToolAccess } from "./contracts.js";
+import type { CommandSettlement, GrantsDelivery, GrantsDeliveryResult, ToolAccess } from "./contracts.js";
 import type { Sandbox } from "@fungi.computer/mycelium/effect";
 import * as Effect from "effect/Effect";
 import * as Stream from "effect/Stream";
@@ -26,6 +26,8 @@ export type ModelAcquisitionEffect = Readonly<{
     retryable: (message: AssistantMessage) => boolean;
     /** Owner-authored reason for this door's failure message, never SDK prose. */
     failureReason?: (message: AssistantMessage) => string | undefined;
+    /** Provider prose for this door's exact failed turn; never a diagnostic. */
+    providerError?: (message: AssistantMessage) => string | undefined;
     /** Effect finalizer for acquired model resources. */
     release: Effect.Effect<void, ShiitakeError>;
 }>;
@@ -128,7 +130,7 @@ export type ShiitakeEffectOptions = Readonly<{
     retry?: RetryPolicy;
     /**
      * Maximum silence between live provider stream events, in milliseconds.
-     * Omitted means `piHttpIdleTimeoutMs` (Pi coding-agent's own default).
+     * Omitted uses Mule's model stream limits.
      */
     modelStreamIdleTimeoutMs?: number;
 }>;
@@ -189,6 +191,8 @@ export type ShiitakeEffectSession = Readonly<{
     }>;
     /** Read a bounded durable baseline. */
     read: (input?: ReadOptions) => Effect.Effect<SessionSnapshot, ShiitakeError>;
+    /** Exact command facts; timeout releases observation without cancelling work. */
+    readSettlement: (commandId: string, timeoutMs?: number) => Effect.Effect<CommandSettlement | undefined, ShiitakeError>;
     /** Subscribe to strict-after replay and live frames. */
     subscribe: (input: SubscribeOptions) => Stream.Stream<SessionFrame, ShiitakeError>;
     /** Open a race-safe baseline plus live changes resource. */

package/dist/internal/model-acquisition.js

@@ -21,6 +21,8 @@ function asEffectAcquisition(acquisition) {
     };
     if (acquisition.failureReason !== undefined)
         shared = { ...shared, failureReason: acquisition.failureReason };
+    if (acquisition.providerError !== undefined)
+        shared = { ...shared, providerError: acquisition.providerError };
     if (acquisition.stream === undefined)
         return acquisition.retryAfterMs === undefined
             ? Object.freeze(shared)

package/dist/internal/observation-kernel.d.ts

@@ -2,8 +2,8 @@ import * as Effect from "effect/Effect";
 import { ShiitakeError } from "../errors.js";
 import type { SqliteOwner } from "./contracts.js";
 /** Finite process-local signal; durable owner state remains authoritative. */
-export type ObservationSignal = "closed" | "reset" | "durable" | "progress";
-export type ObservationReason = "durable" | "progress";
+export type ObservationSignal = "closed" | "reset" | "durable" | "activity" | "progress";
+export type ObservationReason = "durable" | "activity" | "progress" | "settlement";
 /** One scoped process-local observation registration. */
 export type ObservationRegistration = Readonly<{
     /** Inspect and consume one pending finite signal without waiting. */
@@ -12,17 +12,21 @@ export type ObservationRegistration = Readonly<{
     awaitSignal: Effect.Effect<ObservationSignal>;
     /** Release this registration without affecting durable work. */
     close: () => void;
+    /** Track whether this Session's current queue head is waiting on the Agent. */
+    setQueued: (queued: boolean) => void;
 }>;
 /** Process-local wake coordination; durable facts remain authoritative. */
 export type ObservationKernel = Readonly<{
     /** Register before the caller's first durable read. */
-    register: (sessionId: string) => Effect.Effect<ObservationRegistration, ShiitakeError>;
+    register: (sessionId: string, interest?: "settlement") => Effect.Effect<ObservationRegistration, ShiitakeError>;
     /** Close every registration and release this agent's owner publisher. */
     close: Effect.Effect<void>;
 }>;
 /** Combine coalesced reasons without allowing a progress hint to hide a commit. */
 export declare function mergeObservationSignals(first: ObservationSignal, second: ObservationSignal): ObservationSignal;
-/** Notify owner observers; null identifies an Agent-wide execution change. */
+/** Notify observers of one Session's durable or process-local change. */
 export declare function publishOwnerObservation(store: SqliteOwner, sessionId: string | null, reason?: ObservationReason): void;
+/** Wake queued Sessions when this Agent's execution slot changes. */
+export declare function publishAgentExecutionChange(store: SqliteOwner): void;
 /** Open one coalescing process-local observation kernel per agent. */
 export declare function openObservationKernel(store: SqliteOwner): ObservationKernel;

package/dist/internal/observation-kernel.js

@@ -12,6 +12,8 @@ export function mergeObservationSignals(first, second) {
         return "reset";
     if (first === "durable" || second === "durable")
         return "durable";
+    if (first === "activity" || second === "activity")
+        return "activity";
     return "progress";
 }
 function queueObservation(listener, reason) {
@@ -25,7 +27,9 @@ function queueObservation(listener, reason) {
     listener.pendingReason =
         listener.pendingReason === "durable" || reason === "durable"
             ? "durable"
-            : "progress";
+            : listener.pendingReason === "activity" || reason === "activity"
+                ? "activity"
+                : "progress";
 }
 function deliverObservation(listener, reason) {
     if (listener.closed || listener.reset)
@@ -46,14 +50,14 @@ function deliverObservation(listener, reason) {
         listener.reset = true;
     }
 }
-/** Notify owner observers; null identifies an Agent-wide execution change. */
+/** Notify observers of one Session's durable or process-local change. */
 export function publishOwnerObservation(store, sessionId, reason = "durable") {
     const publishers = ownerPublishers.get(store);
     if (publishers === undefined)
         return;
     for (const publish of publishers) {
         try {
-            publish(sessionId, reason);
+            publish({ kind: "session", sessionId, reason });
         }
         catch (cause) {
             reportCatchFailure("owner-observation-publish", cause);
@@ -61,6 +65,20 @@ export function publishOwnerObservation(store, sessionId, reason = "durable") {
         }
     }
 }
+/** Wake queued Sessions when this Agent's execution slot changes. */
+export function publishAgentExecutionChange(store) {
+    const publishers = ownerPublishers.get(store);
+    if (publishers === undefined)
+        return;
+    for (const publish of publishers) {
+        try {
+            publish({ kind: "agent-execution" });
+        }
+        catch (cause) {
+            reportCatchFailure("owner-execution-change-publish", cause);
+        }
+    }
+}
 /** Open one coalescing process-local observation kernel per agent. */
 export function openObservationKernel(store) {
     const sessions = new Map();
@@ -79,7 +97,7 @@ export function openObservationKernel(store) {
         listener.pendingCount = 0;
         const reason = listener.pendingReason;
         listener.pendingReason = undefined;
-        return reason === "durable" ? "durable" : "progress";
+        return reason ?? "progress";
     };
     const closeListener = (listener) => {
         if (listener.closed)
@@ -104,26 +122,39 @@ export function openObservationKernel(store) {
             }
         }
     };
-    const publish = (sessionId, reason) => {
-        const listeners = sessionId === null ? active : sessions.get(sessionId);
+    const publish = (publication) => {
+        if (publication.kind === "agent-execution") {
+            for (const listener of active)
+                if (listener.queued && !listener.settlementOnly)
+                    deliverObservation(listener, "activity");
+            return;
+        }
+        const listeners = publication.sessionId === null
+            ? active
+            : sessions.get(publication.sessionId);
         if (listeners === undefined)
             return;
-        for (const listener of listeners)
-            deliverObservation(listener, reason);
+        for (const listener of listeners) {
+            if (listener.settlementOnly && publication.reason !== "settlement")
+                continue;
+            deliverObservation(listener, publication.reason === "settlement" ? "durable" : publication.reason);
+        }
     };
     publishers.add(publish);
     ownerPublishers.set(store, publishers);
     return Object.freeze({
-        register: (sessionId) => Effect.suspend(() => {
+        register: (sessionId, interest) => Effect.suspend(() => {
             if (released)
                 return Effect.fail(new ShiitakeError("runtime", "closed", "Shiitake is closed"));
             if (active.size >= MAX_OBSERVATIONS)
                 return Effect.fail(new ShiitakeError("runtime", "rejected", "Observation capacity is exhausted"));
             const listener = {
                 sessionId,
+                settlementOnly: interest === "settlement",
                 closed: false,
                 pendingCount: 0,
                 pendingReason: undefined,
+                queued: true,
                 reset: false,
                 wake: undefined,
             };
@@ -153,6 +184,10 @@ export function openObservationKernel(store) {
                 close: () => {
                     closeListener(listener);
                 },
+                setQueued: (queued) => {
+                    if (!listener.closed)
+                        listener.queued = queued;
+                },
             }));
         }),
         close: Effect.sync(() => {

package/dist/internal/promise-facade.d.ts

@@ -14,5 +14,5 @@ export declare function openPromiseAgent(options: ShiitakeOptions, make: (option
 export declare function openPromiseHost(options: ShiitakeOptions, mailRoom: BirdDogEffect, openHost: (options: ShiitakeEffectOptions, mailRoom: BirdDogEffect) => Effect.Effect<ShiitakeEffectHost, ShiitakeError>): Promise<Readonly<{
     agent: ShiitakeOwnerAgent;
     readSettlement: (sessionId: string, commandId: string) => Promise<CommandSettlement | undefined>;
-    acceptMail: (mail: BirdDogMail, meta?: Json, reply?: VerifiedAgentReply) => Promise<Accepted>;
+    acceptMail: (mail: BirdDogMail, meta?: Json, reply?: VerifiedAgentReply, stageAcceptedNotice?: (mail: BirdDogMail) => void) => Promise<Accepted>;
 }>>;

package/dist/internal/promise-facade.js

@@ -155,6 +155,6 @@ export function openPromiseHost(options, mailRoom, openHost) {
     return runShiitakePromise(liftRuntime(options).pipe(Effect.flatMap((runtime) => openHost(liftOptions(options, runtime), mailRoom)))).then(({ agent, acceptMail, readSettlement }) => Object.freeze({
         agent: toPromiseOwner(agent),
         readSettlement: (sessionId, commandId) => runShiitakePromise(readSettlement(sessionId, commandId)),
-        acceptMail: (mail, meta, reply) => runShiitakePromise(acceptMail(mail, meta, reply)),
+        acceptMail: (mail, meta, reply, stageAcceptedNotice) => runShiitakePromise(acceptMail(mail, meta, reply, stageAcceptedNotice)),
     }));
 }