@fungi.computer/shiitake 0.7.0 → 0.9.0

package/dist/internal/session-observation.js

@@ -0,0 +1,440 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import * as Semaphore from "effect/Semaphore";
+import * as Scope from "effect/Scope";
+import * as Exit from "effect/Exit";
+import { ShiitakeError } from "../errors.js";
+import { decodeClientReadOptions, decodeClientSessionId, decodeClientSubscribeOptions, } from "./client-boundary.js";
+import { mergeObservationSignals, openSessionFrameFeed, } from "./observation-kernel.js";
+import { readSessionActivity, } from "./session-status.js";
+import { prepareSessionContext } from "./session-context.js";
+import { compactionEntrySequence, decodeWoodstockCursor, progressPosition, readProcessProgressDelta, readSession, readSessionReplayPage, } from "./woodstock/index.js";
+import { sessionHeartbeatIntervalMs } from "../session-liveness.js";
+function currentSessionWork(runtime, sessionId) {
+    return runtime
+        .readQueueHead(sessionId)
+        .pipe(Effect.flatMap((head) => (head.state === "queued"
+        ? runtime.runningWork(head.jobId)
+        : Effect.succeed(null)).pipe(Effect.map((runningWork) => ({ head, runningWork })))));
+}
+function currentSessionActivity(options, runtime, sessionId) {
+    return currentSessionWork(runtime, sessionId).pipe(Effect.map(({ head, runningWork }) => readSessionActivity(options.store, sessionId, head, runningWork)));
+}
+/** Carry the Session's context use on a baseline, when it has one. */
+function withContext(snapshot, context) {
+    return context === undefined
+        ? snapshot
+        : Object.freeze({ ...snapshot, context });
+}
+/** Read the baseline and its context use for one Session. */
+function readSessionWithContext(options, runtime, sessionId, input, checkpoint = {}) {
+    return currentSessionWork(runtime, sessionId).pipe(Effect.flatMap(({ head, runningWork }) => {
+        checkpoint.beforeRead?.();
+        return readSession(options.store, sessionId, () => readSessionActivity(options.store, sessionId, head, runningWork), input, () => runtime.extensions.project(sessionId), (snapshot) => ({
+            snapshot,
+            context: prepareSessionContext(options, sessionId, snapshot.cursor, input?.before === undefined),
+        }));
+    }), Effect.flatMap(({ snapshot, context }) => {
+        checkpoint.afterRead?.();
+        return context.pipe(Effect.map((value) => withContext(snapshot, value)));
+    }));
+}
+function decodeSubscriptionInput(sessionId, input) {
+    return Effect.try({
+        try: () => Object.freeze({
+            sessionId: decodeClientSessionId(sessionId),
+            options: decodeClientSubscribeOptions(input),
+        }),
+        catch: (error) => error instanceof ShiitakeError
+            ? error
+            : new ShiitakeError("contract", "invalid", "Subscribe options are invalid"),
+    });
+}
+function resetFrame(options, runtime, sessionId, includeSandboxFailures = false, checkpoint = {}) {
+    return runtime.assertOpen.pipe(Effect.andThen(readSessionWithContext(options, runtime, sessionId, { includeSandboxFailures }, checkpoint)), Effect.map((baseline) => Object.freeze({
+        kind: "reset",
+        reason: "history_unavailable",
+        cursor: baseline.cursor,
+        baseline,
+    })));
+}
+function continueFromReset(frame) {
+    return [
+        [frame],
+        Option.some({
+            after: frame.cursor ?? undefined,
+            delivery: frame.baseline.hasMore ? "replay" : "live",
+            awaitSignal: !frame.baseline.hasMore,
+        }),
+    ];
+}
+function subscriptionFrames(options, runtime, sessionId, after, source, includeSandboxFailures = false) {
+    const registration = source.kind === "live" ? source.registration : undefined;
+    let position = source.kind === "live" ? progressPosition(source.progress) : null;
+    let toolOutput = [];
+    const reset = () => resetFrame(options, runtime, sessionId, includeSandboxFailures, source.kind === "replay"
+        ? { beforeRead: source.checkpoint }
+        : { afterRead: source.stamp }).pipe(Effect.map((frame) => {
+        position = progressPosition(frame.baseline.progress);
+        toolOutput = frame.baseline.toolOutput;
+        return source.kind === "replay"
+            ? [[frame], Option.none()]
+            : continueFromReset(frame);
+    }));
+    const liveFrames = (activity) => {
+        const queue = activity.facts.queue;
+        const delta = queue.state !== "running"
+            ? null
+            : readProcessProgressDelta(options.store, sessionId, queue.commandId, position);
+        if (delta === undefined)
+            return undefined;
+        const frames = [];
+        if (delta !== null) {
+            frames.push({
+                kind: "progress",
+                progress: delta,
+                activity: activity.facts,
+            });
+            position = {
+                messageId: delta.messageId,
+                revision: delta.revision,
+                text: delta.text.offset + delta.text.append.length,
+                thinking: delta.thinking.offset + delta.thinking.append.length,
+            };
+        }
+        if (toolOutput.length !== activity.toolOutput.length ||
+            toolOutput.some((slot, index) => slot !== activity.toolOutput[index])) {
+            toolOutput = activity.toolOutput;
+            frames.push({
+                kind: "tool_output",
+                toolOutput,
+                activity: activity.facts,
+            });
+        }
+        return frames;
+    };
+    const initial = {
+        after,
+        delivery: source.kind,
+        // Live registration precedes its baseline; pending hints cover any join
+        // writes. Replaying it unconditionally adds an unprompted idle read.
+        awaitSignal: source.kind === "live",
+    };
+    return Stream.paginate(initial, (state) => (registration === undefined
+        ? Effect.succeed(undefined)
+        : state.awaitSignal
+            ? registration.awaitSignal.pipe(Effect.flatMap((signal) => registration.pollSignal.pipe(Effect.map((pending) => pending === undefined
+                ? signal
+                : mergeObservationSignals(signal, pending)))))
+            : registration.pollSignal).pipe(Effect.flatMap((signal) => {
+        if (signal === "closed")
+            return Effect.succeed([[], Option.none()]);
+        if (signal === "reset")
+            return reset();
+        return runtime.assertOpen.pipe(Effect.andThen(currentSessionActivity(options, runtime, sessionId)), Effect.flatMap((activity) => {
+            if (source.kind === "replay")
+                source.checkpoint();
+            registration?.setQueued(activity.facts.queue.state === "queued");
+            if ((signal === "progress" || signal === "activity") &&
+                state.delivery === "live") {
+                const frames = liveFrames(activity);
+                if (frames === undefined)
+                    return reset();
+                // This path reads no durable page; stamp the live projection.
+                if (source.kind === "live")
+                    source.stamp();
+                return Effect.succeed([
+                    [
+                        ...(signal === "activity"
+                            ? [
+                                {
+                                    kind: "activity",
+                                    activity: activity.facts,
+                                },
+                            ]
+                            : []),
+                        ...frames,
+                    ],
+                    Option.some({ ...state, awaitSignal: true }),
+                ]);
+            }
+            return readSessionReplayPage(options.store, sessionId, state.after, state.delivery, activity, () => runtime.extensions.project(sessionId), includeSandboxFailures, (page) => {
+                const latestCursor = page.kind === "page"
+                    ? page.frames
+                        .flatMap((frame) => frame.kind === "progress" ||
+                        frame.kind === "activity" ||
+                        frame.kind === "tool_output" ||
+                        frame.kind === "heartbeat"
+                        ? []
+                        : [frame.cursor])
+                        .at(-1)
+                    : undefined;
+                // Capture the final moving page's stored context in the
+                // same read transaction as its cursor. Model description
+                // remains deferred until after that transaction.
+                const context = page.kind === "page" &&
+                    !page.hasMore &&
+                    page.frames.some((frame) => frame.kind === "update" &&
+                        frame.cursor !== state.after)
+                    ? prepareSessionContext(options, sessionId, latestCursor ?? null)
+                    : Effect.succeed(undefined);
+                return { page, latestCursor, context };
+            }).pipe(Effect.flatMap(({ page, latestCursor, context, }) => {
+                if (page.kind === "reset")
+                    return reset();
+                if (source.kind === "live")
+                    source.stamp();
+                if (!page.hasMore)
+                    toolOutput = activity.toolOutput;
+                const progressFrames = page.hasMore
+                    ? []
+                    : liveFrames(activity);
+                if (progressFrames === undefined)
+                    return reset();
+                const next = {
+                    after: latestCursor ?? state.after,
+                    delivery: page.hasMore ? state.delivery : "live",
+                    awaitSignal: !page.hasMore,
+                };
+                return context.pipe(Effect.map((context) => [
+                    [
+                        ...(context === undefined
+                            ? page.frames
+                            : page.frames.map((frame) => frame.kind === "update" &&
+                                frame.cursor === latestCursor
+                                ? Object.freeze({ ...frame, context })
+                                : frame)),
+                        ...progressFrames,
+                    ],
+                    source.kind === "replay" && !page.hasMore
+                        ? Option.none()
+                        : Option.some(next),
+                ]));
+            }));
+        }));
+    })));
+}
+/** One projection producer and heartbeat clock per watched Session. */
+function openLiveSessionFeeds(options, runtime, observation, ownerContext) {
+    const lanes = new Map();
+    const scope = Scope.makeUnsafe();
+    let watchers = 0;
+    const acquire = (sessionId, includeSandboxFailures) => Effect.suspend(() => {
+        let lane = lanes.get(sessionId);
+        if (lane === undefined) {
+            lane = { lock: Semaphore.makeUnsafe(1), feed: undefined };
+            lanes.set(sessionId, lane);
+        }
+        const current = lane;
+        return current.lock.withPermit(Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+            if (lanes.get(sessionId) !== current)
+                return yield* acquire(sessionId, includeSandboxFailures);
+            let feed = current.feed;
+            if (feed === undefined) {
+                const registration = yield* observation.register(sessionId).pipe(Effect.onError(() => Effect.sync(() => {
+                    if (lanes.get(sessionId) === current)
+                        lanes.delete(sessionId);
+                })));
+                const lifecycle = { stopped: false };
+                const frames = openSessionFrameFeed(() => {
+                    stop();
+                });
+                const stop = () => {
+                    if (lifecycle.stopped)
+                        return;
+                    lifecycle.stopped = true;
+                    registration.close();
+                    lifecycle.producer?.interruptUnsafe();
+                    lifecycle.heartbeat?.interruptUnsafe();
+                    frames.end();
+                    current.feed = undefined;
+                    if (lanes.get(sessionId) === current)
+                        lanes.delete(sessionId);
+                };
+                feed = { registration, frames, stop };
+                current.feed = feed;
+                const baseline = yield* restore(readSessionWithContext(options, runtime, sessionId, {
+                    includeSandboxFailures: true,
+                })).pipe(Effect.onError(() => Effect.sync(stop)));
+                registration.setQueued(baseline.activity.queue.state === "queued");
+                let revision = registration.revision;
+                // Replace the joining request's context while forking, so the
+                // long-lived children inherit only the Agent's services/span.
+                lifecycle.producer = yield* Effect.forkIn(subscriptionFrames(options, runtime, sessionId, baseline.cursor ?? undefined, {
+                    kind: "live",
+                    registration,
+                    progress: baseline.progress,
+                    stamp: () => {
+                        revision = registration.revision;
+                    },
+                }, true).pipe(Stream.runForEach((frame) => Effect.sync(() => {
+                    frames.publish(frame, revision);
+                })), Effect.catch((error) => Effect.sync(() => {
+                    frames.end(error);
+                })), Effect.ensuring(Effect.sync(stop))), scope, { uninterruptible: false }).pipe(Effect.setContext(ownerContext));
+                if (!lifecycle.stopped)
+                    lifecycle.heartbeat = yield* Effect.forkIn(Stream.fromEffectRepeat(Effect.sleep(sessionHeartbeatIntervalMs).pipe(Effect.as({ kind: "heartbeat" }))).pipe(Stream.runForEach((frame) => Effect.sync(() => {
+                        frames.publish(frame);
+                    }))), scope, { uninterruptible: false }).pipe(Effect.setContext(ownerContext));
+            }
+            const queue = feed.frames.register(includeSandboxFailures);
+            return { feed, queue };
+        })));
+    });
+    return {
+        acquire: (sessionId, includeSandboxFailures) => Effect.uninterruptibleMask((restore) => Effect.suspend(() => {
+            if (watchers >= 64)
+                return Effect.fail(new ShiitakeError("runtime", "rejected", "Observation capacity is exhausted"));
+            watchers += 1;
+            let released = false;
+            const release = () => {
+                if (released)
+                    return;
+                released = true;
+                watchers -= 1;
+            };
+            return restore(acquire(sessionId, includeSandboxFailures)).pipe(Effect.map(({ feed, queue }) => ({
+                feed,
+                queue: Object.freeze({
+                    ...queue,
+                    close: () => {
+                        release();
+                        queue.close();
+                    },
+                }),
+            })), Effect.onError(() => Effect.sync(release)));
+        })),
+        close: Effect.sync(() => {
+            for (const lane of lanes.values())
+                lane.feed?.stop();
+            lanes.clear();
+        }).pipe(Effect.andThen(Scope.close(scope, Exit.void))),
+    };
+}
+function queuedSessionFrames(queue) {
+    return Stream.paginate(null, () => queue.take.pipe(Effect.map((frame) => frame === "closed"
+        ? [[], Option.none()]
+        : [[frame], Option.some(null)])));
+}
+/** Durable rows dedup by sequence; ephemeral appends dedup only by revision. */
+function reconcileSessionFrames(source, initialCursor, initialProgress, reset) {
+    let cursor = initialCursor;
+    let position = progressPosition(initialProgress);
+    return source.pipe(Stream.mapEffect((incoming) => Effect.gen(function* () {
+        let frame = incoming === "reset" ? yield* reset() : incoming;
+        if (frame.kind === "heartbeat")
+            return [frame];
+        if (frame.kind === "progress") {
+            const previous = position?.messageId === frame.progress.messageId
+                ? position
+                : null;
+            if (previous !== null &&
+                previous.revision >= frame.progress.revision)
+                return [];
+            const text = previous?.text ?? 0;
+            const thinking = previous?.thinking ?? 0;
+            if (frame.progress.text.offset > text ||
+                frame.progress.thinking.offset > thinking)
+                frame = yield* reset();
+            else {
+                position = {
+                    messageId: frame.progress.messageId,
+                    revision: frame.progress.revision,
+                    text: frame.progress.text.offset +
+                        frame.progress.text.append.length,
+                    thinking: frame.progress.thinking.offset +
+                        frame.progress.thinking.append.length,
+                };
+            }
+        }
+        if (frame.kind === "reset") {
+            cursor = frame.cursor;
+            position = progressPosition(frame.baseline.progress);
+            return [frame];
+        }
+        if (frame.kind !== "update")
+            return [frame];
+        const previous = cursor === null ? undefined : decodeWoodstockCursor(cursor);
+        const next = frame.cursor === null
+            ? undefined
+            : decodeWoodstockCursor(frame.cursor);
+        if (previous !== undefined &&
+            next !== undefined &&
+            previous.generation !== next.generation) {
+            const baseline = yield* reset();
+            cursor = baseline.cursor;
+            position = progressPosition(baseline.baseline.progress);
+            return [baseline];
+        }
+        const sequence = previous?.sequence ?? 0;
+        const candidateCursor = next !== undefined && next.sequence > sequence
+            ? frame.cursor
+            : cursor;
+        const duplicate = (rows) => rows?.some((row) => row.sequence <= sequence) === true;
+        if (candidateCursor === frame.cursor &&
+            !duplicate(frame.messages) &&
+            !duplicate(frame.terminals) &&
+            !frame.compactions?.some((marker) => compactionEntrySequence(marker) <= sequence) &&
+            !duplicate(frame.compactionNotices)) {
+            cursor = frame.cursor;
+            return [frame];
+        }
+        const rows = {
+            ...frame,
+            cursor: candidateCursor,
+            messages: frame.messages.filter((row) => row.sequence > sequence),
+            terminals: frame.terminals.filter((row) => row.sequence > sequence),
+        };
+        if (frame.compactions !== undefined)
+            rows.compactions = frame.compactions.filter((marker) => compactionEntrySequence(marker) > sequence);
+        if (frame.compactionNotices !== undefined)
+            rows.compactionNotices = frame.compactionNotices.filter((row) => row.sequence > sequence);
+        cursor = rows.cursor;
+        return [rows];
+    })), Stream.flattenIterable);
+}
+function subscribeSession(options, runtime, feeds, sessionId, input) {
+    return Stream.unwrap(runtime.assertOpen.pipe(Effect.andThen(decodeSubscriptionInput(sessionId, input)), Effect.flatMap((decoded) => Effect.acquireRelease(feeds.acquire(decoded.sessionId, decoded.options.includeSandboxFailures === true), ({ queue }) => Effect.sync(queue.close)).pipe(Effect.map(({ feed, queue }) => {
+        const checkpoint = () => {
+            queue.checkpoint(feed.registration.revision);
+        };
+        return reconcileSessionFrames(subscriptionFrames(options, runtime, decoded.sessionId, decoded.options.after, { kind: "replay", checkpoint }, decoded.options.includeSandboxFailures === true).pipe(Stream.concat(queuedSessionFrames(queue))), decoded.options.after ?? null, null, () => resetFrame(options, runtime, decoded.sessionId, decoded.options.includeSandboxFailures === true, { beforeRead: checkpoint }));
+    })))));
+}
+function decodeWatchInput(sessionId, input) {
+    return Effect.try({
+        try: () => Object.freeze({
+            sessionId: decodeClientSessionId(sessionId),
+            options: decodeClientReadOptions(input),
+        }),
+        catch: (error) => error instanceof ShiitakeError
+            ? error
+            : new ShiitakeError("contract", "invalid", "Watch options are invalid"),
+    });
+}
+function watchSession(options, runtime, feeds, sessionId, input) {
+    return runtime.assertOpen.pipe(Effect.andThen(decodeWatchInput(sessionId, input)), Effect.flatMap((decoded) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+        const { feed, queue } = yield* feeds.acquire(decoded.sessionId, decoded.options.includeSandboxFailures === true);
+        const checkpoint = () => {
+            queue.checkpoint(feed.registration.revision);
+        };
+        return yield* restore(runtime.assertOpen.pipe(Effect.andThen(readSessionWithContext(options, runtime, decoded.sessionId, decoded.options, { beforeRead: checkpoint })), Effect.map((snapshot) => {
+            return Object.freeze({
+                snapshot,
+                changes: reconcileSessionFrames(queuedSessionFrames(queue), snapshot.cursor, snapshot.progress, () => resetFrame(options, runtime, decoded.sessionId, decoded.options.includeSandboxFailures === true, { beforeRead: checkpoint })).pipe(Stream.ensuring(Effect.sync(queue.close))),
+                close: Effect.sync(queue.close),
+            });
+        }))).pipe(Effect.onError(() => Effect.sync(queue.close)));
+    }))));
+}
+/** Shared live observation; Woodstock remains the bounded baseline and replay owner. */
+export function openSessionObservation(options, runtime, observation, ownerContext) {
+    const feeds = openLiveSessionFeeds(options, runtime, observation, ownerContext);
+    return Object.freeze({
+        read: (sessionId, input) => readSessionWithContext(options, runtime, sessionId, input),
+        subscribe: (sessionId, input) => subscribeSession(options, runtime, feeds, sessionId, input),
+        watch: (sessionId, input) => watchSession(options, runtime, feeds, sessionId, input),
+        close: feeds.close,
+    });
+}

package/dist/internal/session-status.d.ts

@@ -7,5 +7,7 @@ export type ObservedActivity = Readonly<{
     readProgress: () => SessionProgress | null;
     toolOutput: readonly SessionToolOutput[];
 }>;
+/** Project only the occupying Session's activity, without disclosing its data. */
+export declare function readSessionPhase(owner: SqliteOwner, sessionId: string, head: WatchdogQueueHead): AgentRunningWork["phase"];
 /** Join Watchdog authority with Woodstock facts and process-local progress. */
 export declare function readSessionActivity(owner: SqliteOwner, sessionId: string, head: WatchdogQueueHead, runningWork: AgentRunningWork | null): ObservedActivity;

package/dist/internal/session-status.js

@@ -1,4 +1,20 @@
-import { readProcessProgressForWork, readProcessToolOutputForWork, readProcessCompaction, readLatestLiveRetryForWork, readActiveToolForWork, readLastModelChoiceSequence, } from "./woodstock/index.js";
+import { readProcessProgressForWork, readProcessToolOutputForWork, readProcessCompaction, readLatestLiveRetryForWork, readActiveToolForWork, readLastModelChoiceSequence, readSessionAttention, hasProcessTextForWork, } from "./woodstock/index.js";
+/** Project only the occupying Session's activity, without disclosing its data. */
+export function readSessionPhase(owner, sessionId, head) {
+    const { facts } = readSessionActivity(owner, sessionId, head, null);
+    if (facts.cancellationRequested)
+        return "cancelling";
+    if (readSessionAttention(owner, sessionId).some((item) => item.inbox !== false && item.waitingOn === undefined))
+        return "waiting_on_you";
+    if (facts.compaction !== null || facts.retry !== null)
+        return "thinking";
+    if (facts.activeTool !== null)
+        return "running_tool";
+    if (head.state === "running" &&
+        hasProcessTextForWork(owner, sessionId, head.jobId))
+        return "streaming";
+    return "thinking";
+}
 /** Join Watchdog authority with Woodstock facts and process-local progress. */
 export function readSessionActivity(owner, sessionId, head, runningWork) {
     const lastModelChoiceSequence = readLastModelChoiceSequence(owner, sessionId);

package/dist/internal/woodstock/client-projection.d.ts

@@ -1,4 +1,4 @@
-import type { SessionFrame, SessionExtensionSlots, SessionPendingPrompts, SessionSnapshot } from "../../client.js";
+import type { SessionFrame, SessionCompactionMarker, SessionExtensionSlots, SessionPendingPrompts, SessionSnapshot } from "../../client.js";
 import type { ClientReadOptions } from "../client-boundary.js";
 import type { CommandSettlement, SqliteOwner } from "../contracts.js";
 import type { ObservedActivity } from "../session-status.js";
@@ -8,6 +8,8 @@ import { type AdmissionIdentity, type StoredSessionRow } from "./session-store.j
  * and retry text can contain private provider bodies, not safe diagnostics.
  */
 export declare function diagnosticsByWorkId(path: readonly StoredSessionRow[]): ReadonlyMap<string, string>;
+/** Native entry order, not the marker's display horizon; requires no SQL read. */
+export declare function compactionEntrySequence(marker: SessionCompactionMarker): number;
 /** Same payload projection as the FIFO page, selected independently of that page's bounds. */
 export declare function readLatestPendingPrompt(owner: SqliteOwner, sessionId: string, identity?: AdmissionIdentity): SessionPendingPrompts["prompts"][number] | null;
 /**

package/dist/internal/woodstock/client-projection.js

@@ -150,6 +150,14 @@ function projectTerminal(row, { commandIds, diagnostics, cancellations }) {
         : undefined;
     return Object.freeze(meta === undefined ? terminal : { ...terminal, meta });
 }
+const compactionEntrySequences = new WeakMap();
+/** Native entry order, not the marker's display horizon; requires no SQL read. */
+export function compactionEntrySequence(marker) {
+    const sequence = compactionEntrySequences.get(marker);
+    if (sequence === undefined)
+        throw unavailable("Session compaction entry position is unavailable");
+    return sequence;
+}
 /**
  * Full-history client projections show every durable entry, including what a
  * compaction summarized away. Each compaction entry in `rows` contributes one
@@ -170,14 +178,16 @@ function compactionMarkersIn(owner, lineage, rows) {
             lineageEntrySequence(owner, lineage, entry.head);
         if (kept === undefined)
             throw unavailable("Session compaction horizon is unavailable");
-        markers.push(Object.freeze({
+        const marker = Object.freeze({
             id: row.id,
             sequence: kept,
             at: row.timestamp,
             tokensBefore: entry.data.tokensBefore,
             tokensAfter: entry.data.tokensAfter ?? null,
             trigger: entry.data.reason ?? null,
-        }));
+        });
+        compactionEntrySequences.set(marker, row.sequence);
+        markers.push(marker);
     }
     return Object.freeze(markers);
 }

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

@@ -12,7 +12,8 @@ import { type ClientReplayPage } from "./client-projection.js";
 import { type LiveRetryEvent } from "./session-entry.js";
 import { type CompactionNoticeInput, type AcceptedCommand, type EnqueueAcceptedWork, type AppendCompactionInput, type PreparedSessionRun, type RunContract, type RecordAcceptedCancellation, type SessionQueueHead, type StoredSessionRow } from "./session-store.js";
 export * from "./extension-store.js";
-export { readLatestPendingPrompt } from "./client-projection.js";
+export { decodeWoodstockCursor } from "./cursor.js";
+export { compactionEntrySequence, readLatestPendingPrompt, } from "./client-projection.js";
 export { createFleetDirectoryStore, createFleetDelegationStore, } from "./fleet-store.js";
 export * from "./session-attention.js";
 export * from "./work-senders.js";
@@ -101,6 +102,11 @@ export declare function readSettlementContent(owner: SqliteOwner, input: Readonl
     sessionId: string;
     commandFactId: string;
 }>): Effect.Effect<string, ShiitakeError>;
+/** Last non-empty text in an extension stretch, including its initiating work. */
+export declare function readSettlementStretchContent(owner: SqliteOwner, input: Readonly<{
+    sessionId: string;
+    commandFactId: string;
+}>): Effect.Effect<string, ShiitakeError>;
 /**
  * The host metadata that settles with one accepted command: the
  * cancellation's when a host-attributed cancel ended it, otherwise the

package/dist/internal/woodstock/index.js

@@ -12,7 +12,8 @@ import { appendSessionEntry, appendCompactionTransitionOwned, appendCompactionNo
 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 { decodeWoodstockCursor } from "./cursor.js";
+export { compactionEntrySequence, readLatestPendingPrompt, } from "./client-projection.js";
 export { createFleetDirectoryStore, createFleetDelegationStore, } from "./fleet-store.js";
 export * from "./session-attention.js";
 export * from "./work-senders.js";
@@ -155,8 +156,49 @@ export function readSettlementContent(owner, input) {
         const entries = readSessionEntriesForWork(owner, input.sessionId, admission.entry.workId);
         for (let index = entries.length - 1; index >= 0; index -= 1) {
             const entry = entries[index]?.entry;
-            if (entry?.kind === "message" && entry.value.role === "assistant")
-                return assistantText(entry.value);
+            if (entry?.kind === "message" && entry.value.role === "assistant") {
+                const text = assistantText(entry.value);
+                if (text !== "")
+                    return text;
+            }
+        }
+        return "";
+    });
+}
+/** Last non-empty text in an extension stretch, including its initiating work. */
+export function readSettlementStretchContent(owner, input) {
+    return Effect.gen(function* () {
+        let commandFactId = input.commandFactId;
+        while (commandFactId !== undefined) {
+            const content = yield* readSettlementContent(owner, {
+                sessionId: input.sessionId,
+                commandFactId,
+            });
+            if (content !== "")
+                return content;
+            const currentId = commandFactId;
+            commandFactId = yield* storeEffect(() => {
+                const admission = readSessionCommandAdmission(owner, input.sessionId, currentId);
+                if (admission === undefined)
+                    throw rejected("Accepted Session command is unavailable");
+                if (readExtensionAdmissionOrigin(owner, input.sessionId, currentId, admission.entry.workId) === null)
+                    return undefined;
+                let row = readSessionEntryById(owner, currentId);
+                if (row === undefined)
+                    throw rejected("Accepted Session command entry is unavailable");
+                // Walk only this command's ancestry. Strictly decreasing sequences
+                // bound the walk and exclude sibling branches or newer queued work.
+                while (row.parentId !== null) {
+                    const parent = readSessionEntryById(owner, row.parentId);
+                    if (parent?.sessionId !== input.sessionId ||
+                        parent.sequence >= row.sequence)
+                        throw rejected("Session stretch ancestry is unavailable");
+                    if (parent.entry.kind === "command")
+                        return parent.id;
+                    row = parent;
+                }
+                return undefined;
+            });
         }
         return "";
     });
@@ -533,10 +575,11 @@ export function recordLiveRetryEvent(owner, accepted, event, turn) {
             sameIdentity(current.event.run, event.run));
     }).pipe(Effect.mapError(listenerFailure));
 }
-const listenerFailure = () => ({
+const listenerFailure = (cause) => ({
     _tag: "MuleError",
     phase: "listener",
     message: "Woodstock could not record the Mule event",
+    cause,
 });
 /**
  * Open the one scoped listener that projects Mule's exact event stream into

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

@@ -32,6 +32,8 @@ export declare function openToolProgress(owner: SqliteOwner, accepted: AcceptedC
 export declare function readProcessProgress(owner: SqliteOwner, sessionId: string): SessionProgress | null;
 /** Read progress only when it belongs to the current durable work head. */
 export declare function readProcessProgressForWork(owner: SqliteOwner, sessionId: string, workId: string): SessionProgress | null;
+/** Read a phase fact without flattening another Session's private text tails. */
+export declare function hasProcessTextForWork(owner: SqliteOwner, sessionId: string, workId: string): boolean;
 export type ProgressMessageStart = Extract<MuleEvent, {
     type: "message_start";
 }>;

package/dist/internal/woodstock/progress.js

@@ -189,6 +189,11 @@ export function readProcessProgressForWork(owner, sessionId, workId) {
     const current = progressFor(owner).get(sessionId);
     return snapshot(current?.workId === workId ? current.value : null);
 }
+/** Read a phase fact without flattening another Session's private text tails. */
+export function hasProcessTextForWork(owner, sessionId, workId) {
+    const current = progressByOwner.get(owner)?.get(sessionId);
+    return current?.workId === workId && (current.value?.text.length ?? 0) > 0;
+}
 /**
  * Keep live model progress in the current process only.
  *

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

@@ -447,7 +447,7 @@ export declare function decodeStoredSessionEntry(value: string): Result.Result<{
     readonly run: MuleIdentity;
     readonly turn: MuleIdentity;
     readonly message: MuleIdentity;
-    readonly role: "user" | "assistant" | "system" | "toolResult";
+    readonly role: "toolResult" | "system" | "user" | "assistant";
     readonly workId: string;
 } | {
     readonly kind: "message";
@@ -533,8 +533,8 @@ export declare function decodeStoredSessionEntry(value: string): Result.Result<{
     readonly workId: string;
     readonly result: "failed";
     readonly trigger: "manual" | "threshold" | "overflow";
-    readonly diagnostic?: string;
     readonly usage?: Usage;
+    readonly diagnostic?: string;
 } | {
     readonly kind: "compaction_notice";
     readonly workId: string;