@sagmans/dsh-tui 0.1.1 → 0.2.0

package/lib/index.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { Editor, ProcessTerminal, ScrollView, TuiAltScreen, VStack, isKeyRelease, matchesKey } from '@earendil-works/pi-tui';
+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 { createPresetRoster, parsePresetArgument } from "./agent/presets.js";
@@ -17,25 +17,38 @@ import { ApprovalGate, QuestionGate, toGateQuestions } from "./gates.js";
 import { createCompletionProvider } from "./input/completion.js";
 import { LOCAL_COMMANDS, classifySubmission } from "./input/submission.js";
 import { resolveConfig } from "./config.js";
+import { FoldCursor } from "./fold-cursor.js";
 import { createRestoreRegistry } from "./terminal/restore.js";
+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 { defaultExportFile, transcriptToText } from "./export.js";
-import { colorEnabled, createTheme } from "./theme.js";
+import { createTheme, forwardEditorTheme, forwardMarkdownTheme } from "./theme.js";
+import { detectColourMode } from "./theme-capability.js";
+import { defaultSettings, readScope, toOverrides, TUI_SETTINGS_NAMESPACE, TuiSettingsSchema } from "./theme-settings.js";
+import { renderThemeTable } from "./theme-command.js";
 import { SessionId } from '@deepseek-ai/dsh-session';
+import { formatTokens } from "./tokens.js";
 import { TranscriptModel } from "./transcript.js";
 import { WorkFold, describeTodos } from "./work.js";
 import { WorkDock } from "./ui/dock.js";
+import { BoxedEditor } from "./ui/editor.js";
 import { MarkdownRenderer } from "./ui/markdown.js";
-import { PresetPicker, SessionPicker } from "./ui/picker.js";
-import { StatusBar, formatTokens } from "./ui/status.js";
-import { TranscriptView } from "./ui/view.js";
+import { EffortPicker, PROVIDER_DEFAULT_EFFORT_ID, PresetPicker, SessionPicker, effortChoices, } from "./ui/picker.js";
+import { StatusBar } from "./ui/status.js";
+import { DEFAULT_VIEW_STATE, TranscriptView } from "./ui/view.js";
 export const name = 'tui';
-/** `agents` is the only service the surface cannot run without. */
-export const inject = ['agents'];
+/**
+ * Services the surface cannot run without.
+ *
+ * `tools` is what lets a card read its tool's own render intent; a context that
+ * has not injected it throws on the property read, which silently degraded
+ * every card to a bare generic row.
+ */
+export const inject = ['agents', 'tools'];
 /** Keys the surface answers itself, listed wherever the reader asks for help. */
-const LOCAL_KEYS = 'ctrl+o tool detail · ctrl+t reasoning · ctrl+b back to this session · ctrl+c interrupt or exit';
+const LOCAL_KEYS = 'ctrl+o tool detail · ctrl+y nested calls · shift+tab reasoning · ctrl+t reasoning effort · ctrl+b back to this session · ctrl+c interrupt or exit';
 /** The one thing to say about a view a reader did not open. */
 const LOCAL_KEYS_BACK = 'ctrl+b returns';
 /** Stored sessions titled at once when the picker opens. */
@@ -78,32 +91,116 @@ export function apply(ctx, config) {
     if (appExit === undefined) {
         throw new Error('dsh-tui: the dsh launcher must provide appExit; start this surface with dsh --profile tui');
     }
-    const theme = createTheme(colorEnabled(resolved.color));
-    const model = new TranscriptModel(createToolPresenter(ctx));
+    /**
+     * The surface's appearance, rebuilt whenever the reader's settings change.
+     *
+     * Renderers hold this object for the life of the session, so the current
+     * theme is swapped *behind* a stable delegate rather than reassigned: every
+     * row then reads one whole table, and a repaint can never observe a
+     * half-applied one. `--no-color` still outranks anything configured.
+     */
+    const themeMode = () => (resolved.color ? detectColourMode(process.env) : 'none');
+    /**
+     * The reader's section, or nothing when the service is not mounted.
+     *
+     * The service is only readable inside an `inject` scope — asking for it
+     * outside one is a composition error, not a missing value — so this stays a
+     * late-bound read that the injection point and the change event both use.
+     */
+    let readSection = () => defaultSettings();
+    /** A refused settings edit, kept until the surface can show it: stderr is behind the alt screen. */
+    let pendingSettingsProblem;
+    let current = createTheme(themeMode());
+    const applyTheme = () => {
+        current = createTheme(themeMode(), toOverrides(readSection()));
+    };
+    const theme = {
+        get revision() { return current.revision; },
+        get color() { return current.color; },
+        style: (token, text) => current.style(token, text),
+        cut: (text, width, ellipsis) => current.cut(text, width, ellipsis),
+        glyph: token => current.glyph(token),
+        visible: token => current.visible(token),
+        // Forwarded rather than read, because the editor and the markdown view keep
+        // the theme object they were built with: a settings change has to reach them
+        // through a stable delegate or they would keep the boot appearance.
+        editor: forwardEditorTheme(() => current.editor),
+        markdown: forwardMarkdownTheme(() => current.markdown),
+    };
+    /**
+     * Rows the reader has opened. The model stays untouched; only the view reads
+     * this. A thought starts folded: it is the longest, least scannable row in the
+     * transcript, so leaving it open pushes the answer a reader came for off the
+     * screen, and a folded row still names itself and its key. A PTC card's calls
+     * start open for the opposite reason: each is one clipped line under a header
+     * that already names the program.
+     */
+    const viewState = { ...DEFAULT_VIEW_STATE };
+    /**
+     * Seed the nested-call display the reader configured.
+     *
+     * The key toggles it for one session, but a settings edit is a deliberate act,
+     * so it re-seeds and becomes the new starting point.
+     */
+    const applyDisplay = () => {
+        viewState.expandSubCalls = readSection().subcalls === 'inline';
+    };
+    /**
+     * Own the section, so the harness validates and persists it for the reader.
+     *
+     * Registration is how the document learns the section exists at all; without
+     * it a hand-written `dsh-tui:` block would be dropped on the next save. The
+     * first read happens here too, because this is the only scope the service
+     * may be touched in.
+     */
+    ctx.inject(['settings'], settingsCtx => {
+        const scope = settingsCtx.settings.register(TUI_SETTINGS_NAMESPACE, TuiSettingsSchema);
+        readSection = () => readScope(scope, message => { pendingSettingsProblem = message; });
+        applyTheme();
+        applyDisplay();
+    });
+    /**
+     * 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();
     const modelSwitch = new ModelSwitch();
     const agentPresets = createPresetRoster(ctx);
+    /** The mode named on the command line, which is the only one that may conflict. */
+    const requestedPreset = resolved.preset;
     /**
      * The mode a session the reader starts from here on joins.
      *
      * A launch flag seeds it and a successful switch updates it, so `/new` and
      * `/fork` land in the mode the reader last chose; nothing is written to
      * settings, because the mode of a session is not a property of the machine.
+     * Unset means nobody chose, which is where the roster's default applies.
      */
-    /** The mode named on the command line, which is the only one that may conflict. */
-    const requestedPreset = resolved.preset;
-    let seat = requestedPreset ?? agentPresets?.defaultId;
+    let seat = requestedPreset;
+    /**
+     * The mode a session takes its seat in: the reader's latest choice, or the
+     * roster's default read at this moment.
+     *
+     * The default cannot be captured when this row applies: it comes from the
+     * settings document, which may be read after that, so a captured copy would
+     * pin every later session to the mode the bundle happened to ship.
+     */
+    const seatMode = () => seat ?? agentPresets?.defaultId;
     const catalog = createModelCatalog(ctx);
     const jobDirectory = createJobDirectory(ctx);
     let jobs = [];
     const roster = new SubagentRoster();
     const subagentControl = createSubagentControl(ctx);
     const markdown = new MarkdownRenderer(theme.markdown);
-    /** Rows the reader has opened. The model stays untouched; only the view reads this. */
-    const viewState = { expandCards: false, expandReasoning: false };
     const restore = createRestoreRegistry();
     const terminal = new ProcessTerminal();
-    const tui = new TuiAltScreen(terminal);
+    const tui = new WarningSafeTui(terminal);
     /** The session this surface drives: commands, approvals, and the bell belong to it. */
     let activeSession = resolved.sessionId;
     /** The session the transcript is showing, which can be one of its children. */
@@ -117,8 +214,13 @@ export function apply(ctx, config) {
         gate: () => pending?.gate.card(),
         picker: () => pendingPicker?.picker.card(),
     });
-    const editor = new Editor(tui, theme.editor);
+    const editor = new BoxedEditor(tui, theme.editor);
     const disposers = [];
+    // The presenter closure outlives the composition's own teardown, so it must
+    // not keep an agent alive after its world unwinds.
+    disposers.push(() => {
+        presentScope = undefined;
+    });
     let agent;
     let turnOpen = false;
     let turnStartedAt;
@@ -275,11 +377,20 @@ export function apply(ctx, config) {
             tui.requestRender();
             return { consume: true };
         }
-        if (matchesKey(data, 'ctrl+t')) {
+        if (matchesKey(data, 'shift+tab')) {
             viewState.expandReasoning = !viewState.expandReasoning;
             tui.requestRender();
             return { consume: true };
         }
+        if (matchesKey(data, 'ctrl+y')) {
+            viewState.expandSubCalls = !viewState.expandSubCalls;
+            tui.requestRender();
+            return { consume: true };
+        }
+        if (matchesKey(data, 'ctrl+t')) {
+            void openEffortPicker();
+            return { consume: true };
+        }
         if (matchesKey(data, 'ctrl+b')) {
             if (viewedSession !== activeSession)
                 void showAgentSession();
@@ -429,11 +540,31 @@ export function apply(ctx, config) {
      * materialized; a session this process is not running falls back to storage.
      */
     const liveSession = (id) => ctx.get('sessions')?.get?.(id);
+    /**
+     * 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();
+    /** Feed one durable event to the model, unless a fold has already folded it. */
+    const applyDurable = (event) => {
+        if (foldCursor.accept(event))
+            applyEvent(event);
+    };
     const foldHistory = async (id) => {
+        // 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 = ctx.agents?.get(id);
+        // Every fold starts a cleared transcript, so this session's own numbering is
+        // where the cursor begins rather than the previous session's.
+        foldCursor.reset();
         const inMemory = liveSession(id)?.snapshotEvents?.();
         if (inMemory !== undefined) {
             for (const event of inMemory)
-                applyEvent(event);
+                applyDurable(event);
             return inMemory.length;
         }
         const history = createSessionHistory(ctx);
@@ -441,7 +572,7 @@ export function apply(ctx, config) {
             return 0;
         const events = await history.read(id);
         for (const event of events)
-            applyEvent(event);
+            applyDurable(event);
         return events.length;
     };
     const replayHistory = async (id) => {
@@ -507,13 +638,13 @@ export function apply(ctx, config) {
         if (agentPresets === undefined)
             return undefined;
         if (fork !== undefined)
-            return agentPresets.current(liveSession(fork.from)) ?? seat;
+            return agentPresets.current(liveSession(fork.from)) ?? seatMode();
         if (!resume)
-            return seat;
+            return seatMode();
         const history = createSessionHistory(ctx);
         const stored = history === undefined ? undefined : await presetOfStoredSession(history, id);
         if (stored === undefined)
-            return seat;
+            return seatMode();
         const resolvedStored = await resolveStored(id, stored);
         if (resolvedStored === undefined) {
             // The composition this session recorded is gone. Naming one explicitly is
@@ -541,8 +672,6 @@ export function apply(ctx, config) {
         // Settled before the transcript is touched, so a refusal leaves neither a
         // half-replayed session nor a half-composed agent behind.
         const preset = await presetFor(id, resume, fork);
-        if (resume)
-            await replayHistory(id);
         const handle = await startAgent(ctx, {
             sessionId: id,
             resume,
@@ -561,6 +690,16 @@ export function apply(ctx, config) {
         activeSession = id;
         viewedSession = id;
         agent = handle;
+        // 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;
+        // Replayed only once the agent exists, because the fold reads every card
+        // through the scope the preset mounted; a fold before that scope existed
+        // degraded each replayed card to a bare generic row. The agent's loop is
+        // live by now, so the fold and the stream race over the same events; the
+        // durable sequence number is what keeps one event from landing twice.
+        if (resume)
+            await replayHistory(id);
         // A branch inherits the conversation the reader was already reading, so it
         // opens on that history rather than on an empty screen.
         if (fork !== undefined)
@@ -576,6 +715,9 @@ export function apply(ctx, config) {
     const switchSession = async (id) => {
         const previous = agent;
         agent = undefined;
+        // Drop the outgoing scope before its agent is disposed, so no card folded
+        // during the transition can read a torn-down world.
+        presentScope = undefined;
         turnOpen = false;
         model.reset();
         work.reset();
@@ -833,7 +975,7 @@ export function apply(ctx, config) {
                     ? `${facts.model ?? 'unset'}${facts.effort === undefined ? '' : ` (${facts.effort})`} · composition default`
                     : `${current.provider}/${current.model}${current.reasoningEffort === undefined ? '' : ` (${current.reasoningEffort})`}`;
                 const providers = catalog.providers().map(provider => provider.id);
-                model.notice(`model ${route} · providers: ${providers.length === 0 ? 'none' : providers.join(', ')} · /model <provider>/<model> switches, /model <provider> lists its models`);
+                model.notice(`model ${route} · providers: ${providers.length === 0 ? 'none' : providers.join(', ')} · /model <provider>/<model>[/<effort>] switches, /model <provider> lists its models`);
                 tui.requestRender();
                 return;
             }
@@ -848,17 +990,95 @@ export function apply(ctx, config) {
                     tui.requestRender();
                 });
                 return;
-            case 'switch':
-                modelSwitch.choose(command.choice);
-                model.notice(`model set to ${command.choice.provider}/${command.choice.model} for the next step`);
-                tui.requestRender();
+            case 'switch': {
+                const choice = command.choice;
+                if (choice.reasoningEffort === undefined) {
+                    modelSwitch.choose(choice);
+                    model.notice(`model set to ${choice.provider}/${choice.model} for the next step`);
+                    tui.requestRender();
+                    return;
+                }
+                // The route decides which efforts exist, so an explicit one is checked
+                // against the adapter before it is put in force: a typo must not become
+                // a request the provider rejects.
+                void (async () => {
+                    try {
+                        const info = await catalog.efforts(choice.provider, choice.model);
+                        const efforts = info?.efforts ?? [];
+                        if (!efforts.some(effort => effort.id === choice.reasoningEffort)) {
+                            model.notice(efforts.length === 0
+                                ? `/model: ${choice.provider}/${choice.model} advertises no reasoning efforts`
+                                : `/model: ${choice.provider}/${choice.model} does not offer reasoning effort "${choice.reasoningEffort}" — offers: ${efforts.map(effort => effort.id).join(' ')}`);
+                            tui.requestRender();
+                            return;
+                        }
+                        modelSwitch.choose(choice);
+                        model.notice(`model set to ${choice.provider}/${choice.model} (${choice.reasoningEffort}) for the next step`);
+                    }
+                    catch (error) {
+                        model.notice(`/model: could not read reasoning efforts: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                    tui.requestRender();
+                })();
                 return;
+            }
             case 'invalid':
                 model.notice(`/model: ${command.reason}`);
                 tui.requestRender();
                 return;
         }
     };
+    /** Whether a route's effort list is being read, so a second key cannot race it. */
+    let openingEfforts = false;
+    /** Put the reader's effort choice in force for the next step. */
+    const applyEffort = (provider, modelId, effortId) => {
+        modelSwitch.choose(effortId === PROVIDER_DEFAULT_EFFORT_ID
+            ? { provider, model: modelId }
+            : { provider, model: modelId, reasoningEffort: effortId });
+        model.notice(`reasoning effort for ${provider}/${modelId} set to ${effortId === PROVIDER_DEFAULT_EFFORT_ID ? 'provider default' : effortId} for the next step`);
+        tui.requestRender();
+    };
+    /**
+     * Offer the efforts the route in force advertises.
+     *
+     * The list is read before the picker opens because the rows are the route's
+     * own metadata; a menu painted before that arrived could offer a level the
+     * request would then be refused for.
+     */
+    const openEffortPicker = async () => {
+        if (catalog === undefined) {
+            model.notice('this profile has no llm service, so reasoning efforts cannot be read');
+            tui.requestRender();
+            return;
+        }
+        const facts = statusFacts();
+        if (facts.provider === undefined || facts.model === undefined) {
+            model.notice('no model route is in use; /model <provider>/<model> picks one first');
+            tui.requestRender();
+            return;
+        }
+        if (openingEfforts)
+            return;
+        openingEfforts = true;
+        try {
+            const info = await catalog.efforts(facts.provider, facts.model);
+            const efforts = info?.efforts ?? [];
+            if (efforts.length === 0) {
+                model.notice(`${facts.provider}/${facts.model} advertises no reasoning efforts`);
+                return;
+            }
+            const picked = await openPicker(new EffortPicker(() => effortChoices(efforts, facts.effort), `reasoning effort · ${facts.provider}/${facts.model}`));
+            if (picked !== undefined)
+                applyEffort(facts.provider, facts.model, picked);
+        }
+        catch (error) {
+            model.notice(`could not read reasoning efforts: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            openingEfforts = false;
+            tui.requestRender();
+        }
+    };
     /**
      * Show or choose the mode this session runs.
      *
@@ -943,6 +1163,26 @@ export function apply(ctx, config) {
             tui.requestRender();
         });
     };
+    /**
+     * Put the deployment default in force before the first turn.
+     *
+     * The agent is created before the settings file has been read, so the route
+     * its loop captured is the composition placeholder; the reader's default —
+     * effort included — only exists by the time they can type. Adopting it here
+     * is what makes the status line's route the one the request actually uses.
+     */
+    const adoptDefaultRoute = () => {
+        if (modelSwitch.current() !== undefined)
+            return;
+        const facts = statusFacts();
+        if (facts.provider === undefined || facts.model === undefined)
+            return;
+        modelSwitch.adopt({
+            provider: facts.provider,
+            model: facts.model,
+            ...(facts.effort === undefined ? {} : { reasoningEffort: facts.effort }),
+        });
+    };
     editor.onSubmit = text => {
         const submission = classifySubmission(text);
         switch (submission.kind) {
@@ -978,6 +1218,11 @@ export function apply(ctx, config) {
             case 'todo':
                 runTodoCommand();
                 return;
+            case 'theme':
+                for (const line of renderThemeTable(toOverrides(readSection())))
+                    model.notice(line);
+                tui.requestRender();
+                return;
             case 'copy':
                 runCopyCommand();
                 return;
@@ -1030,8 +1275,10 @@ export function apply(ctx, config) {
                 // While a turn is running the human is steering it, not opening another.
                 if (turnOpen)
                     agent.steer(submission.text);
-                else
+                else {
+                    adoptDefaultRoute();
                     agent.submit(submission.text);
+                }
         }
     };
     disposers.push(ctx.on('session/event', (session, event) => {
@@ -1057,7 +1304,8 @@ export function apply(ctx, config) {
         }
         if (session.id !== viewedSession)
             return;
-        applyEvent(event);
+        presentScope = ctx.agents?.get(session.id);
+        applyDurable(event);
         tui.requestRender();
     }));
     /**
@@ -1145,6 +1393,30 @@ export function apply(ctx, config) {
         model.applyStreamChunk(payload.frame.chunk);
         tui.requestRender();
     }));
+    /**
+     * Restyle a running session when the reader's section changes.
+     *
+     * The settings document is hot-reloaded by the host, so a reader watching a
+     * shade land never has to leave the session to see it — which is what makes
+     * tuning one bearable instead of a restart per attempt. The event is
+     * namespace-filtered: another surface's preferences are not our repaint.
+     */
+    disposers.push(ctx.on('settings/updated', ns => {
+        if (String(ns) !== TUI_SETTINGS_NAMESPACE)
+            return;
+        pendingSettingsProblem = undefined;
+        applyTheme();
+        applyDisplay();
+        // Both caches hold rows under the old table, so they have to be told the
+        // table moved; a repaint alone would reuse what they already stored.
+        markdown.invalidate();
+        view.invalidate();
+        if (pendingSettingsProblem !== undefined) {
+            model.notice(`dsh-tui settings: ${pendingSettingsProblem}`);
+            pendingSettingsProblem = undefined;
+        }
+        tui.requestRender();
+    }));
     const degraded = describeMissingOptional(probe);
     if (degraded !== undefined)
         model.notice(degraded);
@@ -1187,6 +1459,12 @@ export function apply(ctx, config) {
             await presetFor(resolved.sessionId, resolved.resume, undefined);
         tui.start();
         terminal.write(windowTitle(process.cwd(), 'ready'));
+        // A refused settings edit is only visible now that the surface owns the
+        // screen; a bare stderr line would have been hidden behind it.
+        if (pendingSettingsProblem !== undefined) {
+            model.notice(`dsh-tui settings: ${pendingSettingsProblem}`);
+            pendingSettingsProblem = undefined;
+        }
         await boot();
     };
     void start().catch((error) => {