@sagmans/dsh-tui 0.6.0 → 0.7.0

package/lib/surface/background-work.d.ts

@@ -0,0 +1,49 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { TuiAgent } from '../agent/host.ts';
+import { type JobSummary } from '../jobs.ts';
+import { SubagentRoster } from '../subagents.ts';
+/**
+ * What the background-work owner needs from the surface that composes it.
+ *
+ * The agent and the session on screen are read at call time: a command, a
+ * listener, or the job watch each has to follow whatever this terminal drives
+ * now, and a captured identity would follow the one it drove at construction.
+ */
+export interface BackgroundWorkPorts {
+    readonly drivingAgent: () => TuiAgent | undefined;
+    readonly activeSession: () => SessionId;
+    readonly notice: (text: string) => void;
+    readonly marker: (text: string) => void;
+    readonly render: () => void;
+    /** Show the session a child runs in; the viewed-session owner performs it. */
+    readonly navigate: (id: string) => void;
+}
+/** The commands and live reads the composing surface routes to this owner. */
+export interface BackgroundWork {
+    readonly roster: SubagentRoster;
+    readonly jobs: () => readonly JobSummary[];
+    readonly refresh: () => void;
+    /** Fold the parent's durable catalog, which is where a child's task name lives. */
+    readonly acceptCatalog: (info: unknown) => void;
+    readonly resetRoster: () => void;
+    readonly runSubagentsCommand: (argument: string) => void;
+    readonly runJobsCommand: (argument: string) => void;
+    /**
+     * Register the two subagent lifecycle listeners.
+     *
+     * They are returned rather than pushed here so the composition root keeps one
+     * ordered list of teardowns, which is unwound in reverse registration order.
+     */
+    readonly subagentListeners: () => readonly (() => void)[];
+    readonly watchJobs: () => () => void;
+}
+/**
+ * The work that runs beside the conversation: background jobs and child agents.
+ *
+ * Neither is folded from the transcript. A job board is live state owned by a
+ * service, and a child's name arrives on its own event, so this owner keeps
+ * those reads and the two commands that show them in one place.
+ */
+export declare function createBackgroundWork(ctx: Context, ports: BackgroundWorkPorts): BackgroundWork;
+//# sourceMappingURL=background-work.d.ts.map

package/lib/surface/background-work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-work.d.ts","sourceRoot":"","sources":["../../src/surface/background-work.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAChD,OAAO,EAML,KAAK,UAAU,EAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,cAAc,EAAgF,MAAM,iBAAiB,CAAA;AAO9H;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,QAAQ,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,SAAS,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAA;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,SAAS,UAAU,EAAE,CAAA;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAA;IAChC,QAAQ,CAAC,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACxD,QAAQ,CAAC,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,SAAS,CAAC,MAAM,IAAI,CAAC,EAAE,CAAA;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,MAAM,IAAI,CAAA;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,mBAAmB,GAAG,cAAc,CAwI7F"}

package/lib/surface/background-work.js

@@ -0,0 +1,146 @@
+import { JOB_READ_LINES, createJobDirectory, describeJobs, parseJobsArgument, } from "../jobs.js";
+import { SubagentRoster, createSubagentControl, describeSubagents, parseSubagentsArgument, resolveRun } from "../subagents.js";
+/** Decode a lifecycle payload the roster only takes when it carries the shape it expects. */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+/**
+ * The work that runs beside the conversation: background jobs and child agents.
+ *
+ * Neither is folded from the transcript. A job board is live state owned by a
+ * service, and a child's name arrives on its own event, so this owner keeps
+ * those reads and the two commands that show them in one place.
+ */
+export function createBackgroundWork(ctx, ports) {
+    const jobDirectory = createJobDirectory(ctx);
+    let jobs = [];
+    const roster = new SubagentRoster();
+    const subagentControl = createSubagentControl(ctx);
+    /** Re-read the job board; it is live state, so nothing else can fold it. */
+    const refresh = () => {
+        const agent = ports.drivingAgent();
+        jobs = agent === undefined || jobDirectory === undefined ? [] : jobDirectory.list(agent.agent);
+        ports.render();
+    };
+    /**
+     * List or stop the delegations this session started.
+     *
+     * A child runs in the same process as an ordinary agent, so a stop is the
+     * cancel a reader's Ctrl+C sends to the parent; nothing here reaches into the
+     * child's own session, which keeps its own transcript either way.
+     */
+    const runSubagentsCommand = (argument) => {
+        const command = parseSubagentsArgument(argument);
+        switch (command.kind) {
+            case 'list':
+                ports.notice(describeSubagents(roster.list(), Date.now()));
+                ports.render();
+                return;
+            case 'open': {
+                const run = resolveRun(roster.list(), command.id);
+                if (run === undefined) {
+                    ports.notice(`${command.id}: no single child matches; /subagents lists them`);
+                    ports.render();
+                    return;
+                }
+                ports.navigate(run.id);
+                return;
+            }
+            case 'kill': {
+                const stopped = subagentControl?.stop(command.id) ?? false;
+                ports.notice(stopped
+                    ? `${command.id}: stop requested`
+                    : `${command.id}: no live child with that id`);
+                ports.render();
+                return;
+            }
+            case 'invalid':
+                ports.notice(`/subagents: ${command.reason}`);
+                ports.render();
+                return;
+        }
+    };
+    const runJobsCommand = (argument) => {
+        const agent = ports.drivingAgent();
+        if (jobDirectory === undefined) {
+            ports.notice('this profile has no job registry, so there is nothing to list');
+            ports.render();
+            return;
+        }
+        if (agent === undefined) {
+            ports.notice('the agent is still starting; try again in a moment');
+            ports.render();
+            return;
+        }
+        const command = parseJobsArgument(argument);
+        switch (command.kind) {
+            case 'list':
+                refresh();
+                ports.notice(describeJobs(jobs, Date.now()));
+                ports.render();
+                return;
+            case 'read': {
+                const result = jobDirectory.read(agent.agent, command.id);
+                const text = result?.text.trim() ?? '';
+                ports.notice(text === ''
+                    ? `${command.id}: no output yet`
+                    : `${command.id} output\n${text.split('\n').slice(-JOB_READ_LINES).join('\n')}`);
+                refresh();
+                return;
+            }
+            case 'kill': {
+                const outcome = jobDirectory.kill(agent.agent, command.id);
+                ports.notice(outcome === undefined
+                    ? `${command.id}: no such job`
+                    : outcome === 'requested' ? `${command.id}: stop requested` : `${command.id} had already finished`);
+                refresh();
+                return;
+            }
+            case 'invalid':
+                ports.notice(`/jobs: ${command.reason}`);
+                ports.render();
+                return;
+        }
+    };
+    /**
+     * Subagent lifecycle arrives as a service event rather than a session event,
+     * so it is decoration in the transcript: the parent's durable catalog
+     * carries the child's task. The name is cast so a rename in the
+     * harness cannot break compilation of this surface.
+     */
+    const listenFor = (name, handler) => ctx.on(name, handler);
+    return {
+        roster,
+        jobs: () => jobs,
+        refresh,
+        acceptCatalog: info => roster.catalog(info),
+        resetRoster: () => roster.reset(),
+        runSubagentsCommand,
+        runJobsCommand,
+        subagentListeners: () => [
+            listenFor('subagent/start', info => {
+                roster.start(info);
+                const record = asRecord(info);
+                const provider = typeof record?.provider === 'string' ? record.provider : 'subagent';
+                const id = typeof record?.id === 'string' ? record.id : '';
+                ports.marker(`subagent ${provider} started${id === '' ? '' : ` · ${id}`}`);
+                ports.render();
+            }),
+            listenFor('subagent/end', info => {
+                roster.end(info);
+                const record = asRecord(info);
+                const provider = typeof record?.provider === 'string' ? record.provider : 'subagent';
+                const stop = typeof record?.stopReason === 'string' ? record.stopReason : undefined;
+                ports.marker(`subagent ${provider} finished${stop === undefined ? '' : ` · ${stop}`}`);
+                ports.render();
+            }),
+        ],
+        // The board is live state: watch it directly rather than folding events.
+        watchJobs: () => jobDirectory?.watch(owner => {
+            if (owner !== undefined && owner.id !== ports.activeSession())
+                return;
+            refresh();
+        }) ?? (() => { }),
+    };
+}
+//# sourceMappingURL=background-work.js.map

package/lib/surface/background-work.js.map

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

package/lib/surface/commands.d.ts

@@ -0,0 +1,80 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { PresetRoster } from '../agent/presets.ts';
+import type { RegisteredCommand } from '../input/completion.ts';
+import { type Submission } from '../input/submission.ts';
+import type { PromptStash } from '../stash.ts';
+import type { StatusFacts } from '../ui/status.ts';
+import type { Appearance } from './appearance.ts';
+import type { BackgroundWork } from './background-work.ts';
+import type { ModalInput } from './modal-input.ts';
+import type { ModelChoice } from './model-choice.ts';
+import type { PresetChoice, PresetLaunch } from './preset-choice.ts';
+import type { PromptMemory } from './prompt-memory.ts';
+import type { SessionLifecycle } from './session-lifecycle.ts';
+import type { SessionView } from './session-view.ts';
+import type { StagedTurns } from './staged-turns.ts';
+import type { TerminalLifecycle } from './terminal-lifecycle.ts';
+/**
+ * What the command plane needs from the surface that composes it.
+ *
+ * Each owner arrives whole, because this module is the one place that knows
+ * which of their operations a typed line, a chord, or the launch maps onto; the
+ * reads it takes of them are live, so a command typed after a session switch
+ * answers for the session now on screen. The launch facts and the mode roster
+ * are the two things no owner holds, and the notice and render sinks are what a
+ * refusal and a repaint are printed through.
+ */
+export interface CommandsPorts {
+    /** The launch this run was started for, and the mode its own flag named. */
+    readonly launch: PresetLaunch;
+    readonly preset: string | undefined;
+    /** The roster that can say whether a stored session's mode still exists. */
+    readonly presetRoster: PresetRoster | undefined;
+    /** A composition row that is missing, printed before the screen is taken. */
+    readonly missingOptional: () => string | undefined;
+    readonly session: SessionLifecycle;
+    readonly transcript: SessionView;
+    readonly route: ModelChoice;
+    readonly modes: PresetChoice;
+    readonly work: BackgroundWork;
+    readonly staged: StagedTurns;
+    readonly memory: PromptMemory;
+    readonly appearance: Appearance;
+    /** The terminal this surface owns, which is where a copy is written. */
+    readonly terminal: TerminalLifecycle;
+    /** The one modal interaction at a time, which lends its keyboard to a list. */
+    readonly modals: ModalInput;
+    readonly statusFacts: () => StatusFacts;
+    /** The bank the parked-draft commands read, late-bound behind the picker it needs. */
+    readonly stash: () => PromptStash | undefined;
+    readonly render: () => void;
+}
+/** The operations the composing surface routes back into the command plane. */
+export interface Commands {
+    /** Carry out one classified line, wherever it was asked for. */
+    readonly runSubmission: (submission: Submission) => void;
+    /**
+     * The commands one agent can run, or undefined when no registry answers.
+     *
+     * A scoped read rather than the registry itself: the registry stays with this
+     * owner, and completion only ever needs the names it offers.
+     */
+    readonly registeredCommands: (agent: Agent) => readonly RegisteredCommand[] | undefined;
+    /**
+     * Take the screen, then open the session this run was launched for.
+     *
+     * The launch belongs to this owner because the resume it may ask is the same
+     * question the resume command asks, answered by the same list.
+     */
+    readonly start: () => Promise<void>;
+}
+/**
+ * The router over everything the reader and the launcher can ask for.
+ *
+ * The registry is read from the composition rather than taken as a port: it is
+ * scoped to the agent in service, so its listing, lookup and dispatch all have
+ * to follow whichever agent the surface is driving now.
+ */
+export declare function createCommands(ctx: Context, ports: CommandsPorts): Commands;
+//# sourceMappingURL=commands.d.ts.map

package/lib/surface/commands.d.ts.map

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

package/lib/surface/commands.js

@@ -0,0 +1,364 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { defaultExportFile, transcriptToText } from "../export.js";
+import { chordKeysLine, surfaceKeysLine } from "../input/keymap.js";
+import { LOCAL_COMMANDS } from "../input/submission.js";
+import { KEYMAP_LAYERS, keymapLayer } from "../keys-command.js";
+import { clipboardSequence } from "../terminal/clipboard.js";
+import { windowTitle } from "../terminal/title.js";
+import { formatTokens } from "../tokens.js";
+import { KeymapPicker } from "../ui/keymap-picker.js";
+import { describeTodos, planSelectedActive, planToggleLine, readPlanState } from "../work.js";
+import { createSessionPicker } from "./session-picker.js";
+/**
+ * The router over everything the reader and the launcher can ask for.
+ *
+ * The registry is read from the composition rather than taken as a port: it is
+ * scoped to the agent in service, so its listing, lookup and dispatch all have
+ * to follow whichever agent the surface is driving now.
+ */
+export function createCommands(ctx, ports) {
+    const registry = () => ctx.get('commands');
+    // The copy is the one write that must land even while a child owns the tty:
+    // the reader asked for the last answer, not for a title, and a handoff that
+    // swallowed it would leave the clipboard silently empty.
+    const writeTty = (text) => ports.terminal.terminal.write(text);
+    /**
+     * Open the key map over the surface.
+     *
+     * Nothing here is a pick: a row names an action and the keys reaching it, so
+     * the id the list settles on is thrown away. What the reader came for is the
+     * list itself, and the filter that narrows it.
+     */
+    const openKeyMap = (layer) => {
+        void ports.modals.openPicker(new KeymapPicker(ports.appearance.keymap, layer), undefined, 'popup');
+    };
+    /**
+     * Write what the reader can see to a file.
+     *
+     * The base's `/export` downloads the log through the browser, which a
+     * terminal has no way to do, so this dumps the transcript the reader is
+     * looking at — the thing worth pasting into a message.
+     */
+    const runExportCommand = (argument) => {
+        const path = resolve(argument === '' ? defaultExportFile(String(ports.session.activeSession())) : argument);
+        try {
+            writeFileSync(path, transcriptToText(ports.transcript.model.entries()), 'utf8');
+            ports.transcript.notice(`transcript written to ${path}`);
+        }
+        catch (error) {
+            ports.transcript.notice(`could not write ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        ports.render();
+    };
+    /** Show the todo list the agent has been keeping. */
+    const runTodoCommand = () => {
+        ports.transcript.notice(describeTodos(ports.transcript.workState().todos));
+        ports.render();
+    };
+    /**
+     * Put the last answer on the reader's clipboard.
+     *
+     * The clipboard belongs to the terminal, so this asks it through OSC 52 —
+     * which is also the only route that works over SSH.
+     */
+    const runCopyCommand = () => {
+        const last = [...ports.transcript.model.entries()].reverse().find(entry => entry.kind === 'assistant');
+        if (last === undefined || last.kind !== 'assistant') {
+            ports.transcript.notice('nothing to copy yet');
+            ports.render();
+            return;
+        }
+        writeTty(clipboardSequence(last.text));
+        ports.transcript.notice(`copied ${last.text.length} characters through the terminal`);
+        ports.render();
+    };
+    const helpText = () => {
+        const current = ports.session.drivingAgent()?.agent;
+        const registered = current === undefined || registry() === undefined
+            ? []
+            : registry()?.list(current).map(command => `/${command.name}`) ?? [];
+        const commands = registered.length === 0 ? 'none registered yet' : registered.join(' ');
+        return `commands: ${commands} · surface: ${LOCAL_COMMANDS.join(' ')} · keys: ${surfaceKeysLine(ports.appearance.keymap())} · ${chordKeysLine(ports.appearance.keymap())}`;
+    };
+    /**
+     * Whether the agent this surface is driving is in plan mode.
+     *
+     * The dock's fold is the fallback, for a composition without the plan
+     * package: with the controller present its answer is the agent's own state
+     * rather than a replay of the events this surface happened to see.
+     */
+    const planState = () => {
+        const current = ports.session.drivingAgent()?.agent;
+        if (current === undefined)
+            return undefined;
+        const presets = ctx.get('agentPresets');
+        return readPlanState({
+            direct: name => ctx.get(name),
+            forAgent: (target, name) => presets?.serviceFor(target, name),
+        }, current);
+    };
+    const planActive = () => planSelectedActive(planState(), ports.transcript.workState().planMode);
+    const runCommand = (name, line) => {
+        const current = ports.session.drivingAgent();
+        const commands = registry();
+        if (current === undefined) {
+            ports.transcript.notice('the agent is still starting; try again in a moment');
+            ports.render();
+            return;
+        }
+        if (commands === undefined || commands.find(current.agent, name) === undefined) {
+            ports.transcript.notice(`unknown command: /${name} — ${helpText()}`);
+            ports.render();
+            return;
+        }
+        const controller = new AbortController();
+        void commands.execute(current.agent, line, [], controller.signal).then(execution => {
+            const result = execution?.result;
+            if (result === undefined)
+                return;
+            ports.transcript.notice(result.kind === 'error' ? `/${name} failed: ${result.text ?? 'no detail'}` : `/${name} ${result.text ?? 'done'}`);
+            ports.render();
+        }).catch((error) => {
+            ports.transcript.notice(`/${name} failed: ${error instanceof Error ? error.message : String(error)}`);
+            ports.render();
+        });
+    };
+    /**
+     * Carry out one classified line, wherever it was asked for.
+     *
+     * A chord asks for the same things the command line does, so both arrive
+     * here: a chord cannot behave differently from the command it stands for.
+     */
+    const runSubmission = (submission) => {
+        switch (submission.kind) {
+            case 'empty':
+                return;
+            case 'quit':
+                ports.terminal.requestExit(0);
+                return;
+            case 'model':
+                ports.route.runModelCommand(submission.argument);
+                return;
+            case 'preset':
+                ports.modes.runPresetCommand(submission.argument);
+                return;
+            case 'jobs':
+                ports.work.runJobsCommand(submission.argument);
+                return;
+            case 'rename':
+                ports.session.runRenameCommand(submission.title);
+                return;
+            case 'export':
+                runExportCommand(submission.path);
+                return;
+            case 'subagents':
+                ports.work.runSubagentsCommand(submission.argument);
+                return;
+            case 'fork':
+                ports.session.runForkCommand(submission.title);
+                return;
+            case 'new':
+                ports.session.runNewCommand(submission.title);
+                return;
+            case 'reload':
+                ports.session.runReloadCommand();
+                return;
+            case 'todo':
+                runTodoCommand();
+                return;
+            case 'theme':
+                ports.appearance.runThemeCommand(submission.argument);
+                return;
+            case 'keys': {
+                const layer = submission.argument === '' ? undefined : keymapLayer(submission.argument);
+                // A layer that does not exist is not a filter that matches nothing: the
+                // reader asked for something by name, so the answer names the names.
+                if (submission.argument !== '' && layer === undefined) {
+                    ports.transcript.notice(`unknown layer "${submission.argument}" · ${KEYMAP_LAYERS.join(' ')}`);
+                    ports.render();
+                    return;
+                }
+                openKeyMap(layer);
+                return;
+            }
+            case 'copy':
+                runCopyCommand();
+                return;
+            case 'history':
+                ports.memory.runHistoryCommand(submission.argument);
+                return;
+            case 'stash':
+                // Submitting a command consumes the line it was typed on, so this path
+                // can only carry a draft it was given; parking the bar's own draft is
+                // what the chord is for.
+                if (submission.argument.trim() === '')
+                    ports.transcript.notice('usage: /stash <draft>, or ctrl+x then s to park the editor');
+                else
+                    void ports.stash()?.stashEditor(submission.argument);
+                return;
+            case 'stash-draft':
+                void ports.stash()?.stashEditor();
+                return;
+            case 'stash-pop':
+                void ports.stash()?.pop(submission.selector);
+                return;
+            case 'stash-apply':
+                void ports.stash()?.apply(submission.selector);
+                return;
+            case 'stash-list':
+                void ports.stash()?.list(String(ports.session.activeSession()));
+                return;
+            case 'stash-drop':
+                void ports.stash()?.drop(submission.selector);
+                return;
+            case 'stash-clear':
+                void ports.stash()?.clear();
+                return;
+            case 'editor':
+                ports.terminal.editDraft();
+                return;
+            case 'status': {
+                const facts = ports.statusFacts();
+                const context = facts.contextTokens === undefined
+                    ? undefined
+                    : `context ${formatTokens(facts.contextTokens)}${facts.contextWindow === undefined ? '' : `/${formatTokens(facts.contextWindow)}`}`;
+                ports.transcript.notice([
+                    `session ${ports.session.activeSession()}`,
+                    ports.transcript.viewingChild() ? undefined : `viewing ${ports.transcript.viewed()}`,
+                    facts.model === undefined
+                        ? undefined
+                        : `model ${facts.provider === undefined ? '' : `${facts.provider}/`}${facts.model}${facts.effort === undefined ? '' : ` (${facts.effort})`}`,
+                    facts.agentPreset === undefined ? undefined : `mode ${facts.agentPreset}`,
+                    facts.preset === undefined ? undefined : `permissions ${facts.preset}`,
+                    context,
+                    facts.uncachedInputTokens === undefined && facts.outputTokens === undefined
+                        ? undefined
+                        : `tokens in ${formatTokens(facts.uncachedInputTokens ?? 0)} out ${formatTokens(facts.outputTokens ?? 0)}`,
+                    `cwd ${facts.cwd}`,
+                ].filter(part => part !== undefined).join(' · '));
+                ports.render();
+                return;
+            }
+            case 'clear':
+                ports.transcript.reset();
+                ports.render();
+                return;
+            case 'undo':
+                ports.staged.undo();
+                return;
+            case 'redo':
+                ports.staged.redo();
+                return;
+            case 'help':
+                ports.transcript.notice(helpText());
+                ports.render();
+                return;
+            case 'resume':
+                void sessionPicker.chooseSession().then(picked => picked === undefined ? undefined : ports.session.switchSession(picked)).catch((error) => {
+                    ports.transcript.notice(`could not resume: ${error instanceof Error ? error.message : String(error)}`);
+                    ports.render();
+                });
+                return;
+            // Plan mode is a command the harness owns, so the chord asks the host for
+            // the state and names the command for the other one: one key, both ways.
+            case 'plan':
+                runCommand('plan', planToggleLine(planActive()));
+                return;
+            case 'command':
+                runCommand(submission.name, submission.line);
+                return;
+            case 'prompt': {
+                const driven = ports.session.drivingAgent();
+                if (driven === undefined) {
+                    ports.transcript.notice('the agent is still starting; try again in a moment');
+                    ports.render();
+                    return;
+                }
+                // While a turn is running the human is steering it, not opening another.
+                if (ports.session.turnRunning())
+                    driven.steer(submission.text);
+                else {
+                    ports.route.adoptDefault();
+                    void ports.staged.send(submission.text);
+                }
+                return;
+            }
+        }
+    };
+    /**
+     * Where a bare `--resume` gets its list, and the ports it drives.
+     *
+     * The keyboard is taken through a port rather than here: how a picker holds
+     * it, and how long it may, is the modal owner's business.
+     */
+    const sessionPicker = createSessionPicker(ctx, {
+        keymap: ports.appearance.keymap,
+        notice: ports.transcript.notice,
+        render: ports.render,
+        // A stored session's own mode can only disagree with one this run named, and
+        // only a roster can say whether the name it uses still exists.
+        validateStoredPreset: async (id) => {
+            if (ports.preset === undefined || ports.presetRoster === undefined)
+                return;
+            await ports.modes.presetFor(SessionId(id), true, undefined);
+        },
+        openPicker: (picker, vet) => ports.modals.openPicker(picker, vet),
+    });
+    /**
+     * Open the session this run was launched for.
+     *
+     * A bare `--resume` asks a question only the reader can answer, so the
+     * picker runs before anything is created: the agent is then opened on the
+     * chosen session rather than swapped afterwards, which would leave the first
+     * one's turn half-started.
+     */
+    const boot = async () => {
+        if (!ports.launch.resumePicker) {
+            await ports.session.openAgent(ports.launch.sessionId, ports.launch.resume);
+            return;
+        }
+        const picked = await sessionPicker.chooseSession();
+        if (picked === undefined) {
+            ports.terminal.requestExit(0);
+            return;
+        }
+        await ports.session.openAgent(picked, true);
+    };
+    /**
+     * Take the screen, then open the session this run was launched for.
+     *
+     * A mode named on the command line is resolved FIRST: the alt screen swallows
+     * the launcher's own error output, so a mode this roster does not offer has to
+     * be answered while the shell still owns the terminal.
+     */
+    const start = async () => {
+        // A composition row that is missing is a degradation the reader has to be
+        // told about, and this is the last moment before the alt screen closes over
+        // the shell's own output.
+        const missing = ports.missingOptional();
+        if (missing !== undefined)
+            ports.transcript.notice(missing);
+        // A named mode that disagrees with the one this session recorded is refused
+        // here as well as at the open, because the alternate screen closes over
+        // whatever was painted on it: the reader would see the failure, not the
+        // reason.
+        await ports.modes.validateLaunch(ports.launch);
+        ports.terminal.tui.start();
+        ports.terminal.writeTerminal(windowTitle(process.cwd(), 'ready'));
+        // Claiming the pane's agent row does not wait for a session: the pane is
+        // already on screen and already idle, and a session may still be chosen.
+        ports.terminal.herdr.publish();
+        // A refused settings edit is only visible now that the surface owns the
+        // screen; whatever the scope found before this point prints here instead.
+        ports.appearance.openNotices(message => ports.transcript.notice(message));
+        await boot();
+    };
+    return {
+        runSubmission,
+        registeredCommands: agent => registry()?.list(agent),
+        start,
+    };
+}
+//# sourceMappingURL=commands.js.map