@sagmans/dsh-tui 0.3.0 → 0.4.0

package/lib/index.js

@@ -4,6 +4,7 @@ import { resolve } from 'node:path';
 import { ProcessTerminal, ScrollView, VStack, isKeyRelease, matchesKey } from '@earendil-works/pi-tui';
 import { startAgent } from "./agent/host.js";
 import { PICKER_LIMIT, createSessionHistory, presetOfStoredSession, readSessionTitle, } from "./agent/history.js";
+import { createPromptHistory } from "./agent/prompt-history.js";
 import { createPresetRoster, parsePresetArgument } from "./agent/presets.js";
 import { createToolPresenter } from "./agent/present.js";
 import { forkPoint } from "./agent/fork.js";
@@ -15,6 +16,7 @@ import { SubagentRoster, createSubagentControl, describeSubagents, parseSubagent
 import { describeMissingOptional, describeMissingRequired, probeComposition } from "./compat/probe.js";
 import { ApprovalGate, QuestionGate, toGateQuestions } from "./gates.js";
 import { createCompletionProvider } from "./input/completion.js";
+import { ghostSuffix } from "./input/ghost.js";
 import { LOCAL_COMMANDS, classifySubmission } from "./input/submission.js";
 import { createDeferredNotice } from "./settings-notice.js";
 import { ChordReader, DEFAULT_PREFIX_KEYS, DEFAULT_PREFIX_WINDOW_S, chordBindings, chordKeysLine, installKeybindings, surfaceKeysLine, } from "./input/keymap.js";
@@ -26,6 +28,8 @@ import { WarningSafeTui } from "./terminal/warning-screen.js";
 import { BELL, shouldRingBell } from "./terminal/bell.js";
 import { clipboardSequence } from "./terminal/clipboard.js";
 import { CLEAR_TITLE, windowTitle } from "./terminal/title.js";
+import { sessionStartReason } from "./herdr/state.js";
+import { createHerdrReporter } from "./herdr/reporter.js";
 import { defaultExportFile, transcriptToText } from "./export.js";
 import { createTheme, forwardEditorTheme, forwardMarkdownTheme } from "./theme.js";
 import { detectColourMode } from "./theme-capability.js";
@@ -33,19 +37,23 @@ import { defaultSettings, readScope, settingsProblemMessage, toOverrides, TUI_SE
 import { pendingPrompts } from "./queue.js";
 import { renderThemeTable } from "./theme-command.js";
 import { KEYMAP_LAYERS, keymapLayer, renderKeymap } from "./keys-command.js";
+import { resetSequence } from "./theme-tokens.js";
 import { SessionId } from '@deepseek-ai/dsh-session';
 import { formatTokens } from "./tokens.js";
 import { TranscriptModel } from "./transcript.js";
 import { WorkFold, describeTodos, planSelectedActive, planToggleLine, readPlanState } from "./work.js";
 import { WorkDock } from "./ui/dock.js";
 import { GateInputBar } from "./ui/gate-input.js";
+import { HistoryPicker } from "./ui/history-picker.js";
 import { PromptBar } from "./ui/prompt.js";
 import { MarkdownRenderer } from "./ui/markdown.js";
 import { createMermaidTransform } from "./ui/mermaid.js";
 import { EffortPicker, ModelPicker, PROVIDER_DEFAULT_EFFORT_ID, PresetPicker, SessionPicker, effortChoices, } from "./ui/picker.js";
 import { QueueBar } from "./ui/queue.js";
-import { StatusBar } from "./ui/status.js";
+import { shortPath, StatusBar } from "./ui/status.js";
 import { DEFAULT_VIEW_STATE, TranscriptView } from "./ui/view.js";
+import { PromptStash } from "./stash.js";
+import { confirmedClear, StashConfirmPicker, StashPicker } from "./ui/stash-picker.js";
 export const name = 'tui';
 /**
  * Services the surface cannot run without.
@@ -65,6 +73,8 @@ const backHint = (map) => `${hintKeys(map, 'surface.back') || BACK_HINT_FALLBACK
 const TITLE_CONCURRENCY = 4;
 /** How often the running-state clock repaints while a turn is open. */
 const STATUS_TICK_MS = 1000;
+/** Reverse video for the cell the cursor occupies, so a ghost keeps the cursor visible. */
+const GHOST_CURSOR_PREFIX = '\u001b[7m';
 function asRecord(value) {
     return typeof value === 'object' && value !== null ? value : undefined;
 }
@@ -162,6 +172,10 @@ export function apply(ctx, config) {
     let prefixWindowMs = DEFAULT_PREFIX_WINDOW_S * MS_PER_SECOND;
     /** Every action's keys in force; the settings document owns it and a press reads it live. */
     let keymap = defaultKeymap();
+    /** Whether prompts are recorded and offered, and the cap on how many; the settings document owns all three. */
+    let historyEnabled = defaultSettings().history.enabled;
+    let historyGhost = defaultSettings().history.ghost;
+    let historyMaxEntries = defaultSettings().history.maxEntries;
     /**
      * The chord between a prefix and the action that follows it.
      *
@@ -187,6 +201,9 @@ export function apply(ctx, config) {
         // Installed where the library reads it, so a remap lands on the next press
         // rather than at the next restart.
         installKeybindings(keymap);
+        historyEnabled = section.history.enabled;
+        historyGhost = section.history.ghost;
+        historyMaxEntries = section.history.maxEntries;
         // A chord armed under the keymap the reader just replaced is not their chord.
         keyChord.disarm();
     };
@@ -219,7 +236,10 @@ export function apply(ctx, config) {
             scope = settingsCtx.settings.register(TUI_SETTINGS_NAMESPACE, TuiSettingsSchema);
         }
         catch (error) {
-            settingsNotice.post(settingsProblemMessage(error));
+            // Nothing registered means nothing to read, so the reader's switch cannot
+            // be confirmed: recording stays off rather than falling back to on.
+            historyEnabled = false;
+            settingsNotice.post(settingsProblemMessage(error) + ' · prompt history stays off until the section parses');
             return;
         }
         readSection = () => readScope(scope, message => settingsNotice.post(message));
@@ -235,6 +255,33 @@ export function apply(ctx, config) {
      */
     let presentScope;
     const model = new TranscriptModel(createToolPresenter(ctx, () => presentScope));
+    /**
+     * The reader's prompt history: global across projects, recorded from every
+     * submitted line, and offered back as they type. Built before the bar so its
+     * first load cannot race the first suggestion.
+     */
+    const promptHistory = createPromptHistory({
+        cap: () => historyMaxEntries,
+        warn: message => {
+            model.notice(message);
+            tui.requestRender();
+        },
+    });
+    /**
+     * The dimmed completion drawn from recorded prompts.
+     *
+     * Colour is the affordance: with styling off the suggestion would be
+     * unreadable text the reader could still accept, which is worse than none.
+     * The cursor cell is also reversed so the cursor stays visible on the ghost.
+     */
+    const ghostBrush = {
+        enabled: () => historyEnabled && historyGhost && theme.color && theme.visible('editor.ghost'),
+        suggestion: input => ghostSuffix({ entries: promptHistory.entries(), ...input }),
+        paint: (text, cell) => {
+            const styled = theme.style('editor.ghost', text);
+            return cell === 'cursor' ? GHOST_CURSOR_PREFIX + styled + resetSequence() : styled;
+        },
+    };
     const work = new WorkFold();
     const modelSwitch = new ModelSwitch();
     const agentPresets = createPresetRoster(ctx);
@@ -285,7 +332,7 @@ export function apply(ctx, config) {
     // send the library submits on by default. A settings document read after this
     // point installs over it, which is why the bar reads the map per press.
     installKeybindings(keymap);
-    const editor = new GateInputBar(tui, theme.editor, () => keymap);
+    const editor = new GateInputBar(tui, theme.editor, () => keymap, ghostBrush);
     // Answers are written in the reader's own editor, which is why a question
     // borrows the bar instead of drawing a second one beside it.
     const promptBar = new PromptBar(editor);
@@ -306,6 +353,9 @@ export function apply(ctx, config) {
         jobs = agent === undefined || jobDirectory === undefined ? [] : jobDirectory.list(agent.agent);
         tui.requestRender();
     };
+    // The bank is built once the picker exists to answer for it, so the status
+    // source is late-bound: the footer must not read a half-constructed stash.
+    let stash;
     const statusFacts = createStatusFacts(ctx, {
         sessionId: () => activeSession,
         activity: () => ({ running: turnOpen, startedAt: turnStartedAt }),
@@ -316,6 +366,7 @@ export function apply(ctx, config) {
         // a hint stored with the transcript would keep naming the key of the day it
         // was written, and the reader may remap it with the row already on screen.
         back: () => (viewedSession === activeSession ? undefined : backHint(keymap)),
+        stash: () => stash?.entryCount,
     });
     const statusBar = new StatusBar(statusFacts, theme);
     const dock = new WorkDock(() => work.state(), theme, () => jobs, () => roster.list());
@@ -330,11 +381,28 @@ export function apply(ctx, config) {
     disposers.push(() => clearInterval(statusTicker));
     // A window that outlived the surface would repaint a screen that is gone.
     disposers.push(() => keyChord.disarm());
+    // A containing Herdr is told what this pane is doing; away from one the
+    // reporter is inert, so the surface never depends on being multiplexed.
+    const herdr = createHerdrReporter();
+    // Kept out of the disposal list on purpose: the row is handed back before
+    // this stops guarding it, so a host that leaves during the release still
+    // releases synchronously.
+    const unregisterExit = herdr.registerExitRelease();
     restore.add(() => tui.stop());
     ctx.effect(() => () => {
+        // The pane stops being an agent before the process that claimed it unwinds:
+        // a release that ran after the reports were unregistered would race them,
+        // and one that never ran would leave a row that reads as a live agent. The
+        // reports already on the wire are settled first, because Herdr ignores a
+        // release for a pane nothing has claimed yet — the report that followed it
+        // would otherwise claim the row back. The promise is returned so a host that
+        // waits for teardown waits for the row too, and the exit listener outlives
+        // the wait, so one that does not still hands the row back synchronously.
+        const released = herdr.release().catch(() => undefined);
         restore.restore();
         for (const dispose of disposers.reverse())
             dispose();
+        return released.finally(unregisterExit);
     });
     tui.setLayoutRoot(new VStack([
         {
@@ -359,26 +427,37 @@ export function apply(ctx, config) {
             return;
         exited = true;
         clearInterval(statusTicker);
-        // Hand the window label back before the screen does, so a shell that sets
-        // its own title can take over cleanly.
+        // The screen goes back at once, so leaving feels like leaving; the row goes
+        // back behind it. Reports already on the wire are settled first, because
+        // Herdr ignores the release of a pane nothing has claimed yet — the report
+        // that followed it would otherwise claim the row back during shutdown.
         terminal.write(CLEAR_TITLE);
         restore.restore();
-        // Everything below is written after the release: the alternate screen closes
-        // over whatever was painted on it, and a failure nobody can read is not a
-        // failure that was reported.
-        if (reason !== undefined)
-            terminal.write(`\ndsh-tui: ${reason}\n`);
-        // The hint is computed here rather than read from the context because only
-        // the surface knows which session it is leaving: a fork or a switch moves it.
-        // A run that opened nothing has nothing to offer back: the identity it was
-        // launched with names no log, so pointing at it would send the reader to a
-        // conversation that does not exist.
-        if (sessionOpened)
-            terminal.write(`\n${resumeHint(String(activeSession), PROFILE_NAME)}\n`);
-        appExit(code);
+        void herdr
+            .release()
+            // Nobody is left to report a release that failed on the way out, and a
+            // row that could not be cleared is not a reason to keep the process.
+            .catch(() => undefined)
+            .finally(() => {
+            // Everything below is written after the release: a failure nobody can
+            // read is not a failure that was reported.
+            if (reason !== undefined)
+                terminal.write(`\ndsh-tui: ${reason}\n`);
+            // The hint is computed here rather than read from the context because
+            // only the surface knows which session it is leaving: a fork or a
+            // switch moves it. A run that opened nothing has nothing to offer back:
+            // the identity it was launched with names no log, so pointing at it
+            // would send the reader to a conversation that does not exist.
+            if (sessionOpened)
+                terminal.write(`\n${resumeHint(String(activeSession), PROFILE_NAME)}\n`);
+            appExit(code);
+        });
     };
     const openGate = (next) => {
         pending = next;
+        // The card's own title names the decision, which is what a reader glancing
+        // at a wall of panes needs in order to know which one to open.
+        herdr.block(next.gate.card().title);
         // A gate owns the keyboard: the editor must not collect the decision keys.
         editor.disableSubmit = true;
         tui.setFocus(null);
@@ -390,6 +469,7 @@ export function apply(ctx, config) {
     };
     const closeGate = () => {
         pending = undefined;
+        herdr.unblock();
         editor.disableSubmit = false;
         // The question is answered or skipped, so the reader gets their prompt back
         // in the bar they left it in.
@@ -400,7 +480,7 @@ export function apply(ctx, config) {
     /**
      * What each key the surface answers itself does; false hands the press back.
      *
-     * Keyed by the table's own ids, so a key added to {@link SURFACE_KEYS}
+     * Keyed by the table's own ids, so a key added to {@link SURFACE_ACTIONS}
      * without a handler here fails to compile rather than doing nothing.
      */
     const surfaceActions = {
@@ -423,6 +503,10 @@ export function apply(ctx, config) {
             void openEffortPicker();
             return true;
         },
+        history: () => {
+            void openHistoryPicker();
+            return true;
+        },
         back: () => {
             if (viewedSession !== activeSession)
                 void showAgentSession();
@@ -564,6 +648,7 @@ export function apply(ctx, config) {
     const settlePicker = (id) => {
         const settle = pendingPicker?.settle;
         pendingPicker = undefined;
+        herdr.unblock();
         editor.disableSubmit = false;
         tui.setFocus(editor);
         settle?.(id);
@@ -590,10 +675,39 @@ export function apply(ctx, config) {
     /** Take the keyboard for a picker and answer with the id it settled on. */
     const openPicker = (picker, vet) => new Promise(resolve => {
         pendingPicker = { picker, settle: resolve, vet };
+        // A picker owns the keyboard exactly as a gate does: nothing moves until
+        // the reader chooses, so it is the same kind of wait.
+        herdr.block(picker.card().title);
         editor.disableSubmit = true;
         tui.setFocus(null);
         tui.requestRender();
     });
+    /**
+     * Reverse search over recorded prompts, seeded with whatever is in the bar.
+     *
+     * A pick replaces the draft; a cancel leaves it exactly as it was, because the
+     * list was opened to look rather than to lose what is already typed.
+     */
+    const openHistoryPicker = async () => {
+        if (!historyEnabled) {
+            model.notice('prompt history is disabled in ' + TUI_SETTINGS_NAMESPACE + ' settings');
+            tui.requestRender();
+            return;
+        }
+        if (promptHistory.entries().length === 0) {
+            const blocked = promptHistory.blockedReason();
+            model.notice(blocked === undefined ? 'no prompt history yet' : 'prompt history is unavailable: ' + blocked);
+            tui.requestRender();
+            return;
+        }
+        // The expanded text is what the reader wrote; a large paste sits in the bar
+        // as a marker, and seeding with it would filter out the prompt it came from.
+        const picked = await openPicker(new HistoryPicker(() => promptHistory.entries(), editor.getExpandedText(), () => keymap));
+        if (picked === undefined)
+            return;
+        editor.setText(picked);
+        tui.requestRender();
+    };
     /** The roster as the picker paints it, refreshed when the picker opens. */
     let presetRows = [];
     /** Choose the mode a session that has not started yet will run. */
@@ -603,6 +717,28 @@ export function apply(ctx, config) {
         presetRows = await agentPresets.list();
         return await openPicker(new PresetPicker(() => presetRows, () => currentId, () => keymap));
     };
+    /**
+     * The prompt bank for this working directory.
+     *
+     * The surface owns the editor, the picker, and the notices, so the bank is
+     * handed the few things it needs to reach them and nothing else: the commands
+     * stay free of terminal state and are exercised without one in the tests.
+     */
+    const stashCwdLabel = shortPath(process.cwd(), process.env.HOME);
+    stash = new PromptStash({
+        getEditorText: () => editor.getExpandedText(),
+        setEditorText: text => {
+            editor.setText(text);
+            tui.requestRender();
+        },
+        // A question answers in this editor, so a draft written into a borrowed bar
+        // would become somebody's answer instead of a parked prompt.
+        editorIsAvailable: () => !promptBar.isBorrowed(),
+        notice: message => model.notice(message),
+        pick: (entries, label) => openPicker(new StashPicker(entries, label, () => keymap)),
+        confirm: async (count) => confirmedClear(await openPicker(new StashConfirmPicker(count, () => keymap))),
+        render: () => tui.requestRender(),
+    }, { cwd: process.cwd() });
     /** Title the listed sessions without making the reader wait for the slowest log. */
     const loadTitles = async (history, sessions, titles) => {
         const queue = [...sessions];
@@ -812,6 +948,13 @@ export function apply(ctx, config) {
         activeSession = id;
         viewedSession = id;
         agent = handle;
+        // The agent's own id is reported rather than the requested one: a resume can
+        // be answered by the session the log actually holds.
+        herdr.session({
+            id: String(handle.sessionId),
+            cwd: process.cwd(),
+            reason: sessionStartReason({ forked: fork !== undefined, resumed: resume }),
+        });
         // A session with no history to fold still has to present its first live
         // card through the right scope, so the scope is set before any event can.
         presentScope = handle.agent;
@@ -1433,6 +1576,47 @@ export function apply(ctx, config) {
             ...(facts.effort === undefined ? {} : { reasoningEffort: facts.effort }),
         });
     };
+    /** Show where history is kept, or forget it; the file is global to this machine. */
+    const runHistoryCommand = (argument) => {
+        // The line that asked for this is recorded before the command runs, but that
+        // write rides the store's queue; waiting for it lets the count describe the
+        // file the reader has, not the state before their own line landed.
+        void promptHistory.flush().then(() => {
+            if (argument === '') {
+                const count = promptHistory.entries().length;
+                const blocked = promptHistory.blockedReason();
+                model.notice([
+                    count + (count === 1 ? ' prompt recorded' : ' prompts recorded'),
+                    promptHistory.path(),
+                    blocked === undefined ? undefined : 'writes disabled: ' + blocked,
+                ].filter(part => part !== undefined).join(' · '));
+                tui.requestRender();
+                return;
+            }
+            if (argument !== 'clear') {
+                model.notice('usage: /history shows where history is kept · /history clear forgets every prompt');
+                tui.requestRender();
+                return;
+            }
+            // A refused write cannot remove anything, so saying "forgot 0 prompts"
+            // would describe a successful clear the file never had.
+            const blocked = promptHistory.blockedReason();
+            if (blocked !== undefined) {
+                model.notice('prompt history is unavailable: ' + blocked);
+                tui.requestRender();
+                return;
+            }
+            return promptHistory.clear().then(removed => {
+                model.notice('forgot ' + removed + (removed === 1 ? ' prompt' : ' prompts'));
+                tui.requestRender();
+            });
+        }).catch(error => {
+            // The store keeps what the file still holds, so the reader is told the
+            // clear failed rather than being shown a count that never landed.
+            model.notice('could not clear prompt history: ' + (error instanceof Error ? error.message : String(error)));
+            tui.requestRender();
+        });
+    };
     /**
      * Carry out one classified line, wherever it was asked for.
      *
@@ -1493,6 +1677,36 @@ export function apply(ctx, config) {
             case 'copy':
                 runCopyCommand();
                 return;
+            case 'history':
+                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() === '')
+                    model.notice('usage: /stash <draft>, or ctrl+x then s to park the editor');
+                else
+                    void stash?.stashEditor(submission.argument);
+                return;
+            case 'stash-draft':
+                void stash?.stashEditor();
+                return;
+            case 'stash-pop':
+                void stash?.pop(submission.selector);
+                return;
+            case 'stash-apply':
+                void stash?.apply(submission.selector);
+                return;
+            case 'stash-list':
+                void stash?.list(stashCwdLabel);
+                return;
+            case 'stash-drop':
+                void stash?.drop(submission.selector);
+                return;
+            case 'stash-clear':
+                void stash?.clear();
+                return;
             case 'status': {
                 const facts = statusFacts();
                 const context = facts.contextTokens === undefined
@@ -1553,7 +1767,17 @@ export function apply(ctx, config) {
                 }
         }
     };
-    editor.onSubmit = text => runSubmission(classifySubmission(text));
+    editor.onSubmit = text => {
+        const submission = classifySubmission(text);
+        if (submission.kind === 'empty')
+            return;
+        // The library's own history feeds the up/down keys; the store below feeds
+        // ghost completion and reverse search, and is global rather than per-session.
+        editor.addToHistory(text);
+        if (historyEnabled)
+            promptHistory.record(text);
+        runSubmission(submission);
+    };
     disposers.push(ctx.on('session/event', (session, event) => {
         // The surface state — activity, timer, title, bell, job board — belongs to
         // the agent this terminal drives, even while a child is on screen.
@@ -1562,12 +1786,14 @@ export function apply(ctx, config) {
                 turnOpen = true;
                 turnStartedAt = Date.now();
                 terminal.write(windowTitle(process.cwd(), 'working'));
+                herdr.working();
             }
             if (event.type === 'turn/end') {
                 const ranFor = turnStartedAt === undefined ? 0 : Date.now() - turnStartedAt;
                 turnOpen = false;
                 turnStartedAt = undefined;
                 terminal.write(windowTitle(process.cwd(), 'ready'));
+                herdr.idle();
                 if (shouldRingBell({ bell: resolved.bell, ranForMs: ranFor, exiting: exited }))
                     terminal.write(BELL);
                 // A job the turn started may have settled while the reader was watching
@@ -1742,7 +1968,13 @@ export function apply(ctx, config) {
         if (!resolved.resumePicker)
             await presetFor(resolved.sessionId, resolved.resume, undefined);
         tui.start();
+        // Loaded now so the footer's count is real from the first paint, and because
+        // a bank that cannot be read should say so before a reader trusts it.
+        void stash?.open();
         terminal.write(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.
+        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.
         settingsNotice.open(message => model.notice(message));