@nanhara/hara 0.99.3 → 0.100.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.100.0 — the agent keeps its own attention: system-reminders + anti-drift compaction
+
+Distilled from a source-level study of Claude Code v1.0.33's agent internals (the Ie1/WD5 reminder
+layer and the AU2 compaction template).
+
+- **system-reminder injection layer.** An event queue (`agent/reminders.ts`) that lands queued context
+  as ONE `<system-reminder>`-wrapped message before the next model call — visible to the model, never
+  rendered in the transcript, and always carrying the "ignore unless relevant" disclaimer so a nudge
+  can't derail unrelated work. Quiet (sub-agent) runs neither drain nor push, so parallel fan-outs
+  can't steal the main conversation's reminders. First wired event:
+- **Todo attention-refresh.** When a checklist has unfinished items and goes 5 tool-rounds untouched,
+  the model gets a reminder re-showing the authoritative list and asking for a status pass — so long
+  tasks stop silently abandoning their own plan. Any `todo_write` resets the clock; after firing it
+  re-arms (at most one nag per 5 rounds).
+- **Compaction brief: 6 → 8 sections (anti-drift).** `/compact` and auto-compaction now also preserve
+  **All user messages** — your own words survive verbatim, in order, however hard the history is
+  squeezed — and **Key technical concepts**, so the next turn doesn't re-derive the stack.
+  (`COMPACT_SYSTEM` moved to `agent/compact.ts` where tests pin the structure.)
+
 ## 0.99.3 — TUI: rock-steady input box (constant-height chrome) + plan mode grows a real handshake
 
 Built from a source-level study of codex-rs (bottom-anchored viewport, plan cells) and Claude Code

package/README.md

@@ -13,7 +13,7 @@
 **Highlights**
 - **An org, not just an agent** — `hara org "<task>"` routes work to the role that *owns* it; `hara plan "<task>"` decomposes a task into a verified DAG of atoms (frame → atomize → sequence → execute → **verify gate**), and `hara plan --parallel` runs independent atoms concurrently.
 - **Drive it from chat** — `hara gateway` runs your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal** (10 platforms), with **two-way images** (send a photo → it sees it; ask for a file → it sends one), per-chat resumable sessions, and project roaming. Connects out — no public webhook. See **[docs/gateway.md](docs/gateway.md)**.
-- **Real terminal UX** — an **ink TUI**: bottom-pinned input box, **plan mode** (read-only → propose a plan → approve → execute), selectable approvals with "don't ask again", windowed reasoning, **paste images** (Ctrl+V) for vision models, light/dark theme.
+- **Real terminal UX** — an **ink TUI**: bottom-pinned input box, **plan mode** (read-only investigation → the model submits its plan via `exit_plan` → approve → execute), selectable approvals with "don't ask again", windowed reasoning, **paste images** (Ctrl+V) for vision models, light/dark theme.
 - **Persistent memory + self-evolution** — `memory_*` tools over global/project `MEMORY.md`; the agent recalls before acting, **proactively saves** durable facts, and grows its own playbooks (a lexical guard screens what it writes). Inspect/consolidate it with **`hara memory show`** and **`hara memory distill`** (promote recent daily logs → durable memory). Lexical-first by design — semantic search is opt-in, never required.
 - **Multi-provider, all streamed** — Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) with live Markdown + visible reasoning.
 - **Delegate to other agents** — the **`external_agent`** tool hands a self-contained task to **Claude Code** or **Codex** running headless, and returns the result — so you pick the best engine per task. Gated by approval, trust-tiered, and never exposed to read-only sub-agents.

package/dist/agent/compact.js

@@ -3,6 +3,23 @@
 // which reuses the manual /compact path; this just decides *when* to fire.
 /** Auto-compact once the last turn used ≥ this % of the model's context window. */
 export const AUTO_COMPACT_PCT = 85;
+/** The compaction brief (shared by /compact and auto-compaction). Eight sections, mirroring Claude
+ *  Code's AU2 template — the two that matter most beyond the obvious: **All user messages** (the
+ *  user's own words survive verbatim, so however hard the history is squeezed, intent never drifts)
+ *  and **Key technical concepts** (the frameworks/APIs in play, so the next turn doesn't re-derive
+ *  the stack). Lives here (not index.ts) so tests can pin the structure. */
+export const COMPACT_SYSTEM = "Summarize the conversation so far into a structured, complete brief so the assistant can continue with NO " +
+    "loss of context. First think privately in a brief <analysis> scratchpad (what matters, what's in flight), " +
+    "then output ONLY the summary under these exact headings:\n" +
+    "1. Goal — the user's overall intent, in their own framing.\n" +
+    "2. Key technical concepts — the frameworks, tools, APIs, and domain ideas central to the work.\n" +
+    "3. Key decisions — choices made and why (so they aren't relitigated).\n" +
+    "4. Files & code — files created/changed and the important snippets, with why each matters.\n" +
+    "5. Errors & fixes — failures hit, how they were resolved, and any correction the user gave (quote pointed feedback verbatim).\n" +
+    "6. Current state — what works now / what is verified.\n" +
+    "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.";
 /** 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

@@ -10,7 +10,8 @@ import { decideCommand, loadPermissionRules } from "../security/permissions.js";
 import { classifyRisk, guardianVeto, guardianEnabled, newBreaker, recordBlock } from "../security/guardian.js";
 import { subdirHint } from "../context/subdir-hints.js";
 import { classifyError, failoverAction, errorHint } from "./failover.js";
-import { currentTodos } from "../tools/todo.js";
+import { currentTodos, renderTodos } from "../tools/todo.js";
+import { drainReminders, wrapReminders, pushReminder, todoStaleReminder, TODO_STALE_ROUNDS } from "./reminders.js";
 /** 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. */
@@ -86,6 +87,9 @@ export async function runAgent(history, opts) {
     const guardianOn = !!opts.guardian && (opts.guardian.enabled ?? true) && guardianEnabled();
     const breaker = newBreaker();
     let breakerHalt = false; // set when a tripped breaker aborts this run
+    // Todo attention-refresh (à la Claude Code): tool rounds since the checklist was last touched while
+    // unfinished items exist. Main loop only — quiet (sub-agent) runs share the global list and must not nag.
+    let todoIdleRounds = 0;
     for (;;) {
         // Type-ahead steering: fold in anything the user submitted while the previous step ran, so it
         // reaches the model on this next call (drained after the last tool round; empty on the 1st pass).
@@ -93,6 +97,14 @@ export async function runAgent(history, opts) {
             for (const m of await opts.pendingInput())
                 history.push(m);
         }
+        // system-reminder injection: event-driven context queued since the last call (todo staleness today)
+        // lands as ONE wrapped user message the UI never renders. Quiet runs don't drain — a parallel
+        // sub-agent must not steal the main conversation's reminders.
+        if (!opts.quiet) {
+            const reminders = drainReminders();
+            if (reminders.length)
+                history.push({ role: "user", content: wrapReminders(reminders) });
+        }
         const baseSpecs = opts.toolFilter ? toolSpecs().filter((t) => opts.toolFilter(t.name)) : toolSpecs();
         const specs = opts.extraTools?.length
             ? [...baseSpecs, ...opts.extraTools.map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema }))]
@@ -349,6 +361,21 @@ export async function runAgent(history, opts) {
         }
         await flush();
         history.push({ role: "tool", results });
+        // 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).
+        if (!opts.quiet) {
+            if (r.toolUses.some((tu) => tu.name === "todo_write")) {
+                todoIdleRounds = 0;
+            }
+            else if (currentTodos().some((t) => t.status !== "done")) {
+                todoIdleRounds++;
+                if (todoIdleRounds >= TODO_STALE_ROUNDS) {
+                    pushReminder(todoStaleReminder(renderTodos(currentTodos())));
+                    todoIdleRounds = 0;
+                }
+            }
+        }
         if (breakerHalt) {
             // A tripped-and-declined circuit-breaker is a hard stop: end the run cleanly (the denial messages are
             // already in `results` so the model/user see why). Never spin further.

package/dist/agent/reminders.js

@@ -0,0 +1,38 @@
+// system-reminder injection (à la Claude Code's Ie1/WD5 event layer): event-driven context the model
+// should see on its NEXT call, injected as ONE `<system-reminder>`-wrapped user message. It rides the
+// provider history only — the UI transcript never renders it, so the user isn't bothered while the
+// model stays synchronized with system state (todo staleness today; file-change/diagnostic events can
+// plug in later via pushReminder).
+//
+// Claude Code's disclaimer is preserved: the model is told the context may be irrelevant, so an
+// injected nudge never derails an unrelated task.
+const queue = [];
+/** Queue a reminder for injection before the next model call (main loop only — quiet/sub-agent runs
+ *  neither push nor drain, so a parallel fan-out can't steal the main conversation's reminders). */
+export function pushReminder(text) {
+    const t = text.trim();
+    if (t)
+        queue.push(t);
+}
+/** Take everything queued (FIFO), clearing the queue. */
+export function drainReminders() {
+    if (!queue.length)
+        return [];
+    return queue.splice(0, queue.length);
+}
+/** Merge queued reminders into the single injected message. */
+export function wrapReminders(items) {
+    return ("<system-reminder>\n" +
+        items.join("\n\n") +
+        "\n\nThis context may or may not be relevant to your task — do not respond to it directly; ignore it unless it is relevant.\n" +
+        "</system-reminder>");
+}
+/** 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;
+/** 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` +
+        "If you have completed or started items, update them with todo_write now (statuses drive the user's progress view). " +
+        "If the list no longer matches the work, rewrite it.");
+}

package/dist/index.js

@@ -24,7 +24,7 @@ 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 } from "./agent/compact.js";
+import { shouldAutoCompact, COMPACT_SYSTEM } from "./agent/compact.js";
 import { formatContextReport } from "./agent/context-report.js";
 import { userTurnPreviews, rewindTo } from "./agent/rewind.js";
 import { checkpoint, listCheckpoints, restoreCheckpoint } from "./checkpoints.js";
@@ -716,16 +716,7 @@ const MEMORY_DISTILL_SYSTEM = "You consolidate an agent's short-term daily memor
     "conventions / user preferences from the logs that are NOT already captured, and persist each with " +
     "memory_write (target=memory, or target=user for preferences; pick the right scope=project|global). " +
     "Skip the ephemeral, the one-off, and anything already known. Be terse and de-duplicated. Then reply DONE.";
-const COMPACT_SYSTEM = "Summarize the conversation so far into a structured, complete brief so the assistant can continue with NO " +
-    "loss of context. First think privately in a brief <analysis> scratchpad (what matters, what's in flight), " +
-    "then output ONLY the summary under these exact headings:\n" +
-    "1. Goal — the user's overall intent, in their own framing.\n" +
-    "2. Key decisions — choices made and why (so they aren't relitigated).\n" +
-    "3. Files & code — files created/changed and the important snippets, with why each matters.\n" +
-    "4. Errors & fixes — failures hit, how they were resolved, and any correction the user gave (quote pointed feedback verbatim).\n" +
-    "5. Current state — what works now / what is verified.\n" +
-    "6. 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.";
+// COMPACT_SYSTEM (the 8-section brief) lives in agent/compact.ts so tests can pin its structure.
 const workingSetFromSummary = (s) => s
     .split("\n")
     .map((l) => l.replace(/^[-*\d.\s]+/, "").trim())

package/dist/org/roles.js

@@ -22,13 +22,37 @@ export function orgRolesDir() {
 export function claudeAgentsDir(cwd) {
     return join(findProjectRoot(cwd), ".claude", "agents");
 }
-/** Accept Claude-Code `tools:` (comma string or list) as an alias for hara's allowTools. */
-function claudeTools(v) {
-    if (Array.isArray(v))
-        return v;
-    if (typeof v === "string" && v.trim())
-        return v.split(",").map((s) => s.trim()).filter(Boolean);
-    return undefined;
+/** Claude-Code tool names → hara tool names, for `.claude/agents` interop. Without this, a CC agent
+ *  with `tools: Read, Edit, Bash` produced allowTools that matched ZERO hara tools — the role spawned
+ *  with an empty toolbox. Unknown names pass through verbatim (they may be hara names already). */
+const CLAUDE_TOOL_MAP = {
+    read: "read_file",
+    edit: "edit_file",
+    write: "write_file",
+    bash: "bash",
+    grep: "grep",
+    glob: "glob",
+    ls: "ls",
+    webfetch: "web_fetch",
+    websearch: "web_search",
+    agent: "agent",
+    task: "agent",
+    todowrite: "todo_write",
+    notebookedit: "edit_file",
+};
+/** Accept Claude-Code `tools:` (comma string or list) as an alias for hara's allowTools —
+ *  translating CC tool names to hara's. "All tools" / "*" means unrestricted → undefined. */
+export function claudeTools(v) {
+    const raw = Array.isArray(v)
+        ? v
+        : typeof v === "string" && v.trim()
+            ? v.split(",").map((s) => s.trim()).filter(Boolean)
+            : null;
+    if (!raw || !raw.length)
+        return undefined;
+    if (raw.some((t) => /^(\*|all tools?)$/i.test(t)))
+        return undefined; // unrestricted
+    return raw.map((t) => CLAUDE_TOOL_MAP[t.toLowerCase().replace(/[^a-z]/g, "")] ?? t);
 }
 function parseFrontmatter(text) {
     const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
@@ -83,7 +107,9 @@ export function loadRoles(cwd) {
                     description: fm.description || "",
                     owns: Array.isArray(fm.owns) ? fm.owns : [],
                     rejects: Array.isArray(fm.rejects) ? fm.rejects : [],
-                    model: fm.model || undefined,
+                    // Claude-Code model ALIASES (sonnet/opus/haiku/inherit) aren't hara model ids — treat as
+                    // "inherit the session model" rather than passing a string no provider resolves.
+                    model: fm.model && !/^(sonnet|opus|haiku|inherit)$/i.test(String(fm.model)) ? fm.model : undefined,
                     allowTools: Array.isArray(fm.allowTools) ? fm.allowTools : claudeTools(fm.tools),
                     denyTools: Array.isArray(fm.denyTools) ? fm.denyTools : undefined,
                     system: body,

package/package.json

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