@aiwayds/dsh-tui-pi 2.9.1 → 2.11.0

package/lib/stop-dialog.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The stop-everything confirmation dialog — the gate behind the double-Esc
+ * stop gesture.
+ *
+ * "Stop all LLM work" is the widest lever the TUI has: it cancels the main
+ * turn AND every live subagent (background/continuable children survive a
+ * plain parent cancel, so the stop enumerates and cancels each). That reach
+ — and the fact that the gesture is two Esc presses, the same key users
+ * mash to close popups — is exactly why the second Esc opens THIS dialog
+ * instead of firing: the arm notice plus an explicit, read-before-confirm
+ * panel is the misfire guard. The old 200ms auto-fire window confirmed the
+ * *timing* of the press, not the *intent*; a dialog states what will die
+ * and waits for Enter.
+ *
+ * Mirrors the preset-switch dialog's pure-reducer split (src/preset-dialog.ts,
+ * itself modeled on src/repair-dialog.ts) so the decision matrix stays
+ * unit-testable without a terminal. Two ways out: STOP (Enter on the
+ * preselected row, or `1`) and CANCEL (Esc, `2`, or Enter on row 2). While
+ * the overlay is open the keymap yields every app key to it, so a third Esc
+ * lands in the dialog (cancel), never straight at the task. Framing/focus
+ * follow the shared overlay contract: PanelHost framing, close re-focuses
+ * the CURRENT editor instance through `restoreFocus`.
+ */
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+import { type TuiTheme } from './theme/index.ts';
+/** The two choices in display order; index 0 (STOP) is preselected. */
+export declare const STOP_CONFIRM_OPTION_IDS: ReadonlyArray<'stop' | 'cancel'>;
+/** What the dialog says: the title plus the "what is running" body points. */
+export interface StopConfirmWording {
+    title: string;
+    body: readonly string[];
+}
+/**
+ * The dialog wording for one stop moment. The body names exactly what will
+ * be cancelled — the main turn when mid-turn, the running-subagent count —
+ * because the dialog is the only place the blast radius is stated before
+ * the user commits. Always ends with the reassurance that queued prompts
+ * survive (`keepInbox`) and the session stays resumable.
+ */
+export declare function stopConfirmWording(mainRunning: boolean, runningChildren: number): StopConfirmWording;
+/** The fixed option rows for one wording. */
+export declare function stopConfirmOptions(): ReadonlyArray<{
+    id: 'stop' | 'cancel';
+    text: string;
+}>;
+/** Accent-BOLD dialog title. */
+export declare function stopConfirmTitle(wording: StopConfirmWording): string;
+/** Footer hint — hardcoded like every other panel footer (English-only). */
+export declare const STOP_CONFIRM_FOOTER = "\u2191\u2193 select \u00B7 1/2 pick \u00B7 Enter confirm \u00B7 Esc keep running";
+/**
+ * Pure dialog state: which row is highlighted, and the terminal outcome.
+ * Same shape as the preset dialog's state.
+ */
+export interface StopConfirmState {
+    selected: number;
+    /**
+     * Set once by a terminal key: `'confirm'` (Enter on a selection) or
+     * `'cancel'` (Esc). Further input is ignored afterwards.
+     */
+    settled?: 'confirm' | 'cancel';
+}
+export declare function initialStopConfirmState(): StopConfirmState;
+/**
+ * Apply one raw key sequence to the dialog state. Unknown keys are no-ops;
+ * anything after a settle is ignored (single terminal outcome guard).
+ */
+export declare function updateStopConfirm(state: StopConfirmState, data: string): StopConfirmState;
+/** Resolved dialog outcome: `'stop'`, or undefined on cancel. */
+export declare function stopConfirmOutcome(state: StopConfirmState): 'stop' | undefined;
+/**
+ * The framed overlay component. Renders the title, the wrapped body points
+ * and the two option rows; every key goes through
+ * {@link updateStopConfirm}, and the first terminal key fires `onFinish`
+ * exactly once.
+ */
+export declare class StopConfirmPanel implements Component {
+    private readonly theme;
+    private readonly wording;
+    private readonly onFinish;
+    private readonly requestRenderFn;
+    private state;
+    constructor(theme: TuiTheme, wording: StopConfirmWording, onFinish: (outcome: 'stop' | undefined) => void, requestRender: () => void);
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(data: string): void;
+}
+/**
+ * Open the stop-everything confirmation dialog. Resolves `'stop'` when the
+ * user confirmed, or `'cancelled'` (Esc / row 2 / an overlay that failed to
+ * mount — treated as cancel so a half-mounted dialog can never imply
+ * consent). Closing always hands focus back through `restoreFocus` before
+ * the promise settles.
+ */
+export declare function openStopConfirmDialog(tui: TUI, theme: TuiTheme, mainRunning: boolean, runningChildren: number, restoreFocus: () => void): Promise<'stop' | 'cancelled'>;

package/lib/stop-dialog.js

@@ -0,0 +1,194 @@
+/**
+ * The stop-everything confirmation dialog — the gate behind the double-Esc
+ * stop gesture.
+ *
+ * "Stop all LLM work" is the widest lever the TUI has: it cancels the main
+ * turn AND every live subagent (background/continuable children survive a
+ * plain parent cancel, so the stop enumerates and cancels each). That reach
+ — and the fact that the gesture is two Esc presses, the same key users
+ * mash to close popups — is exactly why the second Esc opens THIS dialog
+ * instead of firing: the arm notice plus an explicit, read-before-confirm
+ * panel is the misfire guard. The old 200ms auto-fire window confirmed the
+ * *timing* of the press, not the *intent*; a dialog states what will die
+ * and waits for Enter.
+ *
+ * Mirrors the preset-switch dialog's pure-reducer split (src/preset-dialog.ts,
+ * itself modeled on src/repair-dialog.ts) so the decision matrix stays
+ * unit-testable without a terminal. Two ways out: STOP (Enter on the
+ * preselected row, or `1`) and CANCEL (Esc, `2`, or Enter on row 2). While
+ * the overlay is open the keymap yields every app key to it, so a third Esc
+ * lands in the dialog (cancel), never straight at the task. Framing/focus
+ * follow the shared overlay contract: PanelHost framing, close re-focuses
+ * the CURRENT editor instance through `restoreFocus`.
+ */
+import { getKeybindings } from '@earendil-works/pi-tui';
+import { PanelHost, panelThemeFns } from "./panels.js";
+import { BOLD, RESET, ansiFg } from "./theme/index.js";
+import { clipToWidth, wrapText } from "./text.js";
+/** The two choices in display order; index 0 (STOP) is preselected. */
+export const STOP_CONFIRM_OPTION_IDS = ['stop', 'cancel'];
+/**
+ * The dialog wording for one stop moment. The body names exactly what will
+ * be cancelled — the main turn when mid-turn, the running-subagent count —
+ * because the dialog is the only place the blast radius is stated before
+ * the user commits. Always ends with the reassurance that queued prompts
+ * survive (`keepInbox`) and the session stays resumable.
+ */
+export function stopConfirmWording(mainRunning, runningChildren) {
+    const running = [];
+    if (mainRunning)
+        running.push('the main turn is generating');
+    if (runningChildren > 0) {
+        running.push(`${runningChildren} subagent${runningChildren === 1 ? ' is' : 's are'} running`);
+    }
+    const situation = running.length > 0
+        ? `Right now ${running.join(' and ')}.`
+        : 'Nothing is running right now.';
+    return {
+        title: '● Stop all LLM work?',
+        body: [
+            situation,
+            'Confirming cancels the main turn and every running subagent. '
+                + 'Queued messages are kept and the session stays resumable.',
+        ],
+    };
+}
+/** The fixed option rows for one wording. */
+export function stopConfirmOptions() {
+    return [
+        { id: 'stop', text: 'Stop everything — cancel the main turn and all subagents' },
+        { id: 'cancel', text: 'Cancel — keep everything running' },
+    ];
+}
+/** Accent-BOLD dialog title. */
+export function stopConfirmTitle(wording) {
+    return wording.title;
+}
+/** Footer hint — hardcoded like every other panel footer (English-only). */
+export const STOP_CONFIRM_FOOTER = '↑↓ select · 1/2 pick · Enter confirm · Esc keep running';
+export function initialStopConfirmState() {
+    return { selected: 0 };
+}
+/**
+ * Apply one raw key sequence to the dialog state. Unknown keys are no-ops;
+ * anything after a settle is ignored (single terminal outcome guard).
+ */
+export function updateStopConfirm(state, data) {
+    if (state.settled !== undefined)
+        return state;
+    const kb = getKeybindings();
+    if (kb.matches(data, 'tui.select.cancel'))
+        return { ...state, settled: 'cancel' };
+    if (kb.matches(data, 'tui.input.submit'))
+        return { ...state, settled: 'confirm' };
+    if (kb.matches(data, 'tui.select.up')) {
+        return { ...state, selected: Math.max(0, state.selected - 1) };
+    }
+    if (kb.matches(data, 'tui.select.down')) {
+        return { ...state, selected: Math.min(STOP_CONFIRM_OPTION_IDS.length - 1, state.selected + 1) };
+    }
+    // Digit direct-select (1-based): selects the row, Enter still confirms —
+    // same select-then-confirm split as the preset dialog.
+    const digit = /^([1-9])$/.exec(data);
+    if (digit !== null) {
+        const index = Number(digit[1]) - 1;
+        if (index < STOP_CONFIRM_OPTION_IDS.length)
+            return { ...state, selected: index };
+    }
+    return state;
+}
+/** Resolved dialog outcome: `'stop'`, or undefined on cancel. */
+export function stopConfirmOutcome(state) {
+    if (state.settled !== 'confirm')
+        return undefined;
+    return STOP_CONFIRM_OPTION_IDS[state.selected] === 'stop' ? 'stop' : undefined;
+}
+/**
+ * The framed overlay component. Renders the title, the wrapped body points
+ * and the two option rows; every key goes through
+ * {@link updateStopConfirm}, and the first terminal key fires `onFinish`
+ * exactly once.
+ */
+export class StopConfirmPanel {
+    theme;
+    wording;
+    onFinish;
+    requestRenderFn;
+    state = initialStopConfirmState();
+    constructor(theme, wording, onFinish, requestRender) {
+        this.theme = theme;
+        this.wording = wording;
+        this.onFinish = onFinish;
+        this.requestRenderFn = requestRender;
+    }
+    invalidate() { }
+    render(width) {
+        const fns = panelThemeFns(this.theme);
+        const wrap = Math.max(2, width - 2);
+        // Word-wrap the body FIRST, then paint (iron rule: width math runs on
+        // plain text, ANSI goes on after clipping).
+        const lines = [
+            fns.accent(BOLD + clipToWidth(stopConfirmTitle(this.wording), wrap) + RESET),
+            ...this.wording.body.flatMap(point => wrapText(point, wrap).map(segment => fns.muted(clipToWidth(segment, wrap)))),
+            '',
+        ];
+        const options = stopConfirmOptions();
+        for (let i = 0; i < options.length; i++) {
+            const option = options[i];
+            const marker = i === this.state.selected ? '▸' : ' ';
+            const row = clipToWidth(`${marker} ${i + 1}. ${option.text}`, wrap);
+            lines.push(i === this.state.selected
+                ? ansiFg(this.theme.palette.accent) + BOLD + row + RESET
+                : fns.muted(row));
+        }
+        lines.push('');
+        lines.push(fns.subtle(clipToWidth(STOP_CONFIRM_FOOTER, wrap)));
+        return lines;
+    }
+    handleInput(data) {
+        const previous = this.state;
+        this.state = updateStopConfirm(this.state, data);
+        if (this.state === previous)
+            return;
+        if (this.state.settled === undefined) {
+            this.requestRenderFn();
+            return;
+        }
+        this.onFinish(stopConfirmOutcome(this.state));
+    }
+}
+/**
+ * Open the stop-everything confirmation dialog. Resolves `'stop'` when the
+ * user confirmed, or `'cancelled'` (Esc / row 2 / an overlay that failed to
+ * mount — treated as cancel so a half-mounted dialog can never imply
+ * consent). Closing always hands focus back through `restoreFocus` before
+ * the promise settles.
+ */
+export function openStopConfirmDialog(tui, theme, mainRunning, runningChildren, restoreFocus) {
+    return new Promise(resolve => {
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(outcome);
+        };
+        // A half-mounted overlay must not strand the keyboard: PanelHost's
+        // onError closes + calls restoreFocus, then we settle as cancelled.
+        const host = new PanelHost(tui, theme, () => {
+            restoreFocus();
+            settle('cancelled');
+        });
+        const finish = (outcome) => {
+            host.close();
+            restoreFocus();
+            settle(outcome === 'stop' ? 'stop' : 'cancelled');
+        };
+        const panel = new StopConfirmPanel(theme, stopConfirmWording(mainRunning, runningChildren), outcome => finish(outcome), () => tui.requestRender());
+        // maxHeight is a hard slice in pi-tui: title + 2 wrapped body points +
+        // 2 options + footer ≈ 8 content rows + 4 frame rows; the preset
+        // dialog's 75%-of-24-rows headroom covers it with room to spare.
+        host.open(panel, '70%', '75%');
+    });
+}
+//# sourceMappingURL=stop-dialog.js.map

package/lib/stop-dialog.js.map

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

package/lib/subagent-policy.d.ts

@@ -7,28 +7,32 @@
  * - `maxAgents` caps concurrent live children. A `tools.guard` registered on
  *   the plugin root ctx denies model-facing spawn tools once the bridge's
  *   live child count meets the cap. The live-child COUNT covers every child
- *   in the process, but like `disableSubagent` the DENIAL is scoped to
- *   sessions this bridge created or resumed (`TUI_SURFACE_KEY`): unmarked
- *   callers fail open. The workflow/ralph fan-out bypasses the tool pipeline (its worker thread
- *   spawns through the subagent provider directly), so a `subagent/start`
- *   listener prunes any newcomer that slips past the guard.
+ *   in the process, but the DENIAL scope is "belongs to this TUI": a caller
+ *   carrying the surface marker, or any live descendant of a marked root
+ *   (the ancestor walk closes the host-created-children hole). Foreign
+ *   roots fail open. The workflow/ralph fan-out bypasses the tool pipeline
+ *   (its worker thread spawns through the subagent provider directly), so a
+ *   `subagent/start` listener prunes any newcomer that slips past the guard
+ *   — same ownership scope, decided by the child's parent ancestry.
  * - `disableSubagent` disables the plain native `subagent` tool: its calls
- *   are denied for every TUI session (and it is hidden from the main
+ *   are denied for every TUI-scoped caller (and it is hidden from the main
  *   agent's catalog), so delegation goes through registered agent
  *   definitions (`~/.dsh/agents/*.md` via the registry's `use_agent`).
- *   `subagent_fork`, `workflow` and `ralph` stay available. Enforcement is
- *   scoped to sessions this bridge created or resumed (see
- *   `TUI_SURFACE_KEY`): the guard reads the calling agent's surface marker
- *   and FAILS OPEN for everything else, so a future web-profile deployment
- *   of this plugin never disables the native tool inside Web UI sessions.
+ *   `subagent_fork`, `workflow` and `ralph` stay available.
  * - `maxRounds` caps a child's assistant messages (each LLM round-trip is
- *   one "round"): on the bridge's `onRoundCount` the policy injects one
- *   plugin-sourced user message telling the child to wrap up — via `steer()`
- *   while the child runs (consumed at the next STEP boundary, the very next
- *   LLM round-trip) or `followup()` when idle, mirroring the Ctrl+G steer
- *   routing. The child's log shows the injection with a `⚡` marker on the
- *   compact line and in the subagent viewer, so an ignored wrap-up is
- *   visible, not silent.
+ *   one "round") through a TWO-STAGE ladder. Stage 1: at the cap — the
+ *   per-agent tier when the child's label resolves to an agent .md
+ *   `maxRounds` frontmatter key, else the global setting — the policy
+ *   injects one plugin-sourced user message telling the child to wrap up
+ *   (`steer()` while running, `followup()` when idle). Stage 2: after
+ *   `maxRoundsGrace` further rounds, `state.cancelChild` force-stops the
+ *   run — code, not persuasion; a one-shot run settles `aborted` with its
+ *   partial output in the parent's tool result, a continuable child's
+ *   session and inbox survive for resume. `grace: 0` collapses the ladder
+ *   to the historical warn-only behavior. Every injection carries a `⚡`
+ *   marker in the compact line and the subagent viewer; every hard stop is
+ *   reported to the bridge for the `⏻` marker — an ignored wrap-up is
+ *   visible, and so is its enforcement.
  */
 import type { Context } from '@deepseek-ai/cordis';
 /**
@@ -93,9 +97,11 @@ export declare function markTuiSurface(agentCtx: Context): void;
  * English and directive on purpose: it is a policy instruction to the child
  * LLM, and a soft "please summarize" (the earlier one-line Chinese request)
  * was routinely ignored while the child kept calling tools. It names the
- * limit, forbids further tool calls, and demands a final-answer summary.
+ * limit, forbids further tool calls, and demands a final-answer summary —
+ * and, with a positive grace window, warns that the run is force-stopped
+ * if the summary does not land within it.
  */
-export declare function wrapupMessage(maxRounds: number): string;
+export declare function wrapupMessage(maxRounds: number, grace: number): string;
 /** The policy's live backstop — the bridge's per-child accessors. */
 export interface SubagentPolicyState {
     /** Current live (not settled) children — the count the `maxAgents` guard caps. */
@@ -107,11 +113,38 @@ export interface SubagentPolicyState {
     getRoundCount(childId: string): number;
     /** Whether one child already settled — a settled child is never re-awakened. */
     isSettled(childId: string): boolean;
+    /**
+     * Forcibly stop one live child (the everything-stop's per-child idiom,
+     * `cancel({kind:'user'}, {keepInbox:true})`): a one-shot run settles
+     * `aborted` (the parent's tool call reports the cancellation with the
+     * partial output), a continuable child's run stops while its session and
+     * inbox survive for later resume. `false` when nothing live was found.
+     */
+    cancelChild(childId: string): boolean;
+}
+/**
+ * A hard stop the policy executed on one child, surfaced through the policy
+ * handle for the bridge to fold into the child's view (the `⏻` marker).
+ */
+export interface HardStopRecord {
+    /** The child session id the stop was issued to. */
+    readonly childId: string;
+    /** Round count at which the stop fired (`cap + grace`). */
+    readonly round: number;
+    /** The cap that was exceeded (per-agent when one resolved, else global). */
+    readonly cap: number;
+    /** The grace window that was exhausted. */
+    readonly grace: number;
 }
 /** The running policy: the bridge's `onRoundCount` sink plus the teardown. */
 export interface SubagentPolicy {
     /** Called by the bridge whenever one child produced another assistant message. */
     onRoundCount(childId: string, count: number): void;
+    /**
+     * Report sink for hard stops: wired by the host to the bridge's fold so a
+     * force-stopped child shows its `⏻` marker everywhere the view renders.
+     */
+    onHardStop?(record: HardStopRecord): void;
     /** Unwind the guard and event listeners. */
     dispose(): void;
 }
@@ -122,8 +155,12 @@ export interface SubagentPolicy {
  * is defensive: a settings-less deployment resolves the defaults, so the
  * policy still enforces its documented caps.
  * @param state - the host's live view (bridge.getLiveChildren /
- * bridge.getRoundCount). The guard and the round injection read it at every
+ * bridge.getRoundCount). The guard and the round ladder read it at every
  * decision — no snapshot, no watch.
+ * @param resolveAgentCap - the per-agent round cap lookup (agent .md
+ * frontmatter `maxRounds` via the registry contract). `undefined`/throwing
+ * resolutions fall back to the global cap, never widen it. Omitted = the
+ * global cap always applies.
  * @returns the policy handle wired to the bridge's `onRoundCount`.
  */
-export declare function applySubagentPolicy(ctx: Context, state: SubagentPolicyState): SubagentPolicy;
+export declare function applySubagentPolicy(ctx: Context, state: SubagentPolicyState, resolveAgentCap?: (label: string) => number | undefined): SubagentPolicy;