@nanhara/hara 0.103.0 → 0.105.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.105.0 — fan-outs synthesize before acting
+
+- **Synthesis nudge** (the last adopted item from the Claude Code internals study — their KN5
+  synthesizer, hara-shaped): when a round returns **3+ parallel agent reports**, a silent
+  system-reminder tells the model to merge them first — reconcile overlaps and conflicts explicitly,
+  note what only one report saw, state the merged conclusion — instead of anchoring on whichever
+  report happens to sit last in context. Rides the 0.100.0 reminder layer; no new machinery.
+
+## 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

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

@@ -11,8 +11,12 @@ import { classifyRisk, guardianVeto, guardianEnabled, newBreaker, recordBlock }
 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 { drainReminders, wrapReminders, pushReminder, todoStaleReminder, TODO_STALE_ROUNDS, synthesisReminder, SYNTHESIS_MIN_AGENTS } 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
@@ -381,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) };
@@ -413,6 +422,14 @@ export async function runAgent(history, opts) {
         }
         await flush();
         history.push({ role: "tool", results });
+        // Synthesis nudge (CC's KN5, hara-shaped): a round that fanned out to several parallel agents just
+        // produced N independent reports — remind the model to merge/reconcile them before acting, instead
+        // of anchoring on whichever report happens to sit last in context.
+        if (!opts.quiet) {
+            const fanout = r.toolUses.filter((tu) => tu.name === "agent").length;
+            if (fanout >= SYNTHESIS_MIN_AGENTS)
+                pushReminder(synthesisReminder(fanout));
+        }
         // Todo attention-refresh: a round that touched the checklist resets the clock; rounds that leave
         // unfinished items untouched accumulate, and at TODO_STALE_ROUNDS the model gets a system-reminder
         // re-showing the authoritative list (then the counter re-arms — at most one nag per N rounds).

package/dist/agent/reminders.js

@@ -30,6 +30,15 @@ export function wrapReminders(items) {
 /** How many tool rounds a checklist may sit untouched (with unfinished items) before the model gets an
  *  attention refresh. Reset on every todo_write; re-arms after firing so it nags at most once per N. */
 export const TODO_STALE_ROUNDS = 5;
+/** Parallel fan-outs at/above this size get a synthesis nudge (CC's KN5 synthesizer, hara-shaped:
+ *  instead of a dedicated merger agent, the MAIN model is reminded to merge before acting). */
+export const SYNTHESIS_MIN_AGENTS = 3;
+/** The synthesis nudge: N independent reports just landed — reconcile before acting. */
+export function synthesisReminder(n) {
+    return (`You just received ${n} parallel agent reports. Before acting, SYNTHESIZE them into one coherent ` +
+        "picture: reconcile overlaps and conflicts explicitly (say which report wins and why), note anything " +
+        "only one report saw, and state the merged conclusion. Don't act on a single report in isolation.");
+}
 /** The staleness nudge: re-show the authoritative list + ask for a status pass. */
 export function todoStaleReminder(renderedTodos) {
     return (`Your todo list has not been updated in a while. Current state:\n\n${renderedTodos}\n\n` +

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";
@@ -744,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

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/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.103.0",
+  "version": "0.105.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"