@aiwayds/dsh-tui-pi 1.0.8 → 1.1.0

package/README.md

@@ -116,6 +116,7 @@ GitHub light/dark palettes, hot-switched with `/theme`; `auto` detects your term
 | `/session` | Read-only info: id, cwd, model, token usage, event count. |
 | `/resume` | Pick a persisted session (newest first), validate its log, restore it. |
 | `/new` | Detach the current session; the next prompt opens a fresh one. |
+| `/btw` | By-the-way side question while the main task runs — one tool-less model call over a recent-conversation snapshot, streamed into a temporary overlay. Never kept in the session; idle main line refuses it; `--model provider/model` overrides the route; bare `/btw` reopens the last answer (`DSH_TUI_BTW_CONTEXT_MESSAGES` sizes the snapshot). |
 | `/settings` | Text-based settings browser (namespaces, schema walk, secrets masked). |
 | `/export` | Write the current session log as JSONL. |
 | `/permission` | Permission-preset picker (read-only / workspace-write / danger-full-access). |

package/README.zh-CN.md

@@ -116,6 +116,7 @@ GitHub 明/暗配色，`/theme` 热切换；`auto` 检测你的终端并跟随
 | `/session` | 只读信息：id、cwd、model、token 用量、事件数。 |
 | `/resume` | 选择持久化的 session（新的在前），校验日志后恢复。 |
 | `/new` | 分离当前 session；下一条 prompt 开启新会话。 |
+| `/btw` | 主线任务运行中的「顺带一问」——一次无工具的单次模型调用（带最近对话快照），答案流式呈现在临时浮层里。不进会话记录；主线空闲时拒绝使用；`--model provider/model` 临时换路由；空参 `/btw` 回看上一条问答（`DSH_TUI_BTW_CONTEXT_MESSAGES` 控制快照条数）。 |
 | `/settings` | 文本式设置浏览器（命名空间、schema 遍历、密钥脱敏）。 |
 | `/export` | 把当前会话日志写成 JSONL。 |
 | `/permission` | 权限预设选择器（read-only / workspace-write / danger-full-access）。 |

package/lib/btw-overlay.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The btw overlay — framed floating panel presenting one side-call exchange
+ * (CONTEXT.md: Btw overlay). Bound to a single BtwRunState object: a live
+ * run is the controller's own mutable state (setText streaming, Markdown
+ * once on settle), a review is a plain snapshot object from the Last-btw
+ * slot. Esc closes through the shared overlay focus contract — closing
+ * never stops the run; it delivers into the slot regardless.
+ *
+ * Pure rendering + key routing only; all decisions live in btw.ts. This file
+ * is the PanelHost glue and is exercised on a terminal, not in unit tests
+ * (same split as route-dialog).
+ */
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+import { type TuiTheme } from './theme/index.ts';
+import type { BtwController, BtwRunState } from './btw.ts';
+export declare class BtwOverlayPanel implements Component {
+    private readonly run;
+    private readonly controller;
+    private readonly theme;
+    private readonly onClose;
+    private readonly question;
+    /** Streaming view — one Text, setText per change (AGENTS.md #2). */
+    private readonly answerText;
+    private streamedText;
+    /** Built once when the run settles; never re-parsed per frame. */
+    private finalMarkdown;
+    constructor(run: BtwRunState, controller: BtwController, theme: () => TuiTheme, onClose: () => void);
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(data: string): void;
+}
+/**
+ * Overlay lifecycle for btw runs: `open(run)` shows/swaps the framed panel
+ * bound to that run state; Esc and cancelAll close it through restoreFocus.
+ * Two-step wiring — construct first, `attach(controller)` once it exists
+ * (the panel needs the controller for the queued count; the controller needs
+ * these callbacks at construction).
+ */
+export declare class BtwOverlayWire {
+    private readonly tui;
+    private readonly theme;
+    private readonly restoreFocus;
+    private host;
+    private controller;
+    constructor(deps: {
+        tui: TUI;
+        theme: () => TuiTheme;
+        restoreFocus: () => void;
+    });
+    attach(controller: BtwController): void;
+    /** Called by the controller for every launched or reviewed run. */
+    open(run: BtwRunState): void;
+    /** Called by cancelAll — the overlay's run is gone either way. */
+    requestClose(): void;
+}

package/lib/btw-overlay.js

@@ -0,0 +1,153 @@
+/**
+ * The btw overlay — framed floating panel presenting one side-call exchange
+ * (CONTEXT.md: Btw overlay). Bound to a single BtwRunState object: a live
+ * run is the controller's own mutable state (setText streaming, Markdown
+ * once on settle), a review is a plain snapshot object from the Last-btw
+ * slot. Esc closes through the shared overlay focus contract — closing
+ * never stops the run; it delivers into the slot regardless.
+ *
+ * Pure rendering + key routing only; all decisions live in btw.ts. This file
+ * is the PanelHost glue and is exercised on a terminal, not in unit tests
+ * (same split as route-dialog).
+ */
+import { getKeybindings, Markdown, Text } from '@earendil-works/pi-tui';
+import { PanelHost, panelThemeFns } from "./panels.js";
+import { BOLD, RESET, ansiFg } from "./theme/index.js";
+import { clipToWidth } from "./text.js";
+/**
+ * Answer row budget, sized so the panel NEVER overflows the 24-row e2e
+ * terminal (AGENTS.md matrix floor): maxHeight '80%' ≈ 19 rows there, the
+ * FramedOverlay chrome eats 4, fixed rows are 4 (title + 2 blanks + status),
+ * and the question rows come out of the remainder per frame — an overlay
+ * taller than that just shows a roomier answer. Overflow of the answer
+ * itself is a named tail window (the newest rows stay visible).
+ */
+const BTW_ANSWER_BASE_BUDGET = 11;
+const BTW_ANSWER_MIN_BUDGET = 3;
+export class BtwOverlayPanel {
+    run;
+    controller;
+    theme;
+    onClose;
+    question;
+    /** Streaming view — one Text, setText per change (AGENTS.md #2). */
+    answerText;
+    streamedText = '';
+    /** Built once when the run settles; never re-parsed per frame. */
+    finalMarkdown;
+    constructor(run, controller, theme, onClose) {
+        this.run = run;
+        this.controller = controller;
+        this.theme = theme;
+        this.onClose = onClose;
+        this.question = new Text(run.question, 1, 0);
+        this.answerText = new Text('', 1, 0);
+    }
+    invalidate() { }
+    render(width) {
+        const fns = panelThemeFns(this.theme());
+        const wrap = Math.max(2, width - 2);
+        const questionLines = this.question.render(wrap);
+        const budget = Math.max(BTW_ANSWER_MIN_BUDGET, BTW_ANSWER_BASE_BUDGET - questionLines.length);
+        const lines = [
+            fns.accent(BOLD + clipToWidth(`⌘ btw — ${this.run.modelLabel}`, wrap) + RESET),
+            ...questionLines,
+            '',
+        ];
+        const queued = this.controller.queuedCount;
+        if (this.run.status === 'streaming') {
+            if (this.run.answerText !== this.streamedText) {
+                this.answerText.setText(this.run.answerText);
+                this.streamedText = this.run.answerText;
+            }
+            if (this.run.answerText !== '') {
+                lines.push(...tailWindow(this.answerText.render(wrap), budget, wrap));
+            }
+            else {
+                lines.push(fns.muted(clipToWidth('Thinking…', wrap)));
+            }
+            lines.push('');
+            lines.push(fns.subtle(clipToWidth(`Running alongside the main task · Esc close${queued > 0 ? ` · ${queued} queued` : ''}`, wrap)));
+            return lines;
+        }
+        if (this.run.status === 'error') {
+            lines.push(fns.muted(clipToWidth(`✘ ${this.run.error ?? 'btw failed.'}`, wrap)));
+        }
+        else if (this.run.answerText === '') {
+            lines.push(fns.muted(clipToWidth('(no answer text)', wrap)));
+        }
+        else {
+            if (this.finalMarkdown === undefined) {
+                // Parses ONCE on the settled answer — never per frame, per token.
+                this.finalMarkdown = new Markdown(this.run.answerText, 1, 0, this.theme().markdown, {
+                    color: text => ansiFg(this.theme().palette.fgDefault) + text + RESET,
+                });
+            }
+            lines.push(...tailWindow(this.finalMarkdown.render(wrap), budget, wrap));
+        }
+        lines.push('');
+        lines.push(fns.subtle(clipToWidth(`Not kept in the session · /btw reopens this answer${queued > 0 ? ` · ${queued} queued` : ''}`, wrap)));
+        return lines;
+    }
+    handleInput(data) {
+        if (getKeybindings().matches(data, 'tui.select.cancel'))
+            this.onClose();
+    }
+}
+/** Last rows that fit the budget; the hidden count is named above the tail. */
+function tailWindow(rendered, budget, wrap) {
+    if (rendered.length <= budget)
+        return rendered;
+    const hidden = rendered.length - budget;
+    return [clipToWidth(`… ${hidden} lines above`, wrap), ...rendered.slice(-budget)];
+}
+/**
+ * Overlay lifecycle for btw runs: `open(run)` shows/swaps the framed panel
+ * bound to that run state; Esc and cancelAll close it through restoreFocus.
+ * Two-step wiring — construct first, `attach(controller)` once it exists
+ * (the panel needs the controller for the queued count; the controller needs
+ * these callbacks at construction).
+ */
+export class BtwOverlayWire {
+    tui;
+    theme;
+    restoreFocus;
+    host;
+    controller;
+    constructor(deps) {
+        this.tui = deps.tui;
+        this.theme = deps.theme;
+        this.restoreFocus = deps.restoreFocus;
+    }
+    attach(controller) {
+        this.controller = controller;
+    }
+    /** Called by the controller for every launched or reviewed run. */
+    open(run) {
+        const controller = this.controller;
+        if (controller === undefined)
+            return;
+        // A failed PanelHost.open releases the keyboard exactly like a normal
+        // close (PanelHost calls onError first); the run itself is unaffected.
+        const close = () => {
+            this.host?.close();
+            this.host = undefined;
+            controller.setOverlayOpen(false);
+            this.restoreFocus();
+        };
+        this.host?.close();
+        this.host = new PanelHost(this.tui, this.theme(), close);
+        controller.setOverlayOpen(true);
+        this.host.open(new BtwOverlayPanel(run, controller, this.theme, close), '70%', '80%');
+    }
+    /** Called by cancelAll — the overlay's run is gone either way. */
+    requestClose() {
+        if (this.host !== undefined) {
+            this.host.close();
+            this.host = undefined;
+            this.controller?.setOverlayOpen(false);
+            this.restoreFocus();
+        }
+    }
+}
+//# sourceMappingURL=btw-overlay.js.map

package/lib/btw-overlay.js.map

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

package/lib/btw.d.ts

@@ -0,0 +1,224 @@
+/**
+ * /btw — by-the-way side questions (CONTEXT.md: Btw, Side call, Btw overlay,
+ * Last-btw slot, Queued btw).
+ *
+ * While the main agent is mid-turn, `/btw <question>` fires ONE tool-less
+ * one-shot model call over a read-only snapshot of the recent conversation
+ * and streams the answer into a framed overlay. The main line never sees it:
+ * nothing enters the session log, the inbox, or any main-line model request.
+ * The overlay is the only surface; closing it (Esc) does not stop the call —
+ * the finished exchange lands in the in-process Last-btw slot, reviewable
+ * via bare `/btw` until the process dies.
+ *
+ * Concurrency: at most one side call runs (BtwQueue); further submits queue
+ * behind it (bounded). Lifecycle: a main-line disruption — /new, /resume,
+ * a remote takeover, the stop gesture — cancels the running call and drops
+ * the queue; the caller wires `cancelAll` into those paths. Placement rationale:
+ * docs/adr/0001-btw-tui-owned-command.md.
+ *
+ * Split: pure decision layer here — arg parsing, snapshot assembly, the queue
+ * state machine, stream consumption and the controller, all over structural
+ * slices so the matrix runs without a terminal (test/btw.test.mjs). The
+ * overlay component + PanelHost glue live in btw-overlay.ts; the command
+ * wiring in index.ts.
+ */
+import { type Message, type ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+export declare const BTW_IDLE_NOTICE = "/btw answers alongside a running turn \u2014 the main line is idle, so just ask directly.";
+export declare const BTW_USAGE: string;
+export type ParsedBtwInput = {
+    kind: 'empty';
+} | {
+    kind: 'ok';
+    question: string;
+    modelOverride?: string;
+} | {
+    kind: 'error';
+    error: string;
+};
+/**
+ * Parse the text after `/btw`. Everything is the question except one
+ * optional `--model provider/model` override (extractable from anywhere in
+ * the line). No input at all → `'empty'` (review / usage hint); a `--model`
+ * flag without a question, or a value without a `/`, → `'error'`.
+ */
+export declare function parseBtwInput(rawInput: string | undefined): ParsedBtwInput;
+/** Structural input event — the subset of SessionEvent the snapshot needs. */
+export interface BtwSnapshotEvent {
+    readonly type: string;
+    readonly data: unknown;
+}
+/** Default recent-conversation messages carried into a side call. */
+export declare const BTW_SNAPSHOT_DEFAULT_MESSAGES = 6;
+/** Hard ceiling for the configurable snapshot size (env override clamp). */
+export declare const BTW_SNAPSHOT_MAX_MESSAGES = 50;
+/** Per-message text cap — the snapshot is context, not a transcript replay. */
+export declare const BTW_MAX_MESSAGE_CHARS = 4000;
+/**
+ * Resolve the snapshot size from the `DSH_TUI_BTW_CONTEXT_MESSAGES` env value:
+ * integer clamped to [0, BTW_SNAPSHOT_MAX_MESSAGES], anything else (unset,
+ * non-numeric) falls back to the default. 0 disables the snapshot — the side
+ * call then answers from the question alone.
+ */
+export declare function resolveSnapshotLimit(env: string | undefined): number;
+/**
+ * Project the last `limit` user/assistant text exchanges out of the session
+ * event log, oldest first. Tool calls, reasoning, usage and every
+ * non-message event are dropped; text-only fresh blocks keep each source
+ * message's identity (id/role/source) while shedding everything a tool-less
+ * call cannot use. Malformed event data is skipped, never thrown.
+ */
+export declare function buildBtwSnapshot(events: readonly BtwSnapshotEvent[], limit: number): Message[];
+/**
+ * The side-call message list: the snapshot in order, then the question as a
+ * plugin-sourced user message (it is not a real user turn of any session).
+ */
+export declare function buildBtwMessages(snapshot: readonly Message[], question: string): Message[];
+/** System prompt for the side call — no tools, snapshot is context only. */
+export declare const BTW_SYSTEM_PROMPT: string;
+/** Maximum queued btw requests while one is running. */
+export declare const BTW_QUEUE_CAP = 5;
+export interface BtwJob {
+    readonly question: string;
+    readonly modelOverride?: string;
+}
+export type BtwSubmitResult = {
+    kind: 'started';
+} | {
+    kind: 'queued';
+    position: number;
+} | {
+    kind: 'rejected';
+    reason: string;
+};
+/**
+ * Single-flight queue: one running btw, bounded FIFO behind it. The queue is
+ * the concurrency truth — the controller's view state is derived from it.
+ */
+export declare class BtwQueue {
+    private currentJob;
+    private readonly waiting;
+    get running(): boolean;
+    get queuedCount(): number;
+    submit(job: BtwJob): BtwSubmitResult;
+    /** Settle the current job; returns the next job to launch, if any. */
+    finishCurrent(): BtwJob | undefined;
+    cancelAll(): {
+        canceledRunning: boolean;
+        canceledQueued: number;
+    };
+}
+/**
+ * Structural stream chunk — the subset of dsh-llm's StreamChunk a side call
+ * consumes (text deltas for the live view, the finish chunk for the outcome).
+ */
+export interface BtwStreamChunk {
+    readonly type: string;
+    readonly text?: string;
+    readonly reason?: {
+        readonly kind: string;
+        readonly failure?: {
+            readonly message?: string;
+        };
+    };
+}
+export interface BtwCallOptions {
+    provider: string;
+    model: string;
+    reasoningEffort?: ReasoningEffortId;
+    messages: Message[];
+    system: string;
+    signal?: AbortSignal;
+}
+export type BtwStreamFn = (options: BtwCallOptions) => AsyncIterable<BtwStreamChunk>;
+export type BtwFinish = {
+    kind: 'stop';
+    answer: string;
+} | {
+    kind: 'aborted';
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * Drain one side-call stream: forward text deltas as they arrive, map the
+ * finish chunk (or the stream's end / a throw) to a terminal outcome. A
+ * stream that ends without a finish chunk is an error, never a silent
+ * success; an aborted signal wins over whatever the iterator does next.
+ */
+export declare function consumeBtwStream(chunks: AsyncIterable<BtwStreamChunk>, onDelta: (text: string) => void, signal?: AbortSignal): Promise<BtwFinish>;
+export type BtwRunStatus = 'streaming' | 'done' | 'error' | 'canceled';
+/** View state of the running (or just-finished) side call; overlay-facing. */
+export interface BtwRunState {
+    readonly question: string;
+    readonly modelLabel: string;
+    status: BtwRunStatus;
+    answerText: string;
+    error?: string;
+}
+/** The Last-btw slot — the in-process record of the most recent exchange. */
+export interface BtwLastExchange {
+    readonly question: string;
+    readonly answer: string;
+    readonly modelLabel: string;
+}
+export type BtwNoticeKind = 'info' | 'error' | 'warning';
+export interface BtwSelection {
+    provider: string;
+    model: string;
+    reasoningEffort?: ReasoningEffortId;
+}
+export interface BtwControllerDeps {
+    stream: BtwStreamFn;
+    resolveSelection: () => BtwSelection | undefined;
+    buildSnapshot: () => readonly Message[];
+    requestRender: () => void;
+    notify: (message: string, kind: BtwNoticeKind) => void;
+    /** The glue opens (or swaps) the overlay for a launched run. */
+    onRunStarted: (run: BtwRunState) => void;
+    /** cancelAll: the glue closes the overlay (the run is gone either way). */
+    onOverlayRequestedClose: () => void;
+    /**
+     * Whether a capturing surface (overlay / docked ask-user panel) currently
+     * owns the keyboard. Queue-drained launches under one skip the popup and
+     * run into the slot instead — the answer is reviewable via bare /btw.
+     */
+    hasCapturingSurface?: () => boolean;
+}
+/**
+ * Owns the btw concurrency, the side-call execution and the Last-btw slot.
+ * The overlay glue (btw-overlay.ts) renders `currentRun` / `last` on every
+ * frame and reports overlay open/close back through `setOverlayOpen`.
+ */
+export declare class BtwController {
+    private readonly deps;
+    private readonly queue;
+    private abortController;
+    private run;
+    private lastExchange;
+    private overlayOpen;
+    constructor(deps: BtwControllerDeps);
+    /** View state for the overlay: the live/just-settled run wins over the slot. */
+    get currentRun(): BtwRunState | undefined;
+    get last(): BtwLastExchange | undefined;
+    get queuedCount(): number;
+    /** The glue reports overlay lifecycle so error notices know where to land. */
+    setOverlayOpen(open: boolean): void;
+    submit(job: BtwJob): BtwSubmitResult;
+    /**
+     * Bare `/btw`: an active run reopens live on its overlay; otherwise the
+     * Last-btw slot is shown; nothing at all → the caller shows the usage.
+     */
+    openReview(): 'live' | 'review' | 'empty';
+    /**
+     * Main-line disruption (/new, /resume, remote takeover, stop gesture):
+     * abort the running call, drop the queue, close the overlay. The slot is
+     * untouched — a canceled run never overwrites the last completed one.
+     */
+    cancelAll(): void;
+    /** TUI teardown: same as cancelAll without the overlay ceremony. */
+    dispose(): void;
+    private launch;
+    private execute;
+    /** Settle the queue slot; a queued job (if any) launches immediately. */
+    private drain;
+}