@fungi.computer/shiitake 0.4.0 → 0.6.0

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

@@ -86,11 +86,16 @@ export function createFleetDelegationStore(storage) {
   ) STRICT`);
     storage.sql.exec(`CREATE TABLE IF NOT EXISTS shiitake_fleet_held_delegations (
     request_id TEXT PRIMARY KEY
+  ) STRICT`);
+    storage.sql
+        .exec(`CREATE TABLE IF NOT EXISTS shiitake_fleet_undeliverable_delegations (
+    request_id TEXT PRIMARY KEY
   ) STRICT`);
     return {
         read: (requestId) => storage.sql
             .exec(`SELECT delegation.input, delegation.mail,
             CASE
+              WHEN terminal.request_id IS NOT NULL THEN 'undeliverable'
               WHEN held.request_id IS NOT NULL THEN 'held'
               WHEN delegation.receipt IS NOT NULL THEN 'accepted'
               ELSE 'pending'
@@ -99,6 +104,8 @@ export function createFleetDelegationStore(storage) {
           FROM shiitake_fleet_delegations AS delegation
           LEFT JOIN shiitake_fleet_held_delegations AS held
             ON held.request_id = delegation.request_id
+          LEFT JOIN shiitake_fleet_undeliverable_delegations AS terminal
+            ON terminal.request_id = delegation.request_id
           WHERE delegation.request_id = ?`, requestId)
             .toArray()[0],
         /** Every recipient-accepted delegation, newest first. */
@@ -135,7 +142,27 @@ export function createFleetDelegationStore(storage) {
             storage.transactionSync(() => {
                 storage.sql.exec(`INSERT OR IGNORE INTO shiitake_fleet_held_delegations (request_id)
           SELECT request_id FROM shiitake_fleet_delegations
-          WHERE request_id = ? AND receipt IS NULL`, requestId);
+          WHERE request_id = ? AND receipt IS NULL
+            AND NOT EXISTS (
+              SELECT 1 FROM shiitake_fleet_undeliverable_delegations
+              WHERE request_id = ?
+            )`, requestId, requestId);
+            });
+        },
+        recordUndeliverable(requestId) {
+            return storage.transactionSync(() => {
+                const held = storage.sql
+                    .exec(`SELECT delegation.request_id
+            FROM shiitake_fleet_delegations AS delegation
+            JOIN shiitake_fleet_held_delegations AS held
+              ON held.request_id = delegation.request_id
+            WHERE delegation.request_id = ? AND delegation.receipt IS NULL`, requestId)
+                    .toArray()[0];
+                if (held === undefined)
+                    return false;
+                storage.sql.exec("INSERT OR IGNORE INTO shiitake_fleet_undeliverable_delegations(request_id) VALUES (?)", requestId);
+                storage.sql.exec("DELETE FROM shiitake_fleet_held_delegations WHERE request_id = ?", requestId);
+                return true;
             });
         },
     };

package/dist/internal/woodstock/index.d.ts

@@ -15,6 +15,8 @@ export * from "./extension-store.js";
 export { readLatestPendingPrompt } from "./client-projection.js";
 export { createFleetDirectoryStore, createFleetDelegationStore, } from "./fleet-store.js";
 export * from "./session-attention.js";
+export * from "./work-senders.js";
+export * from "./session-delegator.js";
 export { deliverSessionGrants, prepareSessionGrants, readSessionGrants, type GrantsDelivery, type GrantsDeliveryResult, } from "./session-grants.js";
 export * from "./progress.js";
 export * from "./compaction-activity.js";
@@ -138,6 +140,8 @@ export declare function readSessionFactPage(owner: SqliteOwner, after?: string):
 export declare function readColdSessionPage(owner: SqliteOwner, request: ColdSessionPageRequest): Effect.Effect<ColdSessionPage, ShiitakeError>;
 /** Read one bounded inbox page in tier, then newest-activity order. */
 export declare function readSessionInbox(owner: SqliteOwner, after: string | undefined): Effect.Effect<import("../../client.js").SessionSummaryPage, ShiitakeError>;
+/** Read a Session's open attention items from the store alone. */
+export declare function readStoredSessionAttention(owner: SqliteOwner, sessionId: string): Effect.Effect<readonly import("../../client.js").SessionAttention[], ShiitakeError>;
 /** Read one strict-after page from Woodstock's selected lineage. */
 export declare function readSessionReplayPage(owner: SqliteOwner, sessionId: string, after: string | undefined, delivery: "replay" | "live", activity: ObservedActivity, projectExtensions?: () => SessionExtensionSlots, includeSandboxFailures?: boolean): Effect.Effect<ClientReplayPage, ShiitakeError>;
 /** Persist an operator-only sandbox diagnostic beside its accepted Session work. */

package/dist/internal/woodstock/index.js

@@ -9,10 +9,13 @@ import { openProgress, openToolProgress } from "./progress.js";
 import { encodeStoredSessionEntry, } from "./session-entry.js";
 import { appendSessionEntry, appendCompactionTransitionOwned, appendCompactionNoticeOwned, placeCompactionTransitionOwned, acceptSessionAbort, acceptSessionCancellation, completeSessionLeaf, prepareSessionRun, prepareSessionStore, readSessionEntriesForWork, readSessionCommandAdmission, settleSessionControls, takePendingSessionControls, readSessionEntryById, selectSessionBranch, forkSessionAt, readStoredSessionSummary as readSessionSummaryOwned, readStoredSessionFactPage, createStoredSession, createStoredSessionWithinTransaction, deleteStoredSession, appendOperatorEntry, } from "./session-store.js";
 import { readSessionInboxPage, recordSessionInboxDeletion, } from "./session-inbox.js";
+import { readSessionAttention } from "./session-attention.js";
 export * from "./extension-store.js";
 export { readLatestPendingPrompt } from "./client-projection.js";
 export { createFleetDirectoryStore, createFleetDelegationStore, } from "./fleet-store.js";
 export * from "./session-attention.js";
+export * from "./work-senders.js";
+export * from "./session-delegator.js";
 export { deliverSessionGrants, prepareSessionGrants, readSessionGrants, } from "./session-grants.js";
 export * from "./progress.js";
 export * from "./compaction-activity.js";
@@ -228,6 +231,10 @@ export function readColdSessionPage(owner, request) {
 export function readSessionInbox(owner, after) {
     return storeEffect(() => readSessionInboxPage(owner, after));
 }
+/** Read a Session's open attention items from the store alone. */
+export function readStoredSessionAttention(owner, sessionId) {
+    return storeEffect(() => readSessionAttention(owner, sessionId));
+}
 /** Read one strict-after page from Woodstock's selected lineage. */
 export function readSessionReplayPage(owner, sessionId, after, delivery, activity, projectExtensions = () => ({}), includeSandboxFailures = false) {
     return storeEffect(() => readClientReplayPage(owner, decodeClientSessionId(sessionId), after, delivery, activity, projectExtensions, includeSandboxFailures));

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

@@ -0,0 +1,12 @@
+import type { BirdDogDelegator, BirdDogMail } from "@fungi.computer/bird-dog";
+import type { SqliteOwner } from "../contracts.js";
+/** Woodstock keeps each Session's delegator of record beside the Session. */
+export declare function prepareSessionDelegators(owner: SqliteOwner): void;
+/**
+ * Record who sent a Session its work first, in the admitting transaction.
+ * Only an original mail that asks for replies names a delegator; the first one
+ * stays, so the relationship never moves once it exists.
+ */
+export declare function recordSessionDelegator(owner: SqliteOwner, sessionId: string, mail: BirdDogMail | undefined): void;
+/** The Session's delegator of record, if any Agent has sent it work. */
+export declare function readSessionDelegator(owner: SqliteOwner, sessionId: string): BirdDogDelegator | undefined;

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

@@ -0,0 +1,44 @@
+import { BirdDogAgentReferenceSchema } from "@fungi.computer/bird-dog/effect";
+import * as Schema from "effect/Schema";
+const decodeRow = Schema.decodeUnknownSync(Schema.Struct({
+    mail_key: Schema.String,
+    agent_id: Schema.String,
+    reply_to_json: Schema.fromJsonString(Schema.Array(BirdDogAgentReferenceSchema)),
+}));
+const encodeReplyTo = Schema.encodeSync(Schema.fromJsonString(Schema.Array(BirdDogAgentReferenceSchema)));
+/** Woodstock keeps each Session's delegator of record beside the Session. */
+export function prepareSessionDelegators(owner) {
+    owner.sql.exec(`CREATE TABLE IF NOT EXISTS session_delegators (
+    session_id TEXT PRIMARY KEY,
+    mail_key TEXT NOT NULL,
+    agent_id TEXT NOT NULL,
+    reply_to_json TEXT NOT NULL
+  )`);
+}
+/**
+ * Record who sent a Session its work first, in the admitting transaction.
+ * Only an original mail that asks for replies names a delegator; the first one
+ * stays, so the relationship never moves once it exists.
+ */
+export function recordSessionDelegator(owner, sessionId, mail) {
+    if (mail === undefined ||
+        mail.reply !== undefined ||
+        mail.from.kind !== "agent" ||
+        mail.replyTo.length === 0)
+        return;
+    owner.sql.exec("INSERT OR IGNORE INTO session_delegators (session_id, mail_key, agent_id, reply_to_json) VALUES (?, ?, ?, ?)", sessionId, mail.key, mail.to.agentId, encodeReplyTo(mail.replyTo));
+}
+/** The Session's delegator of record, if any Agent has sent it work. */
+export function readSessionDelegator(owner, sessionId) {
+    const [row] = owner.sql
+        .exec("SELECT mail_key, agent_id, reply_to_json FROM session_delegators WHERE session_id = ?", sessionId)
+        .toArray();
+    if (row === undefined)
+        return undefined;
+    const decoded = decodeRow(row);
+    return {
+        key: decoded.mail_key,
+        agentId: decoded.agent_id,
+        replyTo: decoded.reply_to_json,
+    };
+}

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

@@ -74,6 +74,11 @@ declare const StoredSessionEntrySchema: Schema.Union<readonly [Schema.Struct<{
         readonly commandId: Schema.String;
         readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
         readonly diagnostic: Schema.optionalKey<Schema.String>;
+        readonly waitingOnYou: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly itemId: Schema.String;
+            readonly kind: Schema.String;
+            readonly summary: Schema.String;
+        }>>>;
         readonly agentId: Schema.String;
         readonly sessionId: Schema.String;
     }>, Schema.Struct<{
@@ -357,15 +362,20 @@ export declare function decodeStoredSessionEntry(value: string): Result.Result<{
     readonly delivery?: "followUp" | "steer";
     readonly meta?: import("../../extensions.js").Json;
     readonly reply?: {
+        readonly agentId: string;
         readonly sessionId: string;
         readonly commandId: string;
         readonly outcome: "completed" | "failed" | "cancelled" | "interrupted" | "outcome_unknown";
-        readonly agentId: string;
         readonly diagnostic?: string;
+        readonly waitingOnYou?: readonly {
+            readonly itemId: string;
+            readonly kind: string;
+            readonly summary: string;
+        }[];
     } | {
+        readonly agentId: string;
         readonly reason: "recipient_offline" | "recipient_left";
         readonly outcome: "undeliverable";
-        readonly agentId: string;
         readonly sessionId?: string;
     };
     readonly targetWorkId?: string;

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

@@ -237,6 +237,8 @@ export declare function settleSessionControls(owner: SqliteOwner, input: Readonl
 export declare function readSessionCommandAdmission(owner: SqliteOwner, sessionId: string, id: string): StoredCommandAdmission | undefined;
 /** Read one stable private command admission by accepted request identity. */
 export declare function readSessionCommandAdmissionByRequest(owner: SqliteOwner, sessionId: string, requestId: string): StoredCommandAdmission | undefined;
+/** Probe the indexed terminal facts without materializing a live work's body. */
+export declare function hasSessionWorkTerminal(owner: SqliteOwner, sessionId: string, workId: string): boolean;
 /** Read entries correlated to one accepted work identity in Session order. */
 export declare function readSessionEntriesForWork(owner: SqliteOwner, sessionId: string, workId: string): readonly StoredSessionRow[];
 /** Read the latest retained live-retry event for one accepted work item. */

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

@@ -7,6 +7,8 @@ import { compactionSummaryMessage } from "../compaction/utils.js";
 import { SessionTitleSchema, sessionTitleLimit } from "../client-boundary.js";
 import { commandTimestamp, decodeStoredSessionEntry, encodeStoredSessionEntry, isCompactCommand, commandContextMessage, operatorContextMessage, promptCommand, } from "./session-entry.js";
 import { prepareSessionAttention } from "./session-attention.js";
+import { prepareWorkSenders } from "./work-senders.js";
+import { prepareSessionDelegators } from "./session-delegator.js";
 import { copySessionGrants, prepareSessionGrants } from "./session-grants.js";
 import { prepareSessionInbox, touchSessionInbox } from "./session-inbox.js";
 import { sessionIds } from "./identities.js";
@@ -680,6 +682,18 @@ function readSessionCommandAdmissionByWorkId(owner, sessionId, workId) {
 export function readSessionCommandAdmissionByRequest(owner, sessionId, requestId) {
     return readCommandAdmission(owner, sessionId, { requestId });
 }
+/** Probe the indexed terminal facts without materializing a live work's body. */
+export function hasSessionWorkTerminal(owner, sessionId, workId) {
+    // Keep the readability check even when the work has no terminal rows.
+    readSessionRow(owner, sessionId);
+    return (owner.sql
+        .exec(`SELECT 1 AS present FROM session_entries
+         INDEXED BY idx_session_entries_work_terminal
+         WHERE session_id = ? AND work_id = ?
+           AND type IN ('run_terminal', 'work_terminal')
+         LIMIT 1`, sessionId, workId)
+        .toArray().length > 0);
+}
 /** Read entries correlated to one accepted work identity in Session order. */
 export function readSessionEntriesForWork(owner, sessionId, workId) {
     // Refuse the Session before selecting entries: a damaged work may have no
@@ -832,6 +846,7 @@ export function deleteStoredSession(owner, input) {
             "DELETE FROM session_command_admissions WHERE session_id = ?",
             // The inbox row references the Session; it goes in the same transaction.
             "DELETE FROM session_attention WHERE session_id = ?",
+            "DELETE FROM session_work_senders WHERE session_id = ?",
             "DELETE FROM session_tool_grants WHERE session_id = ?",
             "DELETE FROM session_inbox WHERE session_id = ?",
             "DELETE FROM session_creation_receipts WHERE session_id = ?",
@@ -1128,6 +1143,8 @@ export function prepareSessionStore(owner) {
         createSessionEntryTable(owner);
         prepareSessionDocuments(owner);
         prepareSessionAttention(owner);
+        prepareWorkSenders(owner);
+        prepareSessionDelegators(owner);
         prepareSessionGrants(owner);
         prepareSessionInbox(owner);
         owner.sql.exec(`
@@ -1143,6 +1160,9 @@ export function prepareSessionStore(owner) {
        ON session_entries(session_id, request_id)
        WHERE request_id IS NOT NULL`);
         owner.sql.exec("CREATE INDEX IF NOT EXISTS idx_session_entries_work ON session_entries(work_id, sequence)");
+        owner.sql.exec(`CREATE INDEX IF NOT EXISTS idx_session_entries_work_terminal
+       ON session_entries(session_id, work_id)
+       WHERE type IN ('run_terminal', 'work_terminal')`);
         // Context and preference reads look up these rare older facts directly
         // rather than walking the history behind them.
         owner.sql.exec(`CREATE INDEX IF NOT EXISTS idx_session_entries_model_preference

package/dist/internal/woodstock/work-senders.d.ts

@@ -0,0 +1,32 @@
+import { type AttentionRecipient } from "../../session-attention.js";
+import type { SqliteOwner } from "../contracts.js";
+/** One open item of a Session that waits on the Agent that sent its work. */
+export type WaitingOnYou = Readonly<{
+    itemId: string;
+    kind: string;
+    summary: string;
+}>;
+/**
+ * Woodstock records which Agent Session sent each accepted run, beside the
+ * run's admission. Attention that an extension raises during a run waits on
+ * this sender first; a run no Agent sent has no row.
+ */
+export declare function prepareWorkSenders(owner: SqliteOwner): void;
+/** Record the sender of one accepted run; a replay writes the same row. */
+export declare function recordWorkSender(owner: SqliteOwner, sessionId: string, workId: string, sender: AttentionRecipient): void;
+/** The Agent Session that sent this run, or undefined when none did. */
+export declare function readWorkSender(owner: SqliteOwner, sessionId: string, workId: string): AttentionRecipient | undefined;
+/**
+ * The Session's open attention that waits on the sender of this run, newest
+ * first as stored, bounded. Escalated items wait on someone else and are
+ * absent; a run no Agent sent names none.
+ */
+export declare function readWaitingOnSender(owner: SqliteOwner, sessionId: string, workId: string): readonly WaitingOnYou[];
+/**
+ * The Session's open attention that waits on any of these Agent Sessions,
+ * newest first as stored, bounded: what a reply or report to them names.
+ */
+export declare function readWaitingOn(owner: SqliteOwner, sessionId: string, recipients: readonly Readonly<{
+    agentId: string;
+    sessionId: string;
+}>[]): readonly WaitingOnYou[];

package/dist/internal/woodstock/work-senders.js

@@ -0,0 +1,70 @@
+import * as Schema from "effect/Schema";
+import { AttentionRecipientSchema, } from "../../session-attention.js";
+import { readSessionAttention } from "./session-attention.js";
+/** The most open items one settlement names as waiting on its sender. */
+const maximumWaitingOnYou = 8;
+const decodeRow = Schema.decodeUnknownSync(Schema.Struct({
+    agent_id: Schema.String,
+    sender_session_id: Schema.String,
+    name: Schema.String,
+}));
+const decodeRecipient = Schema.decodeUnknownSync(AttentionRecipientSchema);
+/**
+ * Woodstock records which Agent Session sent each accepted run, beside the
+ * run's admission. Attention that an extension raises during a run waits on
+ * this sender first; a run no Agent sent has no row.
+ */
+export function prepareWorkSenders(owner) {
+    owner.sql.exec(`CREATE TABLE IF NOT EXISTS session_work_senders (
+    session_id TEXT NOT NULL,
+    work_id TEXT NOT NULL,
+    agent_id TEXT NOT NULL,
+    sender_session_id TEXT NOT NULL,
+    name TEXT NOT NULL,
+    PRIMARY KEY (session_id, work_id)
+  )`);
+}
+/** Record the sender of one accepted run; a replay writes the same row. */
+export function recordWorkSender(owner, sessionId, workId, sender) {
+    owner.sql.exec(`INSERT OR IGNORE INTO session_work_senders
+       (session_id, work_id, agent_id, sender_session_id, name)
+     VALUES (?, ?, ?, ?, ?)`, sessionId, workId, sender.agentId, sender.sessionId, sender.name);
+}
+/** The Agent Session that sent this run, or undefined when none did. */
+export function readWorkSender(owner, sessionId, workId) {
+    const raw = owner.sql
+        .exec("SELECT agent_id, sender_session_id, name FROM session_work_senders WHERE session_id = ? AND work_id = ?", sessionId, workId)
+        .toArray()[0];
+    if (raw === undefined)
+        return undefined;
+    const row = decodeRow(raw);
+    return decodeRecipient({
+        agentId: row.agent_id,
+        sessionId: row.sender_session_id,
+        name: row.name,
+    });
+}
+/**
+ * The Session's open attention that waits on the sender of this run, newest
+ * first as stored, bounded. Escalated items wait on someone else and are
+ * absent; a run no Agent sent names none.
+ */
+export function readWaitingOnSender(owner, sessionId, workId) {
+    const sender = readWorkSender(owner, sessionId, workId);
+    return sender === undefined ? [] : readWaitingOn(owner, sessionId, [sender]);
+}
+/**
+ * The Session's open attention that waits on any of these Agent Sessions,
+ * newest first as stored, bounded: what a reply or report to them names.
+ */
+export function readWaitingOn(owner, sessionId, recipients) {
+    return readSessionAttention(owner, sessionId)
+        .filter((item) => recipients.some((recipient) => item.waitingOn?.agentId === recipient.agentId &&
+        item.waitingOn.sessionId === recipient.sessionId))
+        .slice(0, maximumWaitingOnYou)
+        .map((item) => ({
+        itemId: item.id,
+        kind: item.kind,
+        summary: item.summary,
+    }));
+}

package/dist/remote-client.js

@@ -72,7 +72,12 @@ function remoteEvents(url, clientClosed, sources, eventSource) {
                 closed: false,
             };
             const emit = (kind, event) => {
-                Queue.offerUnsafe(queue, { kind, event });
+                if (!Queue.offerUnsafe(queue, { kind, event })) {
+                    // A dropped frame breaks this watch's ordering. Fail instead
+                    // of delivering an incomplete history to the client.
+                    Queue.failCauseUnsafe(queue, Cause.fail(unavailable("Session stream client fell behind")));
+                    Effect.runSync(closeRemoteSource(active, sources));
+                }
             };
             active.source.addEventListener("snapshot", (event) => {
                 emit("snapshot", event);
@@ -91,7 +96,7 @@ function remoteEvents(url, clientClosed, sources, eventSource) {
             return active;
         },
         catch: () => unavailable("Session stream could not open"),
-    }), (active) => closeRemoteSource(active, sources))).pipe(Stream.mapEffect(decodeRemoteEvent), Stream.interruptWhen(clientClosed.await));
+    }), (active) => closeRemoteSource(active, sources)), { bufferSize: 256, strategy: "dropping" }).pipe(Stream.mapEffect(decodeRemoteEvent), Stream.interruptWhen(clientClosed.await));
 }
 function sessionUrl(baseUrl, sessionId) {
     return `${baseUrl}/sessions/${encodeURIComponent(sessionId)}`;

package/dist/server-visitor-stream.d.ts

@@ -0,0 +1,13 @@
+import type { SessionSnapshot, SessionWatch } from "./client.js";
+export type VisitorStreamError = "channel_visitor_stream_expiry_failed" | "channel_visitor_stream_close_failed" | "channel_visitor_stream_heartbeat_failed" | "channel_visitor_stream_failed";
+export declare function visitorStream(options: Readonly<{
+    watch: SessionWatch;
+    visitorId: string;
+    filter: (snapshot: SessionSnapshot) => SessionSnapshot;
+    expiresAt: number;
+    now: () => number;
+    release: () => void;
+    canRead: () => Promise<boolean>;
+    read: () => Promise<SessionSnapshot>;
+    onError: (event: VisitorStreamError, cause: unknown) => void;
+}>): ReadableStream<Uint8Array>;

package/dist/server-visitor-stream.js

@@ -0,0 +1,115 @@
+import { SSEStreamingApi } from "hono/streaming";
+import { visitorSnapshot } from "./client-visitor.js";
+export function visitorStream(options) {
+    const { readable, writable } = new TransformStream();
+    const stream = new SSEStreamingApi(writable, readable);
+    let closing;
+    let ending = false;
+    let heartbeat;
+    const expiry = setTimeout(() => {
+        void close().catch((cause) => {
+            options.onError("channel_visitor_stream_expiry_failed", cause);
+        });
+    }, Math.max(0, options.expiresAt - options.now()));
+    const close = () => {
+        if (closing !== undefined)
+            return closing;
+        ending = true;
+        clearTimeout(expiry);
+        clearTimeout(heartbeat);
+        options.release();
+        closing = Promise.resolve().then(async () => {
+            stream.abort();
+            try {
+                await options.watch.close();
+            }
+            finally {
+                await stream.close();
+            }
+        });
+        return closing;
+    };
+    stream.onAbort(() => {
+        void close().catch((cause) => {
+            options.onError("channel_visitor_stream_close_failed", cause);
+        });
+    });
+    const admitted = async () => !ending &&
+        options.now() < options.expiresAt &&
+        (await options.canRead()) &&
+        !ending;
+    const beat = async () => {
+        if (!(await admitted())) {
+            await close();
+            return;
+        }
+        await stream.write(": heartbeat\n\n");
+        if (!ending)
+            heartbeat = setTimeout(() => {
+                void beat().catch((cause) => {
+                    options.onError("channel_visitor_stream_heartbeat_failed", cause);
+                    void close().catch((closeCause) => {
+                        options.onError("channel_visitor_stream_close_failed", closeCause);
+                    });
+                });
+            }, 30_000);
+    };
+    const publish = async (snapshot, progressOnly) => {
+        if (!(await admitted()))
+            return false;
+        const baseline = visitorSnapshot(options.filter(snapshot), options.visitorId);
+        await stream.writeSSE(progressOnly
+            ? {
+                event: "frame",
+                data: JSON.stringify({
+                    kind: "progress",
+                    progress: baseline.progress,
+                    activity: baseline.activity,
+                }),
+            }
+            : { event: "session", data: JSON.stringify(baseline) });
+        return !ending;
+    };
+    const pump = async () => {
+        try {
+            let snapshot = options.watch.snapshot;
+            if (!(await publish(snapshot, false)))
+                return;
+            heartbeat = setTimeout(() => {
+                void beat().catch((cause) => {
+                    options.onError("channel_visitor_stream_heartbeat_failed", cause);
+                    void close().catch((closeCause) => {
+                        options.onError("channel_visitor_stream_close_failed", closeCause);
+                    });
+                });
+            }, 30_000);
+            for await (const frame of options.watch.changes) {
+                if (ending)
+                    break;
+                if (frame.kind === "tool_output")
+                    continue;
+                snapshot =
+                    frame.kind === "progress"
+                        ? {
+                            ...snapshot,
+                            progress: frame.progress,
+                            activity: frame.activity,
+                        }
+                        : frame.kind === "activity"
+                            ? { ...snapshot, activity: frame.activity }
+                            : frame.kind === "reset"
+                                ? frame.baseline
+                                : await options.read();
+                if (!(await publish(snapshot, frame.kind === "progress")))
+                    break;
+            }
+        }
+        finally {
+            await close();
+        }
+    };
+    void pump().catch((cause) => {
+        options.onError("channel_visitor_stream_failed", cause);
+    });
+    return stream.responseReadable.pipeThrough(new TransformStream());
+}

package/dist/session-attention.d.ts

@@ -1,7 +1,21 @@
 import * as Schema from "effect/Schema";
+/**
+ * The Agent Session that sent the work an item belongs to. The host derives it
+ * from the accepted mail; it is the only party the item waits on until it is
+ * escalated.
+ */
+export declare const AttentionRecipientSchema: Schema.Struct<{
+    readonly agentId: Schema.NonEmptyString;
+    readonly sessionId: Schema.NonEmptyString;
+    readonly name: Schema.NonEmptyString;
+}>;
+/** Decoded Agent Session an attention item waits on. */
+export type AttentionRecipient = typeof AttentionRecipientSchema.Type;
 /**
  * An extension-owned request for human attention; expiry is owned by its timer.
  * Items marked `inbox: false` remain visible without changing the inbox state.
+ * An item with `waitingOn` waits on that Agent first and is never a person's
+ * inbox item until it is escalated past every Agent.
  */
 export declare const AttentionItemSchema: Schema.Struct<{
     readonly id: Schema.NonEmptyString;
@@ -11,6 +25,12 @@ export declare const AttentionItemSchema: Schema.Struct<{
     readonly expiresAt: Schema.optional<Schema.Int>;
     /** This item does not change the Session's inbox state; omission does. */
     readonly inbox: Schema.optional<Schema.Literal<false>>;
+    /** The Agent this item waits on; absent means a person. */
+    readonly waitingOn: Schema.optional<Schema.Struct<{
+        readonly agentId: Schema.NonEmptyString;
+        readonly sessionId: Schema.NonEmptyString;
+        readonly name: Schema.NonEmptyString;
+    }>>;
 }>;
 /** Input to the granted attention door, scoped to the calling extension. */
 export type AttentionItem = typeof AttentionItemSchema.Type;
@@ -23,6 +43,11 @@ export declare const SessionAttentionSchema: Schema.Struct<{
     readonly since: Schema.Int;
     readonly expiresAt: Schema.optional<Schema.Int>;
     readonly inbox: Schema.optional<Schema.Literal<false>>;
+    readonly waitingOn: Schema.optional<Schema.Struct<{
+        readonly agentId: Schema.NonEmptyString;
+        readonly sessionId: Schema.NonEmptyString;
+        readonly name: Schema.NonEmptyString;
+    }>>;
 }>;
 /** One open attention item in a Session observation. */
 export type SessionAttention = typeof SessionAttentionSchema.Type;
@@ -39,4 +64,9 @@ export declare const SessionAttentionListSchema: Schema.$Array<Schema.Struct<{
     readonly since: Schema.Int;
     readonly expiresAt: Schema.optional<Schema.Int>;
     readonly inbox: Schema.optional<Schema.Literal<false>>;
+    readonly waitingOn: Schema.optional<Schema.Struct<{
+        readonly agentId: Schema.NonEmptyString;
+        readonly sessionId: Schema.NonEmptyString;
+        readonly name: Schema.NonEmptyString;
+    }>>;
 }>>;

package/dist/session-attention.js

@@ -1,9 +1,21 @@
 import * as Schema from "effect/Schema";
 const identity = Schema.NonEmptyString.check(Schema.isMaxLength(256));
 const instant = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+/**
+ * The Agent Session that sent the work an item belongs to. The host derives it
+ * from the accepted mail; it is the only party the item waits on until it is
+ * escalated.
+ */
+export const AttentionRecipientSchema = Schema.Struct({
+    agentId: identity,
+    sessionId: identity,
+    name: identity,
+});
 /**
  * An extension-owned request for human attention; expiry is owned by its timer.
  * Items marked `inbox: false` remain visible without changing the inbox state.
+ * An item with `waitingOn` waits on that Agent first and is never a person's
+ * inbox item until it is escalated past every Agent.
  */
 export const AttentionItemSchema = Schema.Struct({
     id: identity,
@@ -13,6 +25,8 @@ export const AttentionItemSchema = Schema.Struct({
     expiresAt: Schema.optional(instant),
     /** This item does not change the Session's inbox state; omission does. */
     inbox: Schema.optional(Schema.Literal(false)),
+    /** The Agent this item waits on; absent means a person. */
+    waitingOn: Schema.optional(AttentionRecipientSchema),
 });
 /** Public identity includes the owner so two extensions can use the same id. */
 export const SessionAttentionSchema = AttentionItemSchema.mapFields((fields) => ({