@itookit/dsht 0.3.7 → 0.5.1

package/dist/ui/chat/status.js

@@ -5,9 +5,8 @@ import { memo, useEffect, useState } from 'react';
 import { Box, Text, useStdout } from 'ink';
 import wrapAnsi from 'wrap-ansi';
 import stringWidth from 'string-width';
-import { costText } from "../../cost/index.js";
-import { toolLine } from "../../session/transcript.js";
-import { safeText } from "../../transport/wire.js";
+import { toolLine } from "../../text.js";
+import { safeText } from "../../text.js";
 /** Format elapsed wall time, clamping clock skew instead of displaying negative durations.
  * @param milliseconds - Elapsed duration.
  * @returns Minute/second display, with hours when needed.
@@ -215,32 +214,33 @@ function measure(row) {
     return row.reduce((sum, segment) => sum + stringWidth(segment.text), 0);
 }
 /** Render a live clock and selected-session metadata; the timer belongs to this mounted bar. */
-export const StatusBar = memo(function StatusBar({ controller, expanded = false, width, scroll = 0, pageSize, onScroll, onOverflow, onRows, pauseReason }) {
+export const StatusBar = memo(function StatusBar({ source, expanded = false, width, scroll = 0, pageSize, onScroll, onOverflow, onRows, pauseReason }) {
     const paused = pauseReason !== undefined;
     const theme = useTheme();
     const { stdout } = useStdout();
     const [now, setNow] = useState(Date.now);
     const [reported, setReported] = useState(1);
-    const running = controller.running;
-    const since = controller.workingSince;
+    const running = source.running;
+    const activity = source.activity;
+    // The controller already merged a turn and a loop into one answer; the bar only draws it.
+    const busy = activity !== undefined;
+    const since = activity?.kind === 'turn' ? activity.since : activity?.kind === 'loop' ? activity.startedAt : undefined;
     useEffect(() => {
         setNow(Date.now());
         if (paused)
             return;
         // An idle bar still re-reads the clock, so a day rollover reaches the cost it reports without
-        // waiting for an unrelated render; a running bar keeps its per-second clock.
-        const timer = setInterval(() => setNow(Date.now()), running ? 1000 : 60_000);
+        // waiting for an unrelated render; a busy bar keeps its per-second clock.
+        const timer = setInterval(() => setNow(Date.now()), busy ? 1000 : 60_000);
         return () => clearInterval(timer);
-    }, [running, since, paused]);
-    const state = controller.state;
-    const workspace = state.workspaces.find(item => item.workspaceId === state.workspaceId);
-    const view = controller.telemetry.view(state.sessionId);
-    const costs = controller.costs;
-    const sessionCost = controller.sessionCostText;
-    const todayCost = costs ? costText(costs.today()) : '?';
+    }, [busy, since, paused]);
+    const state = source;
+    const view = { values: source.values, queued: source.queued, jobs: source.jobs };
+    const costs = source.cost;
+    const sessionCost = source.cost?.sessionText ?? '?';
     // `*` belongs to costText alone; incomplete coverage is a separate degradation, reported by `!`.
-    const coverage = costs?.coverage ?? 'complete';
-    const label = workspace ? `${workspace.title} · ${workspace.path}` : 'none selected';
+    const coverage = source.cost?.coverage ?? 'complete';
+    const label = source.workspaceLabel;
     if (!expanded) {
         const selection = record(view.values.modelSelection);
         const route = record(running ? selection.lastUsed ?? selection.next ?? state.defaultModel : selection.next ?? selection.lastUsed ?? state.defaultModel);
@@ -258,29 +258,38 @@ export const StatusBar = memo(function StatusBar({ controller, expanded = false,
         const billed = buckets[0] === undefined || buckets[2] === undefined ? undefined : buckets[0] + buckets[2] + (buckets[3] ?? 0);
         const hit = cacheHitText(buckets[2], billed);
         const compactCount = (value) => value === undefined ? '?' : compactNumber.format(value);
-        const phase = state.session.record.livePhase;
-        const clock = running && since !== undefined ? ` ${clockText(now - since)}` : '';
+        const phase = source.livePhase;
+        const clock = busy && since !== undefined ? ` ${clockText(now - since)}` : '';
         const phaseLabel = phase === undefined ? undefined
             : phase.kind === 'tool' ? `${phase.name ?? 'tool'} ${phaseText(now - phase.startedAt)}`
                 : `${phase.kind === 'thinking' ? 'think' : 'write'} ${phaseText(now - phase.startedAt)}`;
+        // A host turn's phase wins; without one, the controller's loop activity names what the client is
+        // doing, so the bar never reports an idle session while a review is in flight.
+        const phaseSegment = !busy ? undefined
+            : phaseLabel !== undefined ? { text: phaseLabel }
+                : activity?.kind === 'loop' ? { text: `${activity.activity} ${activity.step}/${activity.total}` }
+                    : activity?.kind === 'paused' ? { text: 'needs you' }
+                        : undefined;
         // The state token reports a fact and never guesses: a paused clock is named, offline and errors
         // take the token over, and an unknown phase simply leaves the phase group empty. An answer this
         // client still owes outranks the paused reason, because that reason is only why the clock stopped.
-        const stateToken = !state.online
+        const stateToken = !source.online
             ? { text: '! Offline', color: theme.status.offline }
-            : state.controlError || state.modelError
+            : source.controlError || source.modelError
                 ? { text: '⚠ Error', color: theme.status.warning }
-                : state.pending.length > 0
+                : source.pendingCount > 0
                     ? { text: '? Needs you', color: theme.status.critical }
                     : pauseReason !== undefined
                         ? { text: `⏸ ${pauseReason}${clock}`, color: theme.colors.muted }
-                        : running ? { text: `◐${clock}`, color: theme.status.working } : { text: '● Ready', color: theme.status.ready };
+                        : activity?.kind === 'paused' ? { text: '⏸ needs you', color: theme.status.critical }
+                            : busy ? { text: `◐${clock}`, color: theme.status.working } : { text: '● Ready', color: theme.status.ready };
         // One marker covers both scopes, because either an unpriceable record or a scan that has not
         // covered every session makes the pair inexact as a reading.
         const inexact = coverage !== 'complete';
         const money = (session, today) => `¥: ${session === undefined ? '?' : session.amount.toFixed(2)}(${today.amount.toFixed(2)})${session?.unknown || today.unknown || inexact ? '*' : ''}`;
+        // Read here rather than from a snapshot, so the bar's own clock drives a day rollover.
         const todayTotal = costs?.today();
-        const sessionTotal = costs !== undefined && costs.hasSession(state.sessionId) ? costs.total(state.sessionId) : undefined;
+        const sessionTotal = costs?.session();
         const contextColor = percent === undefined ? theme.status.usage
             : percent >= 95 ? theme.status.critical : percent >= 80 ? theme.status.warning : theme.status.context;
         // Ten cells resolve context to tenths, the same resolution the percentage beside them reports.
@@ -288,10 +297,11 @@ export const StatusBar = memo(function StatusBar({ controller, expanded = false,
         const groups = {
             state: stateToken,
             // A paused bar keeps the phase: the reason already says why the clock stopped, and dropping the
-            // running tool would leave the one question this bar exists to answer unanswered. A ready bar
-            // has none: the transcript keeps the last event it saw, and only the host knows the turn ended.
-            ...(phaseLabel === undefined || !running ? {} : { phase: { text: phaseLabel } }),
-            ...(running && pauseReason === undefined ? { stop: { text: '^C' } } : {}),
+            // running tool would leave the one question this bar exists to answer unanswered. A bar with no
+            // work of its own has none: the transcript keeps the last event it saw, and only the host knows
+            // the turn ended.
+            ...(phaseSegment === undefined ? {} : { phase: phaseSegment }),
+            ...(busy && pauseReason === undefined ? { stop: { text: '^C' } } : {}),
             ...(todayTotal === undefined ? {} : { cost: { text: money(sessionTotal, todayTotal), color: theme.status.cost } }),
             ...(percent === undefined ? {} : {
                 context: { text: `ctx ${percent}%`, color: contextColor },
@@ -310,26 +320,27 @@ export const StatusBar = memo(function StatusBar({ controller, expanded = false,
         }
         return _jsx(Box, { flexDirection: "column", children: rows.map((row, index) => _jsx(Text, { wrap: "truncate-end", children: row.map((segment, position) => _jsx(Text, { color: segment.color ?? theme.colors.muted, bold: index === 0 && position === 0, children: segment.text }, position)) }, index)) });
     }
-    return _jsx(StatusDetails, { controller: controller, theme: theme, width: width, now: now, scroll: scroll, pageSize: pageSize, onScroll: onScroll, onOverflow: onOverflow });
+    return _jsx(StatusDetails, { source: source, theme: theme, width: width, now: now, scroll: scroll, pageSize: pageSize, onScroll: onScroll, onOverflow: onOverflow });
 });
 /** Expanded detail panel.
  *
  * It is a separate component because it is the only branch that scrolls, and a hook behind the
  * collapsed branch's early return would change the hook order between the two states.
  */
-const StatusDetails = memo(function StatusDetails({ controller, theme, width, now, scroll, pageSize, onScroll, onOverflow }) {
+const StatusDetails = memo(function StatusDetails({ source, theme, width, now, scroll, pageSize, onScroll, onOverflow }) {
     const { stdout } = useStdout();
-    const state = controller.state;
-    const running = controller.running;
-    const since = controller.workingSince;
-    const workspace = state.workspaces.find(item => item.workspaceId === state.workspaceId);
-    const view = controller.telemetry.view(state.sessionId);
-    const costs = controller.costs;
-    const sessionCost = controller.sessionCostText;
-    const todayCost = costs ? costText(costs.today()) : '?';
+    const state = source;
+    const running = source.running;
+    const activity = source.activity;
+    const busy = activity !== undefined;
+    const since = activity?.kind === 'turn' ? activity.since : activity?.kind === 'loop' ? activity.startedAt : undefined;
+    const view = { values: source.values, queued: source.queued, jobs: source.jobs };
+    const costs = source.cost;
+    const sessionCost = source.cost?.sessionText ?? '?';
+    const todayCost = source.cost?.today().text ?? '?';
     // `*` belongs to costText alone; incomplete coverage is a separate degradation, reported by `!`.
-    const coverage = costs?.coverage ?? 'complete';
-    const label = workspace ? `${workspace.title} · ${workspace.path}` : 'none selected';
+    const coverage = source.cost?.coverage ?? 'complete';
+    const label = source.workspaceLabel;
     // Every detail row wraps to the terminal width, so a narrow terminal loses nothing; lines that
     // still do not fit are scrolled rather than dropped, because the panel shares the screen height.
     // Rows are merged and labelled compactly so a normal terminal shows every detail on one screen;
@@ -337,23 +348,27 @@ const StatusDetails = memo(function StatusDetails({ controller, theme, width, no
     const turns = count(numeric(record(view.values.sessionStats).turns));
     const duration = since === undefined ? 'unknown duration' : elapsedTime(now - since);
     const detail = [
-        { key: 'activity', color: state.pending.length > 0 ? theme.status.critical : running ? theme.colors.context : theme.colors.muted, text: state.pending.length > 0
+        { key: 'activity', color: source.pendingCount > 0 ? theme.status.critical : busy ? theme.colors.context : theme.colors.muted, text: source.pendingCount > 0
                 ? '? Needs you · answer the request above to continue'
                 : running
-                    ? `◐ Working · ${duration}${state.session.record.activeTurnStartedAt === undefined ? ' (observed)' : ''} · Ctrl+C Stop`
-                    : '● Ready · Ctrl+C exit' },
-        { key: 'host', text: `${safeText(controller.base)} · ${safeText(state.status)}${!state.online ? ' · offline, last known status' : ''}` },
-        ...state.sessionId
-            ? [{ key: 'session', text: `Session ${safeText(state.sessionId)}${controller.sessionMode ? ` · ${safeText(controller.sessionMode)}` : ''}` }] : [],
+                    ? `◐ Working · ${duration}${source.activeTurnStartedAt === undefined ? ' (observed)' : ''} · Ctrl+C Stop`
+                    : activity?.kind === 'loop'
+                        ? `◐ ${activity.activity} ${activity.step}/${activity.total} · ${duration} · Ctrl+C Stop`
+                        : activity?.kind === 'paused'
+                            ? `⏸ ${activity.title} · needs you · /loop answer <text> or /loop abort`
+                            : '● Ready · Ctrl+C exit' },
+        { key: 'host', text: `${safeText(source.host)} · ${safeText(state.status)}${!source.online ? ' · offline, last known status' : ''}` },
+        ...source.sessionId
+            ? [{ key: 'session', text: `Session ${safeText(source.sessionId)}${source.sessionMode ? ` · ${safeText(source.sessionMode)}` : ''}` }] : [],
         { key: 'workspace', text: `Workspace ${safeText(label)}` },
-        ...metricLines(view.values, state.defaultModel, running).map((line, index) => ({ key: `metric-${index}`, text: safeText(line), dim: true })),
+        ...metricLines(view.values, source.defaultModel, running).map((line, index) => ({ key: `metric-${index}`, text: safeText(line), dim: true })),
         ...costs ? [{ key: 'cost', text: `Cost ${sessionCost} session · ${todayCost} today · ${turns} turns`, dim: true }] : [],
         { key: 'queued', text: `Queued ${count(view.queued)} · Jobs ${count(view.jobs)}${costs ? '' : ` · ${turns} turns`}`, dim: true },
         ...costs && coverage === 'partial'
             ? [{ key: 'coverage', color: theme.colors.context, text: `Cost coverage incomplete: ${costs.error ? safeText(costs.error) : 'no complete scan yet'}` }] : [],
-        ...state.controlError ? [{ key: 'control-error', color: theme.colors.context, text: safeText(state.controlError) }] : [],
-        ...state.presetError ? [{ key: 'preset-error', color: theme.colors.context, text: `Preset names unavailable: ${safeText(state.presetError)}` }] : [],
-        ...state.modelError ? [{ key: 'model-error', color: theme.colors.context, text: `Model catalog unavailable: ${safeText(state.modelError)}` }] : [],
+        ...source.controlError ? [{ key: 'control-error', color: theme.colors.context, text: safeText(source.controlError) }] : [],
+        ...source.presetError ? [{ key: 'preset-error', color: theme.colors.context, text: `Preset names unavailable: ${safeText(source.presetError)}` }] : [],
+        ...source.modelError ? [{ key: 'model-error', color: theme.colors.context, text: `Model catalog unavailable: ${safeText(source.modelError)}` }] : [],
     ];
     // Border and horizontal padding take four columns, so a detail row wraps inside what is left.
     const inner = Math.max(1, (width ?? Math.max(3, (stdout.columns ?? 80) - 2)) - 4);

package/dist/ui/chat/viewport.d.ts

@@ -1,7 +1,7 @@
 /** Measured conversation viewport: only visible rows become React nodes. */
 import { type DOMElement } from 'ink';
 import type { RefObject } from 'react';
-import type { HistoryRow } from '../../session/history.ts';
+import type { HistoryRow } from '../../contracts.ts';
 /** Visible conversation rows plus the scroll hint.
  * @param props - Rows, hint state, freeze identity and the measured box.
  * @returns The scrollable conversation area.

package/dist/ui/dialogs/cost.d.ts

@@ -1,8 +1,25 @@
-import type { Controller } from '../../controller/index.ts';
+import type { Coverage } from '../../contracts.ts';
+/** One formatted cost line: what to show, and how exact it is. */
+export interface CostLine {
+    text: string;
+    unknown: number;
+    records: number;
+}
+/** The billing panel's plain input, assembled by the composition root. */
+export interface CostSource {
+    session?: CostLine;
+    today: CostLine;
+    scanning: boolean;
+    coverage: Coverage;
+    scannedAt?: number;
+    customPrices: boolean;
+    error?: string;
+    missing: readonly string[];
+}
 /** Render cached totals while the independent HTTP cost scan refreshes.
- * @param controller - Selected session and origin-scoped cost ledger.
+ * @param source - Plain billing summary, absent when this run has no ledger.
  * @returns Billing panel, including unpriced models and refresh errors.
  */
-export declare function CostPanel({ controller }: {
-    controller: Controller;
+export declare function CostPanel({ source }: {
+    source?: CostSource;
 }): import("react").JSX.Element;

package/dist/ui/dialogs/cost.js

@@ -2,24 +2,19 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Billing estimates with explicit coverage, calendar and unknown-price indicators. */
 import { useTheme } from "../theme/index.js";
 import { Box, Text } from 'ink';
-import { costText } from "../../cost/index.js";
-import { safeText } from "../../transport/wire.js";
+import { safeText } from "../../text.js";
 /** Render cached totals while the independent HTTP cost scan refreshes.
- * @param controller - Selected session and origin-scoped cost ledger.
+ * @param source - Plain billing summary, absent when this run has no ledger.
  * @returns Billing panel, including unpriced models and refresh errors.
  */
-export function CostPanel({ controller }) {
+export function CostPanel({ source }) {
     const theme = useTheme();
-    const costs = controller.costs;
+    const costs = source;
     if (!costs)
         return _jsx(Text, { children: "Cost tracking is unavailable" });
-    const id = controller.state.sessionId;
-    const rows = [
-        ['Session', id && costs.hasSession(id) ? costs.total(id) : undefined],
-        ['Today', costs.today()],
-    ];
-    return _jsxs(Box, { flexDirection: "column", borderStyle: "single", paddingX: 1, children: [_jsx(Text, { bold: true, children: "Cost \u00B7 CNY estimate \u00B7 Asia/Shanghai \u00B7 /cost closes" }), rows.map(([label, total]) => _jsxs(Text, { children: [label, ": ", total ? `${costText(total)} · ${total.unknown} unpriced / ${total.records} requests` : '?'] }, label)), _jsx(Text, { dimColor: true, children: costs.scanning ? 'Refreshing all visible sessions…'
+    const rows = [['Session', costs.session], ['Today', costs.today]];
+    return _jsxs(Box, { flexDirection: "column", borderStyle: "single", paddingX: 1, children: [_jsx(Text, { bold: true, children: "Cost \u00B7 CNY estimate \u00B7 Asia/Shanghai \u00B7 /cost closes" }), rows.map(([label, total]) => _jsxs(Text, { children: [label, ": ", total ? `${total.text} · ${total.unknown} unpriced / ${total.records} requests` : '?'] }, label)), _jsx(Text, { dimColor: true, children: costs.scanning ? 'Refreshing all visible sessions…'
                     : costs.coverage === 'partial' ? 'Partial totals · awaiting a complete scan'
                         : costs.scannedAt ? `Last refresh: ${new Date(costs.scannedAt).toISOString()}`
-                            : 'Cached totals from the previous run' }), costs.customPrices && _jsx(Text, { color: theme.colors.context, children: "Rates come from prices.json, not the shipped table." }), _jsx(Text, { dimColor: true, children: "Recorded settlement time determines tariff; * means a subtotal is not exact. Provider invoices are authoritative." }), costs.error && _jsxs(Text, { color: theme.colors.context, children: ["Partial totals: ", safeText(costs.error)] }), costs.missing().slice(0, 6).map(reason => _jsx(Text, { color: theme.colors.context, children: safeText(reason) }, reason))] });
+                            : 'Cached totals from the previous run' }), costs.customPrices && _jsx(Text, { color: theme.colors.context, children: "Rates come from prices.json, not the shipped table." }), _jsx(Text, { dimColor: true, children: "Recorded settlement time determines tariff; * means a subtotal is not exact. Provider invoices are authoritative." }), costs.error && _jsxs(Text, { color: theme.colors.context, children: ["Partial totals: ", safeText(costs.error)] }), costs.missing.slice(0, 6).map(reason => _jsx(Text, { color: theme.colors.context, children: safeText(reason) }, reason))] });
 }

package/dist/ui/dialogs/index.d.ts

@@ -1,7 +1,7 @@
-import { type ObjectValue } from '../../transport/wire.ts';
-import { type Message } from '../../session/transcript.ts';
-import type { HistorySearch, RemovalTarget } from '../../session/types.ts';
-import type { QueuedInput } from '../../session/telemetry.ts';
+import { type ObjectValue } from '../../json.ts';
+import { type Message, type SavedPrompt } from '../../contracts.ts';
+import type { HistorySearch, RemovalTarget } from '../../contracts.ts';
+import type { QueuedInput } from '../../contracts.ts';
 import { type Choice } from './picker.tsx';
 /** Pending host input with explicit removal.
  * @param props - Queue contents, geometry and availability.
@@ -16,6 +16,23 @@ export declare function QueueDialog({ queued, rows, width, unavailable, enabled,
     canSelect(): boolean;
     onRemove(id: string): void;
 }): import("react").JSX.Element;
+/** Operator-saved shortcut prompts with choose, edit and delete.
+ *
+ * Enter hands the text to the composer rather than sending it, so the reader can adjust it first.
+ * @param props - Saved entries, their load error, geometry and the three row actions.
+ * @returns The saved-prompt picker.
+ */
+export declare function PromptsDialog({ identity, prompts, error, width, enabled, canSelect, onChoose, onEdit, onRemove }: {
+    identity: string;
+    prompts: readonly SavedPrompt[];
+    error?: string;
+    width: number;
+    enabled: boolean;
+    canSelect(): boolean;
+    onChoose(text: string): void;
+    onEdit(prompt: SavedPrompt): void;
+    onRemove(id: string): void;
+}): import("react").JSX.Element;
 /** Confirmation for workspace removal or session archival.
  * @param props - Reviewed target and its confirmation actions.
  * @returns The confirmation dialog.
@@ -27,7 +44,7 @@ export declare function RemovalDialog({ removal, enabled, canSelect, onCancel, o
     onCancel(): void;
     onConfirm(): void;
 }): import("react").JSX.Element;
-import type { ModelState } from '../../session/index.ts';
+import type { ModelState } from '../../contracts.ts';
 /** Two-step model and reasoning-effort selector; the state shape is shared with the session. */
 export type { ModelState };
 /** Model routes and adapter-owned reasoning efforts.

package/dist/ui/dialogs/index.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Modal panels and list screens rendered inside the shared composer frame. */
 import { Box, Text } from 'ink';
-import { array, object, safeText, string } from "../../transport/wire.js";
-import { toolLine } from "../../session/transcript.js";
-import { COMMAND_HINTS, COMMAND_LABELS, COMMAND_LABEL_WIDTH } from "../commands/registry.js";
+import { array, object, string } from "../../json.js";
+import { safeText } from "../../text.js";
+import { toolLine } from "../../text.js";
+import { COMMAND_HINTS, COMMAND_LABELS, COMMAND_LABEL_WIDTH } from "../../slash/registry.js";
 import { useTheme } from "../theme/index.js";
 import { Picker } from "./picker.js";
 /** Pending host input with explicit removal.
@@ -17,6 +18,21 @@ export function QueueDialog({ queued, rows, width, unavailable, enabled, canSele
                     remove: () => onRemove(item.id),
                 })), pageSize: Math.max(1, Math.min(6, rows - 12)), hint: "\u2191 \u2193 select \u00B7 Enter / d / Delete remove \u00B7 Esc close", enabled: enabled, canSelect: canSelect })] });
 }
+/** Operator-saved shortcut prompts with choose, edit and delete.
+ *
+ * Enter hands the text to the composer rather than sending it, so the reader can adjust it first.
+ * @param props - Saved entries, their load error, geometry and the three row actions.
+ * @returns The saved-prompt picker.
+ */
+export function PromptsDialog({ identity, prompts, error, width, enabled, canSelect, onChoose, onEdit, onRemove }) {
+    const theme = useTheme();
+    return _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(Text, { bold: true, children: "Saved prompts \u00B7 Esc close" }), error !== undefined && _jsx(Text, { color: theme.colors.error, wrap: "truncate-end", children: safeText(error) }), !prompts.length && _jsx(Text, { dimColor: true, children: "No saved prompts \u00B7 add one with /prompt TEXT" }), _jsx(Picker, { choices: prompts.map(prompt => ({
+                    key: prompt.id, label: toolLine(prompt.text, width - 6),
+                    action: () => onChoose(prompt.text),
+                    edit: () => onEdit(prompt),
+                    remove: () => onRemove(prompt.id),
+                })), hint: "\u2191 \u2193 select \u00B7 Enter use \u00B7 e edit \u00B7 d/Delete delete \u00B7 Esc close", enabled: enabled, canSelect: canSelect }, identity)] });
+}
 /** Confirmation for workspace removal or session archival.
  * @param props - Reviewed target and its confirmation actions.
  * @returns The confirmation dialog.

package/dist/ui/dialogs/loop.d.ts

@@ -0,0 +1,43 @@
+import type { LoopLimits, LoopRecord } from '../../contracts.ts';
+/** The numeric fields the form edits, in the order a run reads them. */
+export type LoopField = 'from' | 'to' | 'score' | 'tries';
+/** What the form hands to the runner: the four numbers and the record's variables as confirmed. */
+export interface LoopRun {
+    limits: LoopLimits;
+    vars: Readonly<Record<string, string>>;
+}
+/** The values a run from one record would start with, which the form shows before anything is typed.
+ * @param record - Chosen record.
+ * @returns Its first round, last round and declared score and attempt budgets.
+ */
+export declare function loopRecordDefaults(record: LoopRecord): LoopLimits;
+/** The record list shown under the composer while `/loop` is being typed.
+ *
+ * It offers the same names and defaults the runner reads, so choosing from it cannot start a run
+ * other than the one the row describes.
+ * @param props - Matching records and the highlighted row.
+ * @returns The key line and up to six record rows.
+ */
+export declare function LoopMenu({ records, index }: {
+    records: readonly LoopRecord[];
+    index: number;
+}): import("react").JSX.Element;
+/** The loop parameter form: one record's variables and defaults, editable in place, then a Start.
+ *
+ * Values are replaced by typing over them, so no flag has to be remembered and every default stays
+ * visible until it is changed. A record variable is free text because it is a path or a target, not a
+ * number; the four limits share the command line's own validation. Leaving a row — with Enter or with
+ * an arrow — commits what was typed, so no box needs its own confirmation and Start reads the values
+ * as displayed. The run starts only from the Start row, so no keystroke that edits a value can launch
+ * it by accident. The form stays readable and escapable even when the host is busy or gone; only Start
+ * is unavailable then.
+ * @param props - The chosen record, whether a run may start now, and the three row actions.
+ * @returns The form.
+ */
+export declare function LoopDialog({ record, enabled, onStart, onBack, onClose }: {
+    record: LoopRecord;
+    enabled: boolean;
+    onStart(run: LoopRun): void;
+    onBack(): void;
+    onClose(): void;
+}): import("react").JSX.Element;

package/dist/ui/dialogs/loop.js

@@ -0,0 +1,224 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The `/loop` record list and the parameter form that confirms a chosen record's defaults. */
+import { useMemo, useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { validLoopOption } from "../../slash/parse.js";
+import { safeText } from "../../text.js";
+import { useCopyMode } from "../copy-mode.js";
+import { useTheme } from "../theme/index.js";
+const FIELDS = [
+    { field: 'from', label: 'From', hint: 'first round, 1 or more' },
+    { field: 'to', label: 'To', hint: 'last round, at least From' },
+    { field: 'score', label: 'Pass', hint: 'passing score, 0–10' },
+    { field: 'tries', label: 'Tries', hint: 'attempts per round, 1 or more' },
+];
+/** The values a run from one record would start with, which the form shows before anything is typed.
+ * @param record - Chosen record.
+ * @returns Its first round, last round and declared score and attempt budgets.
+ */
+export function loopRecordDefaults(record) {
+    return { from: 1, to: record.steps, score: record.defaultScore, tries: record.defaultTries };
+}
+/** The form's rows for one record: its own variables first, then the shared run limits.
+ *
+ * The record's variables lead because they are why this record's form was opened at all: the document
+ * under review is the decision that matters most, and it is not something the command line spells out.
+ * @param record - Chosen record.
+ * @returns The ordered rows.
+ */
+function rowsFor(record) {
+    return [
+        { kind: 'start' },
+        ...Object.keys(record.vars).map(name => ({ kind: 'var', name })),
+        ...FIELDS.map(spec => ({ kind: 'field', spec })),
+        { kind: 'back' },
+    ];
+}
+/** Columns the label occupies, so the values line up whatever names a record declares.
+ * @param rows - Rows being rendered.
+ * @returns One past the longest label.
+ */
+function labelWidth(rows) {
+    const longest = Math.max(0, ...rows.map(row => row.kind === 'field' ? row.spec.label.length
+        : row.kind === 'var' ? row.name.length : 0));
+    return Math.max(5, longest) + 1;
+}
+/** The record list shown under the composer while `/loop` is being typed.
+ *
+ * It offers the same names and defaults the runner reads, so choosing from it cannot start a run
+ * other than the one the row describes.
+ * @param props - Matching records and the highlighted row.
+ * @returns The key line and up to six record rows.
+ */
+export function LoopMenu({ records, index }) {
+    const theme = useTheme();
+    const start = Math.max(0, index - 5);
+    return _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Loop records \u00B7 \u2191 \u2193 select \u00B7 Enter confirm defaults \u00B7 Tab finish the name \u00B7 Esc close" }), records.slice(start, start + 6).map((record, offset) => {
+                const current = start + offset === index;
+                // The record's own inputs come before the artifact file: they are what the form will edit, and
+                // the first thing a narrow row must not lose.
+                const vars = Object.entries(record.vars).map(([name, value]) => `${name} ${value}`).join(' · ');
+                const target = vars === '' ? '' : ` · ${vars}`;
+                const artifact = record.artifact === undefined ? '' : ` · ${record.artifact}`;
+                return _jsxs(Text, { color: current ? theme.accent : undefined, wrap: "truncate-end", children: [current ? '❯ ' : '  ', record.name, " \u00B7 ", record.title, " \u00B7 ", record.steps, " rounds \u00B7 pass ", record.defaultScore, " \u00B7 \u2264", record.defaultTries, " tries", target, artifact] }, record.name);
+            })] });
+}
+/** The loop parameter form: one record's variables and defaults, editable in place, then a Start.
+ *
+ * Values are replaced by typing over them, so no flag has to be remembered and every default stays
+ * visible until it is changed. A record variable is free text because it is a path or a target, not a
+ * number; the four limits share the command line's own validation. Leaving a row — with Enter or with
+ * an arrow — commits what was typed, so no box needs its own confirmation and Start reads the values
+ * as displayed. The run starts only from the Start row, so no keystroke that edits a value can launch
+ * it by accident. The form stays readable and escapable even when the host is busy or gone; only Start
+ * is unavailable then.
+ * @param props - The chosen record, whether a run may start now, and the three row actions.
+ * @returns The form.
+ */
+export function LoopDialog({ record, enabled, onStart, onBack, onClose }) {
+    const theme = useTheme();
+    const copyMode = useCopyMode();
+    const defaults = loopRecordDefaults(record);
+    const rows = useMemo(() => rowsFor(record), [record]);
+    const width = useMemo(() => labelWidth(rows), [rows]);
+    const [row, setRow] = useState(0);
+    const [values, setValues] = useState(defaults);
+    const [vars, setVars] = useState({ ...record.vars });
+    const [edit, setEdit] = useState();
+    const [error, setError] = useState();
+    const current = rows[Math.min(row, rows.length - 1)];
+    /** Validate and apply the selected editable row's buffer.
+     *
+     * Leaving a row takes its value with it, so no box needs its own Enter: an arrow to the next row
+     * commits what was typed, and Start then reads the committed values. A value that cannot be used
+     * keeps the cursor on its row and says why, so nothing is dropped silently.
+     * @returns True when it is safe to leave the row.
+     */
+    const applyEdit = () => {
+        if (edit === undefined || current.kind === 'start' || current.kind === 'back')
+            return true;
+        if (current.kind === 'var') {
+            const value = edit.trim();
+            if (value === '') {
+                setError(`${current.name}: a value is required`);
+                return false;
+            }
+            if (value !== vars[current.name])
+                setVars({ ...vars, [current.name]: value });
+            setEdit(undefined);
+            setError(undefined);
+            return true;
+        }
+        // Nothing typed (or the value erased) leaves the field as it was rather than reading `''` as 0.
+        if (edit === '') {
+            setEdit(undefined);
+            setError(undefined);
+            return true;
+        }
+        const parsed = Number(edit);
+        if (!validLoopOption(current.spec.field, parsed)) {
+            setError(`${current.spec.label}: ${current.spec.hint}`);
+            return false;
+        }
+        const next = { ...values, [current.spec.field]: parsed };
+        if (next.to < next.from) {
+            setError('To must be at least From');
+            return false;
+        }
+        setValues(next);
+        setEdit(undefined);
+        setError(undefined);
+        return true;
+    };
+    const move = (next) => {
+        if (!applyEdit())
+            return;
+        setRow(Math.max(0, Math.min(rows.length - 1, next)));
+        setEdit(undefined);
+        setError(undefined);
+    };
+    useInput((input, key) => {
+        if (key.eventType === 'release')
+            return;
+        if (key.escape) {
+            if (edit !== undefined) {
+                setEdit(undefined);
+                setError(undefined);
+            }
+            else
+                onClose();
+            return;
+        }
+        if (key.upArrow) {
+            move(row - 1);
+            return;
+        }
+        if (key.downArrow) {
+            move(row + 1);
+            return;
+        }
+        if (current.kind === 'var') {
+            const { name } = current;
+            if (key.backspace || key.delete) {
+                setEdit((edit ?? vars[name] ?? '').slice(0, -1));
+                setError(undefined);
+                return;
+            }
+            // A variable is a path or a target, so anything printable goes in; control bytes never do.
+            const typed = input.replace(/[\u0000-\u001f\u007f]/g, '');
+            if (typed !== '' && !key.ctrl && !key.meta) {
+                setEdit(edit === undefined ? typed : edit + typed);
+                setError(undefined);
+                return;
+            }
+            if (key.return)
+                move(row + 1);
+            return;
+        }
+        if (current.kind === 'field') {
+            const { field } = current.spec;
+            if (key.backspace || key.delete) {
+                setEdit((edit ?? String(values[field])).slice(0, -1));
+                setError(undefined);
+                return;
+            }
+            if (/^[0-9.]$/.test(input)) {
+                setEdit(edit === undefined ? input : edit + input);
+                setError(undefined);
+                return;
+            }
+            if (key.return)
+                move(row + 1);
+            return;
+        }
+        if (!key.return)
+            return;
+        if (current.kind === 'back') {
+            onBack();
+            return;
+        }
+        if (!enabled) {
+            setError('Cannot start: the host is busy or offline');
+            return;
+        }
+        if (values.to < values.from) {
+            setError('To must be at least From');
+            return;
+        }
+        onStart({ limits: values, vars });
+    }, { isActive: !copyMode });
+    return _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Text, { bold: true, children: ["Run loop record \u00B7 ", safeText(record.name), " \u00B7 Esc close"] }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [record.steps, " rounds", record.artifact === undefined ? '' : ` · ${safeText(record.artifact)}`, " \u00B7 \u2191 \u2193 to a row, then type"] }), rows.map((item, index) => {
+                const selected = index === row;
+                const cursor = selected ? '❯ ' : '  ';
+                if (item.kind === 'start' || item.kind === 'back')
+                    return _jsxs(Text, { color: selected ? theme.accent : undefined, children: [cursor, item.kind === 'start' ? 'Start run' : '← Choose another record'] }, item.kind);
+                if (item.kind === 'var') {
+                    const value = vars[item.name] ?? '';
+                    const shown = selected && edit !== undefined ? edit : value;
+                    return _jsxs(Text, { color: selected ? theme.accent : undefined, children: [cursor, item.name.padEnd(width), selected && edit !== undefined ? _jsx(Text, { inverse: true, children: shown || ' ' }) : shown, value === record.vars[item.name] ? null : _jsxs(Text, { dimColor: true, children: [" \u00B7 default ", record.vars[item.name]] })] }, `var:${item.name}`);
+                }
+                const { field, label } = item.spec;
+                const shown = selected && edit !== undefined ? edit : String(values[field]);
+                return _jsxs(Text, { color: selected ? theme.accent : undefined, children: [cursor, label.padEnd(width), selected && edit !== undefined ? _jsx(Text, { inverse: true, children: shown || ' ' }) : shown, values[field] === defaults[field] ? null : _jsxs(Text, { dimColor: true, children: [" \u00B7 default ", defaults[field]] })] }, `field:${field}`);
+            }), error !== undefined && _jsx(Text, { color: theme.colors.error, children: safeText(error) }), _jsx(Text, { dimColor: true, children: "Enter edit a value / start \u00B7 type to replace \u00B7 Esc close" })] });
+}