@sagmans/dsh-tui 0.6.0 → 0.8.0

package/lib/surface/session-view.js

@@ -0,0 +1,215 @@
+import { createSessionHistory } from "../agent/history.js";
+import { createToolPresenter } from "../agent/present.js";
+import { FoldCursor, ViewGeneration, replayIfCurrent } from "../fold-cursor.js";
+import { hintKeys } from "../input/actions.js";
+import { TranscriptModel } from "../transcript.js";
+import { WorkFold } from "../work.js";
+/** What the back hint names when the reader has unbound the key it would advertise. */
+const BACK_HINT_FALLBACK = 'ctrl+b';
+/** What the reader presses to leave a view they did not open. */
+export const backHint = (map) => `${hintKeys(map, 'surface.back') || BACK_HINT_FALLBACK} returns to this session`;
+/**
+ * The transcript on screen: what is drawn, and never which agent is driven.
+ *
+ * The model, the work fold and the identity they are folded for are one owner
+ * because the reader's view is one thing: a durable event reaches both folds,
+ * and a switch of identity resets both. What this owner drives — the agent, its
+ * staged cutoff, and the terminal it paints — stays with the surface that
+ * composes it, so a reader can watch a child's conversation without moving the
+ * commands, the approvals, or the bell.
+ */
+export function createSessionView(ctx, ports) {
+    /**
+     * The agent scope the tool presenter resolves against.
+     *
+     * Tools are registered in the scoped world the session's preset mounts, so a
+     * card can only read its tool's own render intent while this names that
+     * agent. It follows whatever session the transcript is folding, because a
+     * child on screen reads through the child's scope, not the parent's.
+     */
+    let presentScope;
+    const model = new TranscriptModel(createToolPresenter(ctx, () => presentScope));
+    const work = new WorkFold();
+    /** The session the transcript is showing, which can be one of its children. */
+    let viewedSession = ports.initialSession;
+    /** Only the newest transcript switch may finish an asynchronous stored-log read. */
+    const viewGeneration = new ViewGeneration();
+    /**
+     * The fold's place in the viewed session's durable sequence.
+     *
+     * A resumed session is folded while its agent's loop is already live, so the
+     * same event can reach the surface twice: once on the stream and once from the
+     * log the fold is reading. The sequence number every durable event carries is
+     * what tells the two apart.
+     */
+    const foldCursor = new FoldCursor();
+    /** Every transcript reset revokes reads started for the previous view. */
+    const reset = () => {
+        const current = viewGeneration.begin();
+        model.reset();
+        work.reset();
+        return current;
+    };
+    /** Feed one durable event to everything that folds it. */
+    const applyEvent = (event) => {
+        model.apply(event);
+        work.apply(event);
+    };
+    /**
+     * Fold one durable event into the view, unless a staged cursor hides it.
+     *
+     * Undo never deletes, so the log keeps the hidden suffix; this filter is the
+     * one place the transcript and the log disagree about where the session ends.
+     */
+    const applyDurable = (session, event) => {
+        const cut = ports.stagedCutoff();
+        if (cut !== undefined && session === ports.drivenSession() && typeof event.seq === 'number' && event.seq >= cut)
+            return;
+        if (foldCursor.accept(session, event))
+            applyEvent(event);
+    };
+    /**
+     * Replay a stored session so a resumed run opens on the conversation the
+     * reader left, not on an empty screen: the durable log is the transcript.
+     */
+    /**
+     * Fold one session's history into the transcript.
+     *
+     * A live session answers from memory, which is the only source that includes
+     * events not yet flushed and the only one that works for a child that has not
+     * materialized; a session this process is not running falls back to storage.
+     */
+    const foldHistory = async (id, through, current = () => true) => {
+        // Resolved before the fold so every card reads its tool through the scope
+        // that actually registered it; a stored session nobody runs has none.
+        presentScope = ports.agentScope(id);
+        // Every fold starts a cleared transcript, so a session already known to the
+        // cursor is read from its first event rather than from where it left off.
+        foldCursor.reset();
+        const inMemory = ports.liveEvents(id);
+        if (inMemory !== undefined) {
+            const events = through === undefined ? inMemory : inMemory.slice(0, through);
+            for (const event of events)
+                applyDurable(id, event);
+            return events.length;
+        }
+        // Only a live session can be staged: undo acts on the agent this terminal
+        // drives, and a stored log has no cursor to hide a suffix from.
+        const history = createSessionHistory(ctx);
+        if (history === undefined)
+            return 0;
+        return replayIfCurrent(() => history.read(id), current, event => applyDurable(id, event));
+    };
+    const replayHistory = async (id) => {
+        try {
+            const folded = await foldHistory(id);
+            if (folded > 0)
+                model.notice(`replayed ${folded} events from the stored log`);
+        }
+        catch (error) {
+            model.notice(`could not replay this session: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    /**
+     * Show another session in the transcript without leaving this one.
+     *
+     * A delegation is an ordinary session, so the reader can read what a child is
+     * doing rather than only that it exists; the agent this terminal drives does
+     * not change, which keeps commands, approvals, and the bell where they were.
+     */
+    const showSession = async (id) => {
+        const previous = viewedSession;
+        const current = reset();
+        viewedSession = id;
+        try {
+            await foldHistory(id, undefined, current);
+        }
+        catch (error) {
+            if (!current())
+                return;
+            model.notice(`could not read that session: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!current())
+            return;
+        const driven = ports.drivenSession();
+        const returned = id === driven && previous !== driven;
+        model.marker(returned ? 'back to the session this terminal drives' : `viewing ${id}`);
+        ports.render();
+    };
+    const showAgentSession = async () => {
+        await showSession(ports.drivenSession());
+    };
+    /** Every event of a session, from memory when this process runs it. */
+    const sessionEvents = async (id) => {
+        const inMemory = ports.liveEvents(id);
+        if (inMemory !== undefined)
+            return inMemory;
+        const history = createSessionHistory(ctx);
+        return history === undefined ? [] : history.read(id);
+    };
+    /**
+     * Fold one durable event of the session on screen, and repaint.
+     *
+     * The caller filters on the identity it drives first: the surface state —
+     * activity, timer, title, bell, job board — belongs to that agent even while
+     * a child is on screen.
+     */
+    const observe = (id, event) => {
+        if (id !== viewedSession)
+            return;
+        presentScope = ports.agentScope(id);
+        applyDurable(id, event);
+        ports.render();
+    };
+    /**
+     * The listeners that follow the viewed agent's own stream.
+     *
+     * The transcript belongs to the session on screen, while status, the bell,
+     * and the queue stay with the agent this terminal drives. A live delta or a
+     * failure folded into the wrong model would print one session's words as
+     * another's, and the durable copy that follows would never correct it.
+     */
+    const agentListeners = () => [
+        ctx.on('agent/error', payload => {
+            if (payload.agent.id !== viewedSession)
+                return;
+            model.reportError(payload.error);
+            ports.render();
+        }),
+        ctx.on('agent/assistant-stream', payload => {
+            if (payload.agent.id !== viewedSession)
+                return;
+            if (payload.frame.type !== 'chunk')
+                return;
+            model.applyStreamChunk(payload.frame.chunk);
+            ports.render();
+        }),
+    ];
+    return {
+        viewed: () => viewedSession,
+        viewingChild: () => viewedSession !== ports.drivenSession(),
+        notice: message => model.notice(message),
+        marker: text => model.marker(text),
+        reportError: error => model.reportError(error),
+        model,
+        workState: () => work.state(),
+        sessionEvents,
+        setPresentScope: scope => {
+            presentScope = scope;
+        },
+        clearPresentScope: () => {
+            presentScope = undefined;
+        },
+        reset,
+        setViewed: id => {
+            viewedSession = id;
+        },
+        fold: foldHistory,
+        replay: replayHistory,
+        show: showSession,
+        showDriven: showAgentSession,
+        observe,
+        agentListeners,
+    };
+}
+//# sourceMappingURL=session-view.js.map

package/lib/surface/session-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-view.js","sourceRoot":"","sources":["../../src/surface/session-view.ts"],"names":[],"mappings":"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"}

package/lib/surface/staged-turns.d.ts

@@ -0,0 +1,81 @@
+import { SessionId } from '@deepseek-ai/dsh-session';
+import type { ForkEvent } from '../agent/fork.ts';
+import type { ForkInheritance, TuiAgent } from '../agent/host.ts';
+import { type UndoState } from '../agent/undo.ts';
+/**
+ * The staged-turn policy: the cursor over the live log, and the prompts parked
+ * behind it.
+ *
+ * Undo never deletes a prompt. It moves a cursor over the closed turns, folds
+ * the transcript back to a cut that stops before the hidden ones, and hands the
+ * reader's own words back to the composer. A send while turns are hidden cannot
+ * continue in place — the model would then see the prompts the reader undid —
+ * so it branches from the visible prefix instead.
+ */
+/**
+ * What the staged-turn owner needs from the surface that composes it.
+ *
+ * Every read is taken at call time: the session, the draft, the queue and the
+ * agent in service all move while an undo settles an interrupt, and a captured
+ * copy would park the reader's draft in a session they already left.
+ */
+export interface StagedTurnPorts {
+    /** Whether the transcript shows a child, where neither command belongs. */
+    readonly viewingChild: () => boolean;
+    /** The session this terminal drives, which owns the only log a cursor counts. */
+    readonly activeSession: () => SessionId;
+    /** Every event of a session, which is what the turns are derived from. */
+    readonly sessionEvents: (id: SessionId) => Promise<readonly ForkEvent[]>;
+    /** Drop the folded transcript, so the next fold starts from nothing. */
+    readonly resetTranscript: () => void;
+    /** Fold the transcript to an event index, or over the whole log at the tip. */
+    readonly foldTranscript: (id: SessionId, cutoff: number | undefined) => Promise<unknown>;
+    /** The agent in service, which a plain send submits to and a staged one replaces. */
+    readonly drivingAgent: () => TuiAgent | undefined;
+    /**
+     * The lifecycle owner's one replacement boundary: stop the agent in service
+     * and let go of everything that projected it.
+     */
+    readonly disposeOutgoing: () => Promise<void>;
+    /** Start the agent for a session, which is what a replacement joins. */
+    readonly openSession: (id: SessionId, resume: boolean, fork?: ForkInheritance) => Promise<TuiAgent>;
+    /** The prompts queued on the driven agent, which an interrupt would drop. */
+    readonly queuedPrompts: () => readonly string[];
+    /** Whether a bank exists to park into, which is how the reader's words survive. */
+    readonly canPark: () => boolean;
+    /** Park one prompt, in the order the queue replay needs. */
+    readonly parkPrompt: (text: string) => Promise<void>;
+    /** Whether a turn is open, which the cursor must not cut through. */
+    readonly turnRunning: () => boolean;
+    /** The text the bar holds, which is the reader's draft until this owner writes it. */
+    readonly draft: () => string;
+    /** Put text back in the bar. */
+    readonly writeDraft: (text: string) => void;
+    readonly notice: (message: string) => void;
+    readonly render: () => void;
+}
+/** The staged cursor and the operations the composer routes its commands to. */
+export interface StagedTurns {
+    /** Event index the transcript must not fold past while turns are hidden. */
+    readonly stagedCutoff: () => number | undefined;
+    /** The cursor over this session's closed turns. */
+    readonly cursor: () => UndoState;
+    /** Whether an undo is settling an interrupt, so a second press cannot race it. */
+    readonly pending: () => boolean;
+    /**
+     * The cursor at the tip of the session just opened.
+     *
+     * A cursor counts the turns of one log, so a session that opens takes a fresh
+     * one; the cut goes with it, because a hidden count means nothing on a
+     * transcript nothing has been folded from.
+     */
+    readonly sessionOpened: (id: SessionId) => void;
+    readonly undo: () => void;
+    readonly redo: () => void;
+    /** Send the reader's prompt, branching first when turns are hidden. */
+    readonly send: (text: string) => Promise<void>;
+    /** The turn/end the cursor may be waiting on, which the composer's listener hears. */
+    readonly turnSettled: () => void;
+}
+export declare function createStagedTurns(ports: StagedTurnPorts): StagedTurns;
+//# sourceMappingURL=staged-turns.d.ts.map

package/lib/surface/staged-turns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-turns.d.ts","sourceRoot":"","sources":["../../src/surface/staged-turns.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,EASL,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAA;AAEzB;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,OAAO,CAAA;IACpC,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,MAAM,SAAS,CAAA;IACvC,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAA;IACxE,wEAAwE;IACxE,QAAQ,CAAC,eAAe,EAAE,MAAM,IAAI,CAAA;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACxF,qFAAqF;IACrF,QAAQ,CAAC,YAAY,EAAE,MAAM,QAAQ,GAAG,SAAS,CAAA;IACjD;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IACnG,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,MAAM,SAAS,MAAM,EAAE,CAAA;IAC/C,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAA;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAA;IACnC,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAA;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3C,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAA;CAC5B;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC/C,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,SAAS,CAAA;IAChC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAA;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAA;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAA;IACzB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9C,sFAAsF;IACtF,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAA;CACjC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,WAAW,CA6MrE"}

package/lib/surface/staged-turns.js

@@ -0,0 +1,206 @@
+import { randomUUID } from 'node:crypto';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { hiddenTail, NO_UNDO, redoStep, resetUndo, turnsOf, UNDO_TURN_SETTLE_MS, undoStep, } from "../agent/undo.js";
+export function createStagedTurns(ports) {
+    /** The staged cursor for the session this terminal drives. */
+    let cursor = NO_UNDO;
+    /** Event index the transcript must not fold past while turns are hidden. */
+    let cut;
+    /** Whether an undo is settling an interrupt, so a second press cannot race it. */
+    let pending = false;
+    /** Resolver for the turn/end an undo is waiting on, set only while waiting. */
+    let settled;
+    /** The closed turns of the session this terminal drives, newest last. */
+    const currentTurns = async () => turnsOf(await ports.sessionEvents(ports.activeSession()));
+    /** Fold the transcript through the staged cut, or the whole log at the tip. */
+    const redrawStaged = async () => {
+        ports.resetTranscript();
+        await ports.foldTranscript(ports.activeSession(), cut);
+    };
+    /** Park queued prompts one per bank entry, newest first so popping replays queue order. */
+    const parkQueued = async (queued) => {
+        for (const text of [...queued].reverse())
+            await ports.parkPrompt(text);
+    };
+    /** Wait for the interrupted turn to close, bounded so undo can give up honestly. */
+    const waitForTurnEnd = (timeoutMs) => new Promise(resolve => {
+        const timer = setTimeout(() => {
+            settled = undefined;
+            resolve(false);
+        }, timeoutMs);
+        settled = () => {
+            clearTimeout(timer);
+            settled = undefined;
+            resolve(true);
+        };
+    });
+    /**
+     * Stop the running turn and empty the inbox so the cut lands on a closed
+     * turn/end; queued prompts are parked first because cancelling drops them.
+     *
+     * Returns undefined when the reader's words cannot be kept: a queue with no
+     * bank to park it in, or a turn that will not close. Both leave the cursor
+     * untouched, so the transcript keeps showing what the model actually saw; a
+     * number is how many queued prompts were parked before the turn was stopped.
+     */
+    const settleForUndo = async () => {
+        const queued = ports.queuedPrompts();
+        if (!ports.turnRunning() && queued.length === 0)
+            return 0;
+        if (queued.length > 0 && !ports.canPark()) {
+            ports.notice('queued prompts have no stash to park in; undo cancelled');
+            ports.render();
+            return undefined;
+        }
+        ports.drivingAgent()?.interrupt();
+        if (queued.length > 0)
+            await parkQueued(queued);
+        if (ports.turnRunning() && !(await waitForTurnEnd(UNDO_TURN_SETTLE_MS))) {
+            ports.notice('could not stop the turn; undo cancelled');
+            ports.render();
+            return undefined;
+        }
+        return queued.length;
+    };
+    const runUndoCommand = () => {
+        if (pending)
+            return;
+        pending = true;
+        void (async () => {
+            if (ports.viewingChild()) {
+                ports.notice('undo works on the session this terminal drives · ctrl+b comes back');
+                ports.render();
+                return;
+            }
+            const turns = await currentTurns();
+            if (cursor.hidden >= turns.length && !ports.turnRunning()) {
+                ports.notice('nothing to undo');
+                ports.render();
+                return;
+            }
+            const draft = ports.draft();
+            // Text this state itself restored is not the reader's draft, so undoing
+            // again must not park it and end up with two copies.
+            const holdsDraft = draft !== '' && draft !== cursor.lastRestored;
+            if (holdsDraft && !ports.canPark()) {
+                ports.notice('the bar holds a draft and there is no stash to park it in; undo cancelled');
+                ports.render();
+                return;
+            }
+            const parked = await settleForUndo();
+            if (parked === undefined)
+                return;
+            const settledTurns = await currentTurns();
+            const next = undoStep(cursor, settledTurns);
+            if (next === undefined) {
+                ports.notice('nothing to undo');
+                ports.render();
+                return;
+            }
+            if (holdsDraft) {
+                await ports.parkPrompt(draft);
+                ports.notice('the draft in the bar was parked in the stash');
+            }
+            cursor = next;
+            cut = hiddenTail(next, settledTurns)?.seedCount;
+            await redrawStaged();
+            ports.writeDraft(next.lastRestored);
+            // The parking count rides the undo notice: a notice of its own would be
+            // replaced before the frame could show it.
+            const parkedNote = parked === 0 ? '' : ` · ${parked} queued prompt${parked === 1 ? '' : 's'} parked in the stash`;
+            ports.notice(`undo · ${next.hidden} prompt${next.hidden === 1 ? '' : 's'} hidden${parkedNote} · prefix r redo`);
+            ports.render();
+        })()
+            .catch((error) => {
+            ports.notice(`undo failed: ${error instanceof Error ? error.message : String(error)}`);
+            ports.render();
+        })
+            .finally(() => {
+            pending = false;
+        });
+    };
+    const runRedoCommand = () => {
+        void (async () => {
+            if (ports.viewingChild()) {
+                ports.notice('redo works on the session this terminal drives · ctrl+b comes back');
+                ports.render();
+                return;
+            }
+            const turns = await currentTurns();
+            const before = ports.draft();
+            const restored = cursor.lastRestored;
+            const next = redoStep(cursor, turns);
+            if (next === undefined) {
+                ports.notice('nothing to redo');
+                ports.render();
+                return;
+            }
+            cursor = next;
+            cut = hiddenTail(next, turns)?.seedCount;
+            await redrawStaged();
+            // A composer the reader edited is theirs; only text this state wrote is replaced.
+            if (before === restored)
+                ports.writeDraft(next.lastRestored);
+            ports.notice(next.hidden === 0
+                ? 'redo · back at the newest prompt'
+                : `redo · ${next.hidden} prompt${next.hidden === 1 ? '' : 's'} hidden`);
+            ports.render();
+        })().catch((error) => {
+            ports.notice(`redo failed: ${error instanceof Error ? error.message : String(error)}`);
+            ports.render();
+        });
+    };
+    /**
+     * Send the reader's prompt, branching first when the transcript is staged.
+     *
+     * Context is derived from the log, so a send while turns are hidden has to
+     * continue in a child seeded with the visible prefix; submitting in place would
+     * show the model the prompts the reader undid. Every send passes through here so
+     * the branch has one commit point, not one per caller.
+     */
+    const commitStagedSend = async (text) => {
+        try {
+            const previous = ports.drivingAgent();
+            if (previous === undefined) {
+                ports.notice('the agent is still starting; try again in a moment');
+                ports.render();
+                return;
+            }
+            if (cursor.hidden === 0) {
+                previous.submit(text);
+                return;
+            }
+            const source = ports.activeSession();
+            const events = await ports.sessionEvents(source);
+            const turns = turnsOf(events);
+            const tail = hiddenTail(cursor, turns);
+            const seed = tail === undefined ? [] : events.slice(0, tail.seedCount);
+            const childId = SessionId(`tui-session-${randomUUID()}`);
+            await ports.disposeOutgoing();
+            const opened = await ports.openSession(childId, false, seed.length === 0 ? undefined : { from: source, events: seed });
+            ports.notice(`continuing in a new branch · ${source} keeps the undone turns`);
+            opened.submit(text);
+        }
+        catch (error) {
+            ports.notice(`could not send: ${error instanceof Error ? error.message : String(error)}`);
+            ports.render();
+        }
+    };
+    return {
+        stagedCutoff: () => cut,
+        cursor: () => cursor,
+        pending: () => pending,
+        sessionOpened: id => {
+            cursor = resetUndo(id);
+            cut = undefined;
+        },
+        undo: runUndoCommand,
+        redo: runRedoCommand,
+        send: commitStagedSend,
+        // The turn/end the cursor may be waiting on, which only the composer hears.
+        turnSettled: () => {
+            settled?.();
+        },
+    };
+}
+//# sourceMappingURL=staged-turns.js.map

package/lib/surface/staged-turns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-turns.js","sourceRoot":"","sources":["../../src/surface/staged-turns.ts"],"names":[],"mappings":"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"}

package/lib/surface/terminal-lifecycle.d.ts

@@ -0,0 +1,76 @@
+import { ProcessTerminal } from '@earendil-works/pi-tui';
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import { type HerdrReporter } from '../herdr/reporter.ts';
+import { WarningSafeTui } from '../terminal/warning-screen.ts';
+import type { FrameRow } from '../ui/frame.ts';
+/**
+ * What the terminal's owner needs from the surface that composes it.
+ *
+ * Every read is taken at call time: a handoff, an exit, or a copied selection
+ * happens against whatever this terminal drives when it happens, and a captured
+ * copy would name the session the surface happened to open first.
+ */
+export interface TerminalLifecyclePorts {
+    /** A frame that could not be drawn reaches the transcript through here. */
+    readonly reportFrameError: (error: unknown) => void;
+    /** Say something the screen cannot: a failed handoff is one. */
+    readonly notice: (message: string) => void;
+    /** The rows the last frame drew, which is what a copied selection is read through. */
+    readonly copyRows: () => readonly FrameRow[];
+    /** The session this terminal drives, which is what an exit hint can offer back. */
+    readonly activeSession: () => SessionId;
+    /** Whether a session was really opened; a run that opened none has nothing to point at. */
+    readonly sessionOpened: () => boolean;
+    /** Whether a turn is open, which the title names once the screen comes back. */
+    readonly turnRunning: () => boolean;
+    /** Stop the clock that repaints a running turn; an exit does not wait for it. */
+    readonly stopClock: () => void;
+    /** Leave the process with the status the caller owns. */
+    readonly exit: (code: number) => void;
+    /** The draft the bar holds, which is what the reader's own editor is handed. */
+    readonly draftText: () => string;
+    /** Whether a question borrowed the bar, so an edited draft must wait behind it. */
+    readonly draftBorrowed: () => boolean;
+    /** Park an edited draft behind a borrowed bar instead of answering the question. */
+    readonly holdDraft: (text: string) => void;
+    /** Put an edited draft back into the bar. */
+    readonly writeDraft: (text: string) => void;
+}
+/** The handles and operations the composing surface routes to this owner. */
+export interface TerminalLifecycle {
+    readonly terminal: ProcessTerminal;
+    readonly tui: WarningSafeTui;
+    /** The pane's agent row; the surface reports through it and this owner releases it. */
+    readonly herdr: HerdrReporter;
+    /**
+     * The surface's teardowns, in the order they were registered.
+     *
+     * The array is handed out rather than wrapped in a register function because
+     * the composing surface registers most of them, several by spreading a
+     * listener list: one array is what keeps a spread and a single push in the
+     * same order, and the unwind below reverses that one order.
+     */
+    readonly disposers: Array<() => void>;
+    /** Write to the tty, but only while this surface owns it. */
+    readonly writeTerminal: (text: string) => void;
+    readonly handedOver: () => boolean;
+    readonly disposed: () => boolean;
+    readonly exited: () => boolean;
+    readonly requestExit: (code: number, reason?: string) => void;
+    /** Hand the draft to the reader's own editor and take back what it saved. */
+    readonly editDraft: () => void;
+    /** Register the supervisor signals that end this surface the way a quit does. */
+    readonly signalShutdown: () => () => void;
+}
+/**
+ * The terminal's lifetime: the screen this surface owns, the way out of it, and
+ * the child that borrows it.
+ *
+ * Ownership is the whole subject: the alternate screen, the hooks that put the
+ * shell back, and the exit are one mechanism, and a second writer would not
+ * know that the reader's own editor holds the tty. The composer keeps the
+ * widgets; this owner keeps every byte written to the terminal.
+ */
+export declare function createTerminalLifecycle(ctx: Context, ports: TerminalLifecyclePorts): TerminalLifecycle;
+//# sourceMappingURL=terminal-lifecycle.d.ts.map

package/lib/surface/terminal-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-lifecycle.d.ts","sourceRoot":"","sources":["../../src/surface/terminal-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAO9E,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,QAAQ,CAAC,gBAAgB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IACnD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,SAAS,QAAQ,EAAE,CAAA;IAC5C,mFAAmF;IACnF,QAAQ,CAAC,aAAa,EAAE,MAAM,SAAS,CAAA;IACvC,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,EAAE,MAAM,OAAO,CAAA;IACrC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAA;IACnC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAA;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,MAAM,CAAA;IAChC,mFAAmF;IACnF,QAAQ,CAAC,aAAa,EAAE,MAAM,OAAO,CAAA;IACrC,oFAAoF;IACpF,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5C;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAA;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAA;IACrC,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAA;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;IAC9B,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7D,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAA;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,cAAc,EAAE,MAAM,MAAM,IAAI,CAAA;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,sBAAsB,GAAG,iBAAiB,CAuMtG"}