@nanhara/hara 0.102.0 → 0.104.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.104.0 — compaction keeps your working files + honest context accounting
+
+Closes the last two adopted items from the Claude Code internals study, and un-breaks the release
+pipeline.
+
+- **Post-compaction file restore** (CC's TW5): compaction now re-attaches the CURRENT on-disk content
+  of the files the conversation was most recently working with (top 5, byte-capped) — the summary is
+  no longer the model's only anchor, so it doesn't re-read its own working set or act on a stale
+  memory of an edited file.
+- **Context threshold ladder + cache-aware accounting**: the footer's `ctx N%` turns yellow at 60%
+  and red at 80% (auto-compact fires at 85), so compaction never surprises you. And on Anthropic
+  endpoints, input accounting now includes cache reads/writes — cached sessions used to under-report
+  context fullness so badly that auto-compact could never fire before overflow.
+- **Release pipeline fixed** (every `v*` tag's release workflow had been failing silently):
+  the Docker image's `npm ci` ran the `prepare → tsc` hook before src was copied; and the standalone
+  binaries died on the Feishu SDK's default import under bun's ESM resolution. Both corrected —
+  binaries + ghcr image ship again from this tag.
+
+## 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

package/dist/agent/compact.js

@@ -20,6 +20,28 @@ export const COMPACT_SYSTEM = "Summarize the conversation so far into a structur
     "7. All user messages — EVERY user message so far (excluding tool results), verbatim and in order; abbreviate only huge pasted blobs with […]. These are the ground truth of intent.\n" +
     "8. Next step — the immediate next action, INCLUDING a direct verbatim quote of the user's most recent request so there is no drift.\n" +
     "Be specific and concrete. Drop the <analysis>; output only the headed summary.";
+/** Post-compaction file restore (Claude Code's TW5): re-attach the CURRENT content of the files the
+ *  conversation was just working with, so the summary isn't the model's only anchor — it doesn't have
+ *  to re-read its own working set next turn (and can't act on a stale memory of an edited file).
+ *  `readFn` is injected (returns null for unreadable/gone files); byte caps bound the token cost. */
+export function buildFileRestore(paths, readFn, opts) {
+    const per = opts?.perFileBytes ?? 8_192;
+    let budget = opts?.totalBytes ?? 24_576;
+    const parts = [];
+    for (const p of paths) {
+        if (budget <= 0)
+            break;
+        const raw = readFn(p);
+        if (raw == null)
+            continue;
+        const clipped = raw.slice(0, Math.min(per, budget));
+        budget -= clipped.length;
+        parts.push(`--- ${p}${clipped.length < raw.length ? " (truncated)" : ""} ---\n${clipped}`);
+    }
+    if (!parts.length)
+        return null;
+    return `Files you were recently working with (CURRENT on-disk content, restored after compaction):\n\n${parts.join("\n\n")}`;
+}
 /** Whether to auto-compact now: enabled, the history is substantial enough to be worth summarizing, and the
  *  last turn filled the context past the threshold (so the NEXT turn would risk overflow). */
 export function shouldAutoCompact(ctxPct, historyLen, autoCompact, threshold = AUTO_COMPACT_PCT) {

package/dist/agent/loop.js

@@ -13,6 +13,10 @@ 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";
+import { recordTouch } from "./touched.js";
+import { resolve as resolvePath } from "node:path";
+/** File tools whose `path` input marks the file as "recently worked with" (post-compaction restore). */
+const FILE_TOUCH_TOOLS = new Set(["read_file", "edit_file", "write_file"]);
 /** 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
@@ -49,7 +53,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.
@@ -375,6 +385,11 @@ export async function runAgent(history, opts) {
                     results[idx] = { id: p.tu.id, name: p.tu.name, content: pre.message, isError: true };
                     return;
                 }
+                // Track the MAIN conversation's working files for post-compaction restore (quiet fan-out
+                // sub-agents read broadly — their files aren't "what the user was working on").
+                if (!opts.quiet && FILE_TOUCH_TOOLS.has(p.tu.name) && typeof p.tu.input?.path === "string") {
+                    recordTouch(resolvePath(ctx.cwd, String(p.tu.input.path)));
+                }
                 const res = await p.tool.run(p.tu.input, ctx);
                 // append any not-yet-seen subdirectory AGENTS.md/CLAUDE.md this call touched (monorepo-local conventions)
                 results[idx] = { id: p.tu.id, name: p.tu.name, content: res + subdirHint(p.tu.input, ctx.cwd) };

package/dist/agent/touched.js

@@ -0,0 +1,18 @@
+// Recently-touched file tracker — feeds post-compaction FILE RESTORE (Claude Code's TW5 pattern).
+// The loop records every file the MAIN conversation reads/edits; when the history is compacted to a
+// summary, the top-N most-recent files get their CURRENT on-disk content re-attached — so the model
+// doesn't lose the very files it was working on and re-read them all next turn.
+const touched = new Map(); // absolute path → last-touch timestamp
+export function recordTouch(path) {
+    touched.set(path, Date.now());
+}
+/** Most-recently-touched first. */
+export function recentTouched(n = 5) {
+    return [...touched.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, n)
+        .map(([p]) => p);
+}
+export function clearTouched() {
+    touched.clear();
+}

package/dist/gateway/feishu.js

@@ -3,7 +3,11 @@
 // outbound. Creds from HARA_FEISHU_APP_ID / HARA_FEISHU_APP_SECRET (+ HARA_FEISHU_DOMAIN=lark for larksuite.com).
 // Same ChatAdapter shape as the others, so all cross-platform gateway logic (send_file, system context,
 // stuck-guard, image attach/describe) works unchanged. v1 = p2p (DM) only; group support is a fast-follow.
-import lark from "@larksuiteoapi/node-sdk";
+// Namespace import + default fallback: node resolves this SDK as CJS (default = module object), but
+// bun's bundler resolves its ESM build (named exports only, NO default) — `import lark from` made
+// every binaries release fail. This form works under both resolutions.
+import * as larkNs from "@larksuiteoapi/node-sdk";
+const lark = (larkNs.default ?? larkNs);
 import { createReadStream, createWriteStream, mkdirSync } from "node:fs";
 import { pipeline } from "node:stream/promises";
 import { join, basename } from "node:path";

package/dist/index.js

@@ -24,7 +24,8 @@ import { clearEnrollment, enrollDevice, heartbeat, syncOrgRoles } from "./org-fl
 import { loadActiveProfile, listProfiles, useProfile, addProfile, upsertProfile, removeProfile, setModel as setProfileModel, resetModel as resetProfileModel, getProfile, effectiveModel, routingLabel, routeHost, activeId, resolveActive, setFlagOverride, writePin, removePin, pinFilePath, DEFAULT_ORG_ID, PERSONAL_ID, } from "./profile/profile.js";
 import { loadPermissionRules, scaffoldPermissions, globalPermissionsPath, projectPermissionsPath } from "./security/permissions.js";
 import { routingProvider } from "./agent/route.js";
-import { shouldAutoCompact, COMPACT_SYSTEM } from "./agent/compact.js";
+import { shouldAutoCompact, COMPACT_SYSTEM, buildFileRestore } from "./agent/compact.js";
+import { recentTouched } from "./agent/touched.js";
 import { checkForUpdate } from "./update-check.js";
 import { formatContextReport } from "./agent/context-report.js";
 import { userTurnPreviews, rewindTo } from "./agent/rewind.js";
@@ -36,6 +37,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";
@@ -743,6 +745,18 @@ async function compactConversation(provider, history, meta, stats) {
     meta.workingSet = workingSetFromSummary(summary); // survives the history wipe + injects into the next turns
     history.length = 0;
     history.push({ role: "user", content: `Summary of our conversation so far (continue from here):\n\n${summary}` });
+    // TW5-style file restore: the summary alone loses the working set's ACTUAL content — re-attach the
+    // most recently touched files (current on-disk state, byte-capped) so work continues without re-reads.
+    const restore = buildFileRestore(recentTouched(5), (p) => {
+        try {
+            return readFileSync(p, "utf8");
+        }
+        catch {
+            return null;
+        }
+    });
+    if (restore)
+        history.push({ role: "user", content: restore });
     stats.input += r.usage?.input ?? 0;
     stats.output += r.usage?.output ?? 0;
     stats.lastInput = r.usage?.input ?? 0; // ctx% now reflects the (small) summary, not the old full turn
@@ -765,6 +779,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 +797,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/providers/anthropic.js

@@ -113,7 +113,11 @@ export function createAnthropicProvider(opts) {
                 .filter((b) => b.type === "tool_use")
                 .map((b) => ({ id: b.id, name: b.name, input: b.input }));
             const stop = msg.stop_reason === "tool_use" ? "tool_use" : "end";
-            const usage = { input: msg.usage?.input_tokens ?? 0, output: msg.usage?.output_tokens ?? 0 };
+            // Cache-aware input accounting: Anthropic's input_tokens EXCLUDES cache reads/writes, so a
+            // cached session under-reported context fullness badly (ctx% stayed tiny → auto-compact never
+            // fired → overflow). Total context = fresh + cache_creation + cache_read (CC's zY5 equivalent).
+            const u = msg.usage;
+            const usage = { input: (u?.input_tokens ?? 0) + (u?.cache_creation_input_tokens ?? 0) + (u?.cache_read_input_tokens ?? 0), output: u?.output_tokens ?? 0 };
             return { text, toolUses, stop, usage };
         },
     };

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/InputBox.js

@@ -54,21 +54,25 @@ export function footerParts(model, s, cwdShort, route) {
     return {
         prefix: `  ${model} · `,
         mode: s.approval,
-        suffix: `${routeSeg} · ${cwdShort} · ↑${tok(s.input)} ↓${tok(s.output)} · ctx ${s.ctxPct}%`,
+        suffix: `${routeSeg} · ${cwdShort} · ↑${tok(s.input)} ↓${tok(s.output)} · `,
+        ctx: `ctx ${s.ctxPct}%`,
+        // Claude Code's threshold ladder (60 warn / 80 error / 92 compact): hara auto-compacts at 85, so
+        // the footer escalates BEFORE that — yellow at 60, red at 80 — and the user sees compaction coming.
+        ctxLevel: s.ctxPct >= 80 ? "high" : s.ctxPct >= 60 ? "warn" : "ok",
     };
 }
-/** Back-compat: the full footer as one string (prefix+mode+suffix). Kept for any pure consumer/test. */
+/** Back-compat: the full footer as one string. Kept for any pure consumer/test. */
 export function footerLine(model, s, cwdShort, route) {
     const p = footerParts(model, s, cwdShort, route);
-    return p.prefix + p.mode + p.suffix;
+    return p.prefix + p.mode + p.suffix + p.ctx;
 }
 // The merged status footer: model · approval · route · cwd · usage · ctx. The active approval mode is
 // colored inline (the always-on ModeBar is gone — shift+tab now pops a transient selector instead), so
 // the outer <Text> is NOT dim: only the prefix/suffix are dimmed and the mode token stays bright.
 // Memoized so a prompt keystroke doesn't reconcile it.
 const Footer = memo(function Footer({ model, s, cwdShort, route }) {
-    const { prefix, mode, suffix } = footerParts(model, s, cwdShort, route);
-    return (_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: prefix }), _jsx(Text, { color: approvalColor(s.approval), bold: true, children: mode }), _jsx(Text, { dimColor: true, children: suffix })] }));
+    const { prefix, mode, suffix, ctx, ctxLevel } = footerParts(model, s, cwdShort, route);
+    return (_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: prefix }), _jsx(Text, { color: approvalColor(s.approval), bold: true, children: mode }), _jsx(Text, { dimColor: true, children: suffix }), ctxLevel === "ok" ? _jsx(Text, { dimColor: true, children: ctx }) : _jsx(Text, { color: ctxLevel === "high" ? "red" : "yellow", bold: true, children: ctx })] }));
 });
 // The rounded TOP edge of the input box, carrying the session name in the right corner (it "rides"
 // the border — codex-style titled panel, and where hara has always shown it). Drawn by hand because

package/package.json

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