ralph-flow-pi 0.1.0

package/dist/tui/extension.js

@@ -0,0 +1,114 @@
+/**
+ * The ralph-flow extension for the main chat session.
+ *
+ * This is the whole TUI. The plan budgeted ~870 lines for a hand-built one
+ * (transcript pane, streaming renderer, slash dispatcher, status bar) — none of
+ * that got written, because pi's InteractiveMode already IS a Claude-Code-style
+ * TUI and its extension API exposes exactly the three seams we need:
+ *
+ *   registerTool     → the six ralphflow_* tools, so the model can drive them
+ *                      from plain language ("start the spec workflow on X")
+ *   registerCommand  → the eight /ralphflow-* slash commands, verbatim
+ *   sendMessage      → the runner's output, rendered into the same transcript
+ *
+ * The important thing this does NOT do: hand pi the workflow. Step sessions are
+ * still created and driven by our runner, one fresh context per step. The main
+ * chat session is a control surface and a viewport — if it were the DO session
+ * we would have rebuilt the opencode plugin's central flaw on a new stack.
+ */
+import { createRunner } from "../engine/runner.js";
+import { createTools } from "../commands/tools.js";
+import { COMMAND_PROMPTS } from "../commands/prompts.js";
+import { loadSkillIndex } from "../engine/skills.js";
+import { historyEditorFactory } from "./history-editor.js";
+import { createWelcomeHeaderFactory } from "./welcome-header.js";
+/**
+ * Build the inline extension. `getSessionId` must return the main session's id
+ * — it is the ownership token written into every instance's state.json.
+ */
+export function createRalphExtension(engine, getSessionId) {
+    let runner;
+    let api;
+    /** Post engine-authored text into the transcript without provoking a turn. */
+    const post = (text) => {
+        api.sendMessage({ customType: "ralph-flow", content: text, display: text }, { triggerTurn: false });
+    };
+    // Pi's InlineExtension shape: { name, factory } — the factory IS the activate
+    // hook, called with the extension API.
+    const extension = {
+        name: "ralph-flow",
+        factory(a) {
+            api = a;
+            // `ui` doesn't exist on `factory`'s own `api` (see the interface
+            // comment above) — "session_start" is the first point an
+            // ExtensionContext, and therefore `ctx.ui`, is available. `mode ===
+            // "tui"` guards it per ExtensionContext.mode's own doc comment ("Use
+            // 'tui' to guard terminal-only UI such as custom components") — rpc/
+            // print modes have no editor to replace.
+            api.on("session_start", (_event, ctx) => {
+                if (ctx.mode !== "tui")
+                    return;
+                ctx.ui.setEditorComponent(historyEditorFactory);
+                ctx.ui.setHeader(createWelcomeHeaderFactory(() => engine.listWorkflows()));
+            });
+            // Deliberately NO onStepEvent here: run-app.ts's own temporary listener
+            // (added only while a run view is actually attached — see embed.ts)
+            // already shows every DO/CHECK tool call live for anyone watching. A
+            // permanent listener that also streamed those one-liners into chat used
+            // to sit here — real-terminal testing found it was *why* the model kept
+            // reaching for ralphflow_watch on totally unrelated turns: those lines
+            // ("▸ [create] bash mkdir -p ...", "▸ [create] report_done") accumulate
+            // in the transcript the model re-reads on every future invocation
+            // (`triggerTurn: false` only skips waking it up immediately — the text
+            // is still there next time it IS woken up, for any reason), and a model
+            // that notices background activity in its own context tends to comment
+            // on or act on it, unprompted. This directly violated the product's own
+            // stated promise ("不需要你现在做任何事，也不需要主动去查看或汇报进度")
+            // — DO/CHECK tool calls were never a "needs you" moment. Removing this
+            // loses nothing for someone actually watching; it only stops narrating
+            // to someone who isn't.
+            runner = createRunner(engine, {
+                onMessage: (_instId, text) => post(text),
+                onGate: () => { }, // the gate's own message comes through onMessage
+                onPaused: () => { }, // ditto
+                onStalled: () => { }, // ditto
+                onCompleted: () => { }, // ditto
+            }, {
+                skillPaths: () => loadSkillIndex(engine.getRalphFlowDir(), engine.getGlobalConfigHome()).paths,
+            });
+            // The engine needs to reach into this process to abort a DO session when
+            // an instance is destroyed. (abortActiveCheck is wired at engine creation.)
+            engine.setAbortActiveStep?.(runner.abortActiveStep);
+            for (const tool of createTools({ engine, runner, getSessionId })) {
+                api.registerTool(tool);
+            }
+            // Slash commands are thin: each hands its prompt template to the model,
+            // which then calls the matching tool. Keeping the model in the loop is
+            // what makes "/ralphflow-start" with no arguments ask what you want, and
+            // what makes /ralphflow-create an actual conversation.
+            for (const [name, template] of Object.entries(COMMAND_PROMPTS)) {
+                api.registerCommand(name, {
+                    description: template.description,
+                    handler: async (args) => {
+                        api.sendUserMessage(template.render(args));
+                    },
+                });
+            }
+            // Adopt whatever was left running: a crashed process leaves live instance
+            // dirs behind, and the user should not have to know to type continue.
+            for (const info of engine.listInstances()) {
+                if (info.state.paused)
+                    continue;
+                if (engine.foreignRunnerPid(info.id) !== null)
+                    continue; // someone else has it
+                runner.ensureRunning(info.id);
+            }
+        },
+    };
+    return {
+        extension,
+        get runner() { return runner; },
+        shutdown: () => runner?.pauseAllForShutdown(),
+    };
+}
+//# sourceMappingURL=extension.js.map

package/dist/tui/extension.js.map

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

package/dist/tui/history-editor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Completes a feature pi's own chat editor ships half-wired: `Editor` (the
+ * base class `CustomEditor` extends, in pi-tui) already implements Up/Down
+ * arrow history navigation in full — `history`/`historyIndex`/`navigateHistory`
+ * and the key-handling branches that call it are all there, and `addToHistory`
+ * is documented "Called after successful submission." Nothing in
+ * pi-coding-agent's interactive mode actually calls it, though (verified by
+ * grepping the compiled output of all four @earendil-works packages for
+ * `addToHistory` — the only hit is the definition itself). So the editor never
+ * has anything to navigate to, even though the navigation logic works.
+ *
+ * The obvious hook points don't work: `submitValue()` (where the base class's
+ * own doc comment says addToHistory should be called) is `private` in the
+ * .d.ts, so a subclass can't override or call it. `onSubmit` looks like a
+ * public callback property to wrap, but the base class declares it as a bare
+ * class field (`onSubmit;`, no initializer) — under ES2022 class-field
+ * semantics that materializes as an own `[[DefineOwnProperty]]` on every
+ * instance during `super()`, which would silently SHADOW a get/set accessor
+ * defined in this subclass rather than route through it.
+ *
+ * What's actually safe: override the public `handleInput(data)` (already
+ * overridden once by `CustomEditor` itself, so this is a well-trodden
+ * extension point) and replicate the base class's own submit-detection using
+ * only its public surface (`getLines`/`getCursor`/`disableSubmit`/
+ * `getExpandedText`/`addToHistory` — none of them private). The backslash-
+ * before-cursor check mirrors submitValue's own "Shift+Enter workaround"
+ * branch exactly, so a `\` + Enter that inserts a newline instead of
+ * submitting doesn't pollute history with a half-typed draft.
+ */
+import { CustomEditor, type EditorTheme, type KeybindingsManager, type TUI } from "../pi/tui.js";
+export declare class HistoryEditor extends CustomEditor {
+    private kb;
+    constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager);
+    handleInput(data: string): void;
+}
+/** Matches Pi's `EditorFactory` shape for `ctx.ui.setEditorComponent(...)`. */
+export declare function historyEditorFactory(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager): HistoryEditor;
+//# sourceMappingURL=history-editor.d.ts.map

package/dist/tui/history-editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-editor.d.ts","sourceRoot":"","sources":["../../src/tui/history-editor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,GAAG,EAAE,MAAM,cAAc,CAAC;AAEjG,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,EAAE,CAAqB;gBAEnB,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB;IAKhE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAYzC;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,GAAG,aAAa,CAEjH"}

package/dist/tui/history-editor.js

@@ -0,0 +1,55 @@
+/**
+ * Completes a feature pi's own chat editor ships half-wired: `Editor` (the
+ * base class `CustomEditor` extends, in pi-tui) already implements Up/Down
+ * arrow history navigation in full — `history`/`historyIndex`/`navigateHistory`
+ * and the key-handling branches that call it are all there, and `addToHistory`
+ * is documented "Called after successful submission." Nothing in
+ * pi-coding-agent's interactive mode actually calls it, though (verified by
+ * grepping the compiled output of all four @earendil-works packages for
+ * `addToHistory` — the only hit is the definition itself). So the editor never
+ * has anything to navigate to, even though the navigation logic works.
+ *
+ * The obvious hook points don't work: `submitValue()` (where the base class's
+ * own doc comment says addToHistory should be called) is `private` in the
+ * .d.ts, so a subclass can't override or call it. `onSubmit` looks like a
+ * public callback property to wrap, but the base class declares it as a bare
+ * class field (`onSubmit;`, no initializer) — under ES2022 class-field
+ * semantics that materializes as an own `[[DefineOwnProperty]]` on every
+ * instance during `super()`, which would silently SHADOW a get/set accessor
+ * defined in this subclass rather than route through it.
+ *
+ * What's actually safe: override the public `handleInput(data)` (already
+ * overridden once by `CustomEditor` itself, so this is a well-trodden
+ * extension point) and replicate the base class's own submit-detection using
+ * only its public surface (`getLines`/`getCursor`/`disableSubmit`/
+ * `getExpandedText`/`addToHistory` — none of them private). The backslash-
+ * before-cursor check mirrors submitValue's own "Shift+Enter workaround"
+ * branch exactly, so a `\` + Enter that inserts a newline instead of
+ * submitting doesn't pollute history with a half-typed draft.
+ */
+import { CustomEditor } from "../pi/tui.js";
+export class HistoryEditor extends CustomEditor {
+    kb;
+    constructor(tui, theme, keybindings) {
+        super(tui, theme, keybindings);
+        this.kb = keybindings;
+    }
+    handleInput(data) {
+        if (!this.disableSubmit && this.kb.matches(data, "tui.input.submit")) {
+            const cursor = this.getCursor();
+            const currentLine = this.getLines()[cursor.line] || "";
+            const isBackslashContinuation = cursor.col > 0 && currentLine[cursor.col - 1] === "\\";
+            if (!isBackslashContinuation) {
+                const text = this.getExpandedText().trim();
+                if (text)
+                    this.addToHistory(text);
+            }
+        }
+        super.handleInput(data);
+    }
+}
+/** Matches Pi's `EditorFactory` shape for `ctx.ui.setEditorComponent(...)`. */
+export function historyEditorFactory(tui, theme, keybindings) {
+    return new HistoryEditor(tui, theme, keybindings);
+}
+//# sourceMappingURL=history-editor.js.map

package/dist/tui/history-editor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-editor.js","sourceRoot":"","sources":["../../src/tui/history-editor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAAuD,MAAM,cAAc,CAAC;AAEjG,MAAM,OAAO,aAAc,SAAQ,YAAY;IACrC,EAAE,CAAqB;IAE/B,YAAY,GAAQ,EAAE,KAAkB,EAAE,WAA+B;QACvE,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;QAC/B,IAAI,CAAC,EAAE,GAAG,WAAW,CAAC;IACxB,CAAC;IAEQ,WAAW,CAAC,IAAY;QAC/B,IAAI,CAAC,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,kBAAkB,CAAC,EAAE,CAAC;YACrE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YAChC,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACvD,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC;YACvF,IAAI,CAAC,uBAAuB,EAAE,CAAC;gBAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC,IAAI,EAAE,CAAC;gBAC3C,IAAI,IAAI;oBAAE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,UAAU,oBAAoB,CAAC,GAAQ,EAAE,KAAkB,EAAE,WAA+B;IAChG,OAAO,IAAI,aAAa,CAAC,GAAG,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;AACpD,CAAC"}

package/dist/tui/launcher.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The launch flow: pick a workflow, describe the task — a form, not a chat.
+ *
+ * A deterministic pipeline is launched, not conversed with, so the entry point
+ * is a picker + a text field, not an LLM turn. (Designing a NEW workflow IS a
+ * conversation — that lives in the separate `ralphflow create` mode.)
+ *
+ * These helpers drive the shared TUI: they swap in a picker / input as the root,
+ * resolve a promise on selection, and leave the TUI clean for the run view.
+ */
+import type { Engine } from "../engine/core.js";
+import { TUI } from "../pi/tui.js";
+export interface LaunchChoice {
+    kind: "start" | "resume" | "quit";
+    workflow?: string;
+    task?: string;
+    instanceId?: string;
+}
+/**
+ * Full launch flow. Resolves with the user's choice. Resume takes priority: if
+ * live instances exist, offer to attach before starting something new.
+ */
+export declare function runLauncher(tui: TUI, engine: Engine): Promise<LaunchChoice>;
+//# sourceMappingURL=launcher.d.ts.map

package/dist/tui/launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../../src/tui/launcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAiD,GAAG,EAAuC,MAAM,cAAc,CAAC;AAGvH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAaD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAejF"}

package/dist/tui/launcher.js

@@ -0,0 +1,97 @@
+/**
+ * The launch flow: pick a workflow, describe the task — a form, not a chat.
+ *
+ * A deterministic pipeline is launched, not conversed with, so the entry point
+ * is a picker + a text field, not an LLM turn. (Designing a NEW workflow IS a
+ * conversation — that lives in the separate `ralphflow create` mode.)
+ *
+ * These helpers drive the shared TUI: they swap in a picker / input as the root,
+ * resolve a promise on selection, and leave the TUI clean for the run view.
+ */
+import { Input, SelectList, Text, getSelectListTheme } from "../pi/tui.js";
+import { bold, dim } from "./render.js";
+/** Swap the TUI root to a single component (clearing prior children). */
+function setRoot(tui, ...components) {
+    tui.clear();
+    for (const c of components)
+        tui.addChild(c);
+    tui.requestRender();
+}
+function heading(text) {
+    return new Text(text, 1, 1);
+}
+/**
+ * Full launch flow. Resolves with the user's choice. Resume takes priority: if
+ * live instances exist, offer to attach before starting something new.
+ */
+export async function runLauncher(tui, engine) {
+    const instances = engine.listInstances();
+    if (instances.length > 0) {
+        const resumeChoice = await pickResumeOrNew(tui, engine, instances);
+        if (resumeChoice.kind !== "start")
+            return resumeChoice; // resume or quit
+        // fall through to the new-workflow flow
+    }
+    const workflow = await pickWorkflow(tui, engine);
+    if (!workflow)
+        return { kind: "quit" };
+    const task = await enterTask(tui, workflow);
+    if (task === null)
+        return { kind: "quit" };
+    return { kind: "start", workflow, task };
+}
+/** When instances already exist: resume one, start new, or quit. */
+function pickResumeOrNew(tui, engine, instances) {
+    return new Promise((resolve) => {
+        const items = [
+            ...instances.map((i) => ({
+                value: `resume:${i.id}`,
+                label: `恢复 ${i.state.workflow_name} · ${i.state.current_step}`,
+                description: (i.state.user_task || "").replace(/\s+/g, " ").slice(0, 60),
+            })),
+            { value: "new", label: "开始一个新工作流", description: "选择工作流并输入任务" },
+        ];
+        const list = new SelectList(items, 10, getSelectListTheme());
+        list.onSelect = (item) => {
+            if (item.value === "new")
+                resolve({ kind: "start" });
+            else
+                resolve({ kind: "resume", instanceId: item.value.slice("resume:".length) });
+        };
+        list.onCancel = () => resolve({ kind: "quit" });
+        setRoot(tui, heading(bold("有未完成的工作流") + dim("  ↑↓ 选择 · 回车确认 · Esc 退出")), list);
+        tui.setFocus(list);
+    });
+}
+/** Pick a workflow from the resolved list (project → global → built-in). */
+function pickWorkflow(tui, engine) {
+    return new Promise((resolve) => {
+        const workflows = engine.listWorkflows().filter((w) => !w.invalid);
+        if (workflows.length === 0) {
+            resolve(null);
+            return;
+        }
+        const items = workflows.map((w) => ({ value: w.name, label: w.name, description: w.desc }));
+        const list = new SelectList(items, 12, getSelectListTheme());
+        list.onSelect = (item) => resolve(item.value);
+        list.onCancel = () => resolve(null);
+        setRoot(tui, heading(bold("选择工作流") + dim("  ↑↓ 选择 · 回车确认 · Esc 退出")), list);
+        tui.setFocus(list);
+    });
+}
+/** Capture the task description. Resolves null on Esc. */
+function enterTask(tui, workflow) {
+    return new Promise((resolve) => {
+        const input = new Input();
+        input.placeholder = "描述这次要完成的任务，回车开始…";
+        input.onSubmit = (value) => {
+            const task = value.trim();
+            if (task)
+                resolve(task); // empty → keep waiting
+        };
+        input.onEscape = () => resolve(null);
+        setRoot(tui, heading(bold(`工作流：${workflow}`) + dim("  回车开始 · Esc 退出")), new Text(dim("引擎会逐步执行，每步一个全新会话，独立验证。你可以随时看到进度。"), 1, 0), input);
+        tui.setFocus(input);
+    });
+}
+//# sourceMappingURL=launcher.js.map

package/dist/tui/launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../src/tui/launcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAwB,KAAK,EAAE,UAAU,EAAE,IAAI,EAAwB,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AASxC,yEAAyE;AACzE,SAAS,OAAO,CAAC,GAAQ,EAAE,GAAG,UAAuB;IACnD,GAAG,CAAC,KAAK,EAAE,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,UAAU;QAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5C,GAAG,CAAC,aAAa,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAQ,EAAE,MAAc;IACxD,MAAM,SAAS,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;IACzC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,YAAY,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;QACnE,IAAI,YAAY,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,YAAY,CAAC,CAAC,iBAAiB;QACzE,wCAAwC;IAC1C,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACjD,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAEvC,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC5C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAE3C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED,oEAAoE;AACpE,SAAS,eAAe,CAAC,GAAQ,EAAE,MAAc,EAAE,SAA8C;IAC/F,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG;YACZ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACvB,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,EAAE;gBACvB,KAAK,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE;gBAC9D,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;aACzE,CAAC,CAAC;YACH,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE;SAC/D,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,KAAK,EAAE,EAAE,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,EAAE,EAAE;YACvB,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK;gBAAE,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;;gBAChD,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnF,CAAC,CAAC;QACF,IAAI,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,yBAAyB,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAC/E,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,4EAA4E;AAC5E,SAAS,YAAY,CAAC,GAAQ,EAAE,MAAc;IAC5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,SAAS,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACnE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAAC,OAAO;QAAC,CAAC;QACtD,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC5F,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,KAAK,EAAE,EAAE,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC,yBAAyB,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAC5E,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,0DAA0D;AAC1D,SAAS,SAAS,CAAC,GAAQ,EAAE,QAAgB;IAC3C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;QACzB,KAAa,CAAC,WAAW,GAAG,kBAAkB,CAAC;QAChD,KAAK,CAAC,QAAQ,GAAG,CAAC,KAAa,EAAE,EAAE;YACjC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;YAC1B,IAAI,IAAI;gBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,uBAAuB;QAClD,CAAC,CAAC;QACF,KAAK,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACrC,OAAO,CAAC,GAAG,EACT,OAAO,CAAC,IAAI,CAAC,OAAO,QAAQ,EAAE,CAAC,GAAG,GAAG,CAAC,iBAAiB,CAAC,CAAC,EACzD,IAAI,IAAI,CAAC,GAAG,CAAC,kCAAkC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACvD,KAAK,CAAC,CAAC;QACT,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tui/render.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure rendering: RunModel → terminal lines.
+ *
+ * No pi-tui, no side effects, no I/O. Given a model and a width it returns the
+ * exact lines the run view shows, so the entire look of the product is unit-
+ * testable without a terminal. run-view.ts is a thin pi-tui wrapper that pipes
+ * these lines to the screen and calls back in on input.
+ *
+ * The layout is a growing stream on top with a persistent status block pinned at
+ * the bottom (pi-tui's TUI keeps the tail visible, so "bottom" is always on
+ * screen while stream history scrolls up — the same shape as a chat's fixed
+ * input bar). This is what a chat transcript could never give: a live pipeline
+ * you can see all of, with each step's real work streaming in place.
+ */
+import { type RunModel, type StreamBlock } from "./run-model.js";
+export declare const dim: (s: string) => string;
+export declare const bold: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const red: (s: string) => string;
+export declare const yellow: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare const gray: (s: string) => string;
+export declare const magenta: (s: string) => string;
+/**
+ * Display width, counting CJK/emoji as 2 columns (delegates to pi-tui so it
+ * agrees exactly with the width pi-tui's renderer enforces — a mismatch makes
+ * the TUI throw "line exceeds terminal width").
+ */
+export declare function visibleLength(s: string): number;
+/**
+ * Wrap a logical line to `width` display columns, ANSI- and wide-char-aware.
+ * Uses pi-tui's own wrapper, so every line we emit is guaranteed to fit.
+ */
+export declare function wrap(text: string, width: number): string[];
+/**
+ * Pipeline strip: an icon-only progress row, then a dedicated line naming
+ * the active step — number, description, DO/CHECK, elapsed. Two lines, not
+ * one, on purpose: cramming "步骤 3/7：技术方案设计 DO 45s" onto the same
+ * line as the icon row (the original design) made a user report they could
+ * only tell "some step is running" from a glance — the icons read fine as a
+ * progress bar, but the one piece of text answering "which step, doing
+ * what, DO or CHECK" was easy to miss appended after seven icons. Giving it
+ * its own line, led with the step's ordinal position, fixes that without
+ * adding new information — everything here was already computed, just
+ * under-emphasized. `now` defaults to the real clock but is an explicit
+ * param so tests stay deterministic — this is the only place render.ts
+ * touches wall-clock time at all.
+ */
+export declare function renderStepStrip(m: RunModel, width: number, now?: number): string[];
+/** Render one block. Reasoning is dimmed; tools show their key arg + a few result lines. */
+export declare function renderBlock(b: StreamBlock, width: number): string[];
+/** The active step's stream as lines. */
+export declare function renderStream(m: RunModel, width: number): string[];
+/** Header + step strip + action prompt + hints — always visible at the bottom. */
+export declare function renderStatus(m: RunModel, width: number, now?: number): string[];
+/** The actionable block for gate / pause / stall / completion. */
+export declare function renderAction(m: RunModel, width: number): string[];
+/**
+ * The complete document. pi-tui's `TUI` has no real scrollable viewport —
+ * there's no API for "pin this footer, scroll that region above it" (checked:
+ * `TUI extends Container`'s public surface has nothing scroll-related; the
+ * `previousViewportTop` field it does have is a private diffing internal, not
+ * something a Component can use). What `TUI` actually does is redraw the last
+ * `terminalRows` lines of *whatever this function returns this frame* — so
+ * "scrolling" only has one degree of freedom available: change how many lines
+ * this function returns, in front of a renderer that always anchors to the
+ * bottom of that array.
+ *
+ * The bug this used to have: the earlier version dropped lines straight off
+ * the end of `stream` as `scrollBack` grew, which shrinks the *whole returned
+ * array* by that much every keypress — since the status block sits at the very
+ * end, its position relative to the top of the (now shorter) array moves every
+ * time, and because the renderer bottom-anchors, that reads as the status
+ * block itself sliding up the screen the moment you press Up, before there's
+ * any real "scrolling" sensation at all. A user reported exactly this: "方向键
+ * 上去看的时候，不是滚动看，而是下面分割线的布局先往上跑."
+ *
+ * The fix: keep the returned array's total length **invariant to
+ * `scrollBack`** by left-padding with blank lines instead of shrinking the
+ * array. The status block then always sits at the same offset from the end of
+ * the document no matter how far back you've scrolled, so the bottom-anchored
+ * renderer keeps it visually still — only the *content* revealed above it
+ * changes as you page up, which is what "scrolling" is supposed to look like
+ * within a renderer that has no actual scroll primitive.
+ */
+export declare function renderScreen(m: RunModel, width: number, scrollBack?: number, now?: number): string[];
+//# sourceMappingURL=render.d.ts.map

package/dist/tui/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/tui/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,QAAQ,EAAkD,KAAK,WAAW,EAChF,MAAM,gBAAgB,CAAC;AAmBxB,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,WAAoB,CAAC;AAClD,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,WAAqB,CAAC;AACpD,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,WAAsB,CAAC;AACtD,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,WAAoB,CAAC;AAClD,eAAO,MAAM,MAAM,GAAI,GAAG,MAAM,WAAuB,CAAC;AACxD,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,WAAqB,CAAC;AACpD,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,WAAqB,CAAC;AACpD,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,WAAwB,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAS1D;AAkBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,EAAE,CAM9F;AAwBD,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA4BnE;AAQD,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAOjE;AAaD,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,EAAE,CAiB3F;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBjE;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,SAAI,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,EAAE,CAO3G"}