@nanhara/hara 0.101.1 → 0.103.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.103.0 — the project-analysis SOP (why hara felt slow on "analyze this repo")
+
+The execution layer could always parallelize reads and fan out read-only sub-agents — but nothing
+TAUGHT the model, so it explored one call per turn. Distilled from codex's prompt discipline and
+Claude Code's Explore-agent pattern:
+
+- **System prompt playbook**: batch independent tool calls in one response (reads execute in
+  parallel); analyzing a project starts with a ONE-batch wide sweep (manifest + README + build/CI
+  config) then narrow grep/glob; more than ~3 searches → fan out `agent` sub-agents, several in one
+  response.
+- **`agent` tool grows WHEN-TO-USE / WHEN-NOT-TO-USE guidance** (CC's heuristic): narrow lookups go
+  to direct tools; open-ended "how does X work across the codebase" goes to sub-agents.
+- **Built-in `explore` persona** — `agent(role:"explore")` works with zero setup: read-only, parallel
+  searches, excerpts not whole files, returns conclusions with path:line refs, never dumps. A
+  user-defined explore role still wins.
+
+## 0.102.0 — a slow network never feels dead
+
+Jeff + a designer colleague both hit the same thing: press Enter on a slow connection and hara
+"looks stuck — thought it failed". Studied codex's handling (15s connect timeout, 2–9s stream-idle
+timeout, Working[Xs·Esc] status machine) and closed the gaps:
+
+- **Stall watchdog.** A model attempt that streams NOTHING for 120s (HARA_STALL_TIMEOUT to tune) is
+  aborted and routed through the normal error→failover path — `fallbackModel` picks it up
+  automatically, or you get a clear "model stream timeout — no output for 120s" instead of an
+  infinite spinner. A real Esc stays an interrupt (never rewritten).
+- **"waiting for the model… Ns".** The status row now distinguishes the pre-first-token stretch from
+  actual work (a new turn-phase channel published by the loop) — on a slow route you can SEE the
+  request is out, ticking, interruptible.
+- **Big pastes fold to a token.** Pasting a long/multi-line text used to flood the box AND could
+  auto-submit at the first newline mid-paste. Now ≥3 lines or ≥600 chars folds to a highlighted
+  `[Paste #1 +N lines]` token (Claude-Code style): the box stays small, typing stays smooth,
+  backspace deletes it whole, and the FULL text expands into the message on submit.
+
 ## 0.101.1 — the input box stops running to the top
 
 - **Live-region overflow guard.** A long streaming answer (or a big diff) used to grow the live region

package/dist/agent/loop.js

@@ -12,6 +12,16 @@ import { subdirHint } from "../context/subdir-hints.js";
 import { classifyError, failoverAction, errorHint } from "./failover.js";
 import { currentTodos, renderTodos } from "../tools/todo.js";
 import { drainReminders, wrapReminders, pushReminder, todoStaleReminder, TODO_STALE_ROUNDS } from "./reminders.js";
+import { setTurnPhase } from "./phase.js";
+/** Stall watchdog ceiling: a model attempt that streams NOTHING for this long is treated as a dead /
+ *  stalled connection and aborted into the normal error→failover path — instead of hanging on
+ *  "working Ns" forever (the "pressed Enter, thought it failed" report). Generous default because
+ *  hidden-reasoning models can legitimately go quiet for a while; HARA_STALL_TIMEOUT (ms) tunes it,
+ *  floor 1s (tests). codex's equivalent is its 2–9s stream-idle timeout. */
+export function stallMs() {
+    const raw = Number(process.env.HARA_STALL_TIMEOUT ?? 120_000);
+    return Math.max(1_000, Number.isFinite(raw) && raw > 0 ? raw : 120_000);
+}
 /** Spinner verb (terminal mode + reused by TUI tests): when the agent has an in_progress todo,
  *  surface its activeForm/text so the bottom-of-screen line reads concretely ("▶ updating tests… 3s")
  *  instead of "working 3s". Pure: takes a snapshot + elapsed seconds. */
@@ -39,7 +49,13 @@ const HARA_SYSTEM = (cwd) => `You are hara, a coding agent running in the user's
 Working directory: ${cwd}
 Be concise and direct. Use the provided tools to read files, edit/write files, and run shell
 commands. Prefer small, verifiable steps; edit existing files with edit_file rather than rewriting
-them whole. For a multi-step task, call \`todo_write\` to plan a short checklist and keep it updated as
+them whole. Batch INDEPENDENT tool calls in a single response — especially reads (read_file / grep /
+glob / ls run in PARALLEL when requested together); one-call-per-turn exploration is the slowest thing
+you can do. When analyzing a project, start wide in ONE batch — manifest (package.json / Cargo.toml /
+pyproject.toml / go.mod), README, build/CI config — then chase only what the task needs with narrow
+grep/glob; don't read whole large files when a targeted search answers the question. For broad,
+open-ended exploration (more than ~3 searches), spawn \`agent\` sub-agents — several in one response for
+independent questions (role "explore") — each returns conclusions, not dumps. For a multi-step task, call \`todo_write\` to plan a short checklist and keep it updated as
 you go (one item in_progress at a time) — skip it for trivial one-step tasks. You have a persistent
 memory: use memory_search before answering about prior decisions,
 conventions, or the user's preferences, and memory_write to proactively save durable facts you learn.
@@ -141,53 +157,89 @@ export async function runAgent(history, opts) {
                 out(`\r\x1b[K${c.dim(`${frames[fi++ % frames.length]} ${verb}`)}`);
             }, 100);
         }
-        const r = await activeProvider.turn({
-            system: composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory),
-            history,
-            tools: specs,
-            onText: (d) => {
-                if (opts.quiet)
-                    return;
-                if (sink) {
-                    sink.text(d);
-                    return;
-                }
-                stopSpin();
-                flushReasoningTail();
-                if (md)
-                    md.push(d);
-                else
-                    out(d);
-            },
-            onReasoning: sink || tty
-                ? (d) => {
+        // Stall watchdog: any stream event resets the clock; STALL_MS of silence aborts THIS attempt via
+        // its own controller (the user's opts.signal chains into it, so Esc still interrupts). The abort
+        // is then rewritten from "interrupted" to a timeout-class error so failover can take over.
+        const STALL_MS = stallMs();
+        const attempt = new AbortController();
+        const onUserAbort = () => attempt.abort();
+        opts.signal?.addEventListener("abort", onUserAbort, { once: true });
+        let lastEvent = Date.now();
+        let stalled = false;
+        const stallTimer = setInterval(() => {
+            if (Date.now() - lastEvent > STALL_MS) {
+                stalled = true;
+                attempt.abort();
+            }
+        }, Math.min(2_000, Math.max(250, STALL_MS / 4)));
+        const alive = () => {
+            lastEvent = Date.now();
+            if (!opts.quiet)
+                setTurnPhase("streaming");
+        };
+        if (!opts.quiet)
+            setTurnPhase("waiting"); // request sent, nothing streamed yet — the status row shows it
+        let r;
+        try {
+            r = await activeProvider.turn({
+                system: composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory),
+                history,
+                tools: specs,
+                onText: (d) => {
+                    alive();
                     if (opts.quiet)
                         return;
                     if (sink) {
-                        sink.reasoning(d);
+                        sink.text(d);
                         return;
                     }
-                    // Terminal mode: render reasoning on its own dim lines (prefix `│ ` per line). Each
-                    // line is committed once and never overwritten — so a subsequent spinner tick can't
-                    // clobber it (the old `out(c.dim(d))` bug). Multi-line deltas split cleanly; the
-                    // current line resumes mid-output when the next delta arrives.
                     stopSpin();
-                    const lines = d.split("\n");
-                    for (let i = 0; i < lines.length; i++) {
-                        if (!reasoningOpen) {
-                            out(c.dim("│ "));
-                            reasoningOpen = true;
+                    flushReasoningTail();
+                    if (md)
+                        md.push(d);
+                    else
+                        out(d);
+                },
+                onReasoning: sink || tty
+                    ? (d) => {
+                        alive();
+                        if (opts.quiet)
+                            return;
+                        if (sink) {
+                            sink.reasoning(d);
+                            return;
                         }
-                        out(c.dim(lines[i]));
-                        if (i < lines.length - 1) {
-                            out("\n");
-                            reasoningOpen = false;
+                        // Terminal mode: render reasoning on its own dim lines (prefix `│ ` per line). Each
+                        // line is committed once and never overwritten — so a subsequent spinner tick can't
+                        // clobber it (the old `out(c.dim(d))` bug). Multi-line deltas split cleanly; the
+                        // current line resumes mid-output when the next delta arrives.
+                        stopSpin();
+                        const lines = d.split("\n");
+                        for (let i = 0; i < lines.length; i++) {
+                            if (!reasoningOpen) {
+                                out(c.dim("│ "));
+                                reasoningOpen = true;
+                            }
+                            out(c.dim(lines[i]));
+                            if (i < lines.length - 1) {
+                                out("\n");
+                                reasoningOpen = false;
+                            }
                         }
                     }
-                }
-                : undefined,
-            signal: opts.signal,
-        });
+                    : (d) => alive(), // quiet runs still feed the watchdog (reasoning-only stretches are progress)
+                signal: attempt.signal,
+            });
+        }
+        finally {
+            clearInterval(stallTimer);
+            opts.signal?.removeEventListener("abort", onUserAbort);
+        }
+        // A watchdog abort surfaces from the provider as "interrupted" — rewrite it to a timeout-class
+        // error (unless the USER really did interrupt) so classifyError → failover/fallback handles it.
+        if (stalled && r.stop === "error" && !opts.signal?.aborted) {
+            r = { ...r, errorMsg: `model stream timeout — no output for ${Math.round(STALL_MS / 1000)}s (stalled connection?)` };
+        }
         stopSpin();
         flushReasoningTail();
         md?.end();

package/dist/agent/phase.js

@@ -0,0 +1,29 @@
+// Turn phase for the status line (codex-parity): between "request sent" and "first stream event"
+// the user should see *waiting for the model* — not a generic "working" that reads the same whether
+// the model is thinking or the connection is dead. The MAIN loop publishes (quiet/sub-agent runs
+// don't — they'd stomp the shared channel); the TUI status row subscribes like it does for todos.
+let phase = "idle";
+const listeners = new Set();
+export function turnPhase() {
+    return phase;
+}
+export function setTurnPhase(p) {
+    if (p === phase)
+        return;
+    phase = p;
+    for (const fn of listeners) {
+        try {
+            fn(phase);
+        }
+        catch {
+            /* a listener must not break the loop */
+        }
+    }
+}
+/** Subscribe to phase changes. Returns an unsubscribe fn. */
+export function onTurnPhase(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}

package/dist/index.js

@@ -36,6 +36,7 @@ import { addJob, removeJob, setEnabled, resolveJob, loadJobs, recordRun, logPath
 import { runTick, runJobOnce, selfArgv } from "./cron/runner.js";
 import { installScheduler, uninstallScheduler, isInstalled } from "./cron/install.js";
 import { getTools } from "./tools/registry.js";
+import { EXPLORE_SYSTEM } from "./tools/agent.js";
 import { createAnthropicProvider } from "./providers/anthropic.js";
 import { createOpenAIProvider } from "./providers/openai.js";
 import { qwenDeviceLogin, getValidQwenAuth } from "./providers/qwen-oauth.js";
@@ -765,6 +766,9 @@ async function maybeAutoCompact(provider, history, meta, stats, cfg, notify) {
 async function runSubagent(cfg, baseProvider, cwd, sandbox, projectContext, stats, task, roleId) {
     const roles = loadRoles(cwd);
     const role = roleId ? roles.find((r) => r.id === roleId) : undefined;
+    // Built-in explore persona: `agent(role:"explore")` works with ZERO user setup (a user-defined
+    // explore role still wins — it was found above and carries its own system).
+    const builtinSystem = !role && roleId === "explore" ? EXPLORE_SYSTEM : undefined;
     const __subModel = effectiveRoleModel(role?.model, cfg.model);
     const provider = __subModel ? ((await buildProvider({ ...cfg, model: __subModel })) ?? baseProvider) : baseProvider;
     // A sub-agent runs full-auto + UNCONFIRMED + parallel, so it is ALWAYS read-only — a role may narrow
@@ -780,7 +784,7 @@ async function runSubagent(cfg, baseProvider, cwd, sandbox, projectContext, stat
         projectContext,
         memory: memoryDigest(cwd),
         stats,
-        systemOverride: role?.system,
+        systemOverride: role?.system ?? builtinSystem,
         toolFilter,
         quiet: true,
     });

package/dist/tools/agent.js

@@ -2,11 +2,24 @@
 // turn run in PARALLEL (kind "read" → concurrent), making the footer's ⛁ count real. Sub-agents are
 // read-only by default (safe to parallelize); the actual spawn is provided via ctx.spawn.
 import { registerTool } from "./registry.js";
+/** Built-in persona for `role: "explore"` (no setup needed — index.ts falls back to this when the
+ *  user hasn't defined an explore role). Claude-Code's Explore-agent playbook: read-only, parallel,
+ *  excerpts-not-files, conclusions-not-dumps. */
+export const EXPLORE_SYSTEM = "You are a fast, READ-ONLY codebase explorer. Navigate with grep/glob/ls/read_file and be quick: " +
+    "issue your searches and file reads as MULTIPLE PARALLEL tool calls in one round whenever they are " +
+    "independent — never one-per-turn. Read targeted excerpts, not whole files. You cannot modify anything. " +
+    "Answer with CONCLUSIONS: the finding, the relevant paths with line references, and what they mean for " +
+    "the question — never dump raw file contents. Match your depth to the task: a quick lookup stays quick; " +
+    "an architecture question deserves a thorough sweep across naming conventions and directories.";
 registerTool({
     name: "agent",
-    description: "Delegate an independent sub-task to a fresh sub-agent and get its result. Spawn SEVERAL in one " +
-        "turn to run them in parallel (e.g. analyze/search/review N things at once). Sub-agents are " +
-        "read-only by default; pass a `role` id to use that role's persona + tools. Not for edits.",
+    description: "Delegate an independent sub-task to a fresh READ-ONLY sub-agent and get its conclusions. " +
+        "WHEN TO USE: open-ended exploration ('how does X work across the codebase', 'find everything that touches Y') " +
+        "that would take more than ~3 searches — pass role \"explore\" for a fast search specialist; and spawning " +
+        "SEVERAL agents in ONE response for independent questions (they run in parallel). " +
+        "WHEN NOT TO USE: reading a specific known file (read_file), finding one symbol (grep), or searching " +
+        "within 2-3 known files — direct tools are faster. Never for edits. " +
+        "Pass a `role` id to use that role's persona + tools.",
     input_schema: {
         type: "object",
         properties: {

package/dist/tui/App.js

@@ -17,6 +17,7 @@ import { ctxPctFor } from "../statusbar.js";
 import { accent } from "./theme.js";
 import { renderMarkdown } from "../md.js";
 import { clearTodos, currentTodos, onTodosChange } from "../tools/todo.js";
+import { onTurnPhase, turnPhase } from "../agent/phase.js";
 let _id = 0;
 const nid = () => ++_id;
 const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
@@ -256,7 +257,9 @@ const SPINNER_FRAME_MS = 125;
 const IDLE_HINTS = "⏎ send · @ file · ctrl+v image · ctrl+t transcript · shift+tab mode";
 function StatusRow({ working, todos, queued }) {
     const [frame, setFrame] = useState(0);
+    const [phase, setPhase] = useState(() => turnPhase());
     const startRef = useRef(Date.now());
+    useEffect(() => onTurnPhase(setPhase), []); // waiting → streaming, published by the agent loop
     useEffect(() => {
         if (!working)
             return;
@@ -269,7 +272,10 @@ function StatusRow({ working, todos, queued }) {
     }
     const frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏";
     const elapsedSec = Math.floor((Date.now() - startRef.current) / 1000);
-    return (_jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "yellow", children: frames[frame % frames.length] }), _jsx(Text, { dimColor: true, children: ` ${spinnerVerb(todos, elapsedSec)} · ⏎ queues${queued ? ` (${queued})` : ""}` })] }));
+    // Pre-first-token honesty (codex-parity): "waiting for the model" reads very differently from a
+    // generic "working" when the network is slow — the user knows the request is out, not dead.
+    const verb = phase === "waiting" ? `waiting for the model… ${elapsedSec}s · esc to interrupt` : spinnerVerb(todos, elapsedSec);
+    return (_jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "yellow", children: frames[frame % frames.length] }), _jsx(Text, { dimColor: true, children: ` ${verb} · ⏎ queues${queued ? ` (${queued})` : ""}` })] }));
 }
 // Short per-mode descriptions for the ONE-ROW mode line (the old two-row ModeBar's long sentences
 // don't fit inline). Full behavior is documented in /help; this line is a switching aid, not a manual.

package/dist/tui/InputBox.js

@@ -89,7 +89,7 @@ function activeMention(value, cursor) {
 const MentionPopup = memo(function MentionPopup({ items, selected, query }) {
     return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: `  @${query}  ·  ${items.length} match${items.length === 1 ? "" : "es"} — ↑↓ select · Tab/Enter insert · Esc dismiss` }), items.map((it, i) => (_jsxs(Text, { children: [i === selected ? _jsx(Text, { color: "cyan", children: "  ▸ " }) : _jsx(Text, { children: "    " }), _jsx(Text, { color: it.endsWith("/") ? "blue" : undefined, dimColor: i !== selected, bold: i === selected, children: it })] }, it)))] }));
 });
-const TOKEN_RE = /\[Image #\d+\]/g;
+const TOKEN_RE = /\[Image #\d+\]|\[Paste #\d+ \+\d+ lines\]/g;
 /** Split the value into text/image-token segments (image tokens render highlighted, codex-style). */
 function segmentize(value) {
     const parts = [];
@@ -239,6 +239,7 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
     const [sel, setSel] = useState(0);
     const [dismissed, setDismissed] = useState(false);
     const [images, setImages] = useState([]);
+    const [pastes, setPastes] = useState([]); // full text behind each [Paste #N] token
     const [mode, setMode] = useState("insert"); // vim only
     const [pending, setPending] = useState(""); // vim operator-pending (d/c/g)
     const [register, setRegister] = useState(""); // vim yank/delete register
@@ -260,12 +261,28 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
         setSel(0);
         setDismissed(false);
     };
+    // A big paste folds into a [Paste #N +L lines] token (Claude-Code/codex style) instead of flooding
+    // the box: typing stays smooth (the VALUE stays short), the box stays small, and a multi-line paste
+    // can no longer fire the newline-submit path mid-paste. Expanded back to the full text on submit.
+    const addPaste = (text) => {
+        const lines = text.split("\n").length;
+        const tok = `[Paste #${pastes.length + 1} +${lines} lines]`;
+        const before = value.slice(0, cursor);
+        const ins = (before && !/\s$/.test(before) ? " " : "") + tok + " ";
+        setValue(before + ins + value.slice(cursor));
+        setCursor((before + ins).length);
+        setPastes((xs) => [...xs, text]);
+        setSel(0);
+        setDismissed(false);
+    };
+    const expandPastes = (text) => text.replace(/\[Paste #(\d+) \+\d+ lines\]/g, (m, d) => pastes[Number(d) - 1] ?? m);
     const submit = (text) => {
         if (!text.trim() && images.length === 0)
             return; // nothing to send
-        onSubmit?.(text, images.length ? images : undefined);
+        onSubmit?.(expandPastes(text), images.length ? images : undefined);
         set("", 0);
         setImages([]);
+        setPastes([]);
         setMode("insert"); // a fresh prompt starts in insert
         setPending("");
     };
@@ -354,6 +371,18 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
         if (key.backspace || key.delete) {
             if (cursor > 0) {
                 const head = value.slice(0, cursor);
+                const pm = /\[Paste #(\d+) \+\d+ lines\]\s?$/.exec(head); // paste token deletes whole + renumbers
+                if (pm) {
+                    const n = Number(pm[1]);
+                    const kept = head.slice(0, pm.index) + value.slice(cursor);
+                    const renumbered = kept.replace(/\[Paste #(\d+)( \+\d+ lines\])/g, (m2, d, tail) => (Number(d) > n ? `[Paste #${Number(d) - 1}${tail}` : m2));
+                    setPastes((xs) => xs.filter((_, i) => i !== n - 1));
+                    setValue(renumbered);
+                    setCursor(pm.index);
+                    setSel(0);
+                    setDismissed(false);
+                    return;
+                }
                 const tm = /\[Image #(\d+)\]\s?$/.exec(head); // backspacing over an attachment token removes it whole
                 if (tm) {
                     const n = Number(tm[1]);
@@ -371,6 +400,12 @@ export function InputBox({ status, cwd, model, route, width, onSubmit, onClipboa
             return;
         }
         if (input && !key.ctrl && !key.meta) {
+            // A LARGE paste (many lines or lots of text in one chunk) folds to a token — never submits,
+            // never floods the box. Small chunks keep the existing paste-to-run newline behavior.
+            if (input.length >= 600 || (input.match(/\n/g)?.length ?? 0) >= 3) {
+                addPaste(input);
+                return;
+            }
             const nl = input.search(/[\r\n]/); // a chunk carrying a newline (paste / fed input) submits
             if (nl >= 0) {
                 submit(value.slice(0, cursor) + input.slice(0, nl) + value.slice(cursor));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.101.1",
+  "version": "0.103.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"