@nanhara/hara 0.126.0 → 0.127.0

package/dist/providers/anthropic.js

@@ -56,13 +56,14 @@ const CACHE = { type: "ephemeral" };
  *  conversation prefix FROM CACHE instead of re-billing + re-processing the whole prompt — the single
  *  biggest latency + cost win as history grows (uncached, a long session pays full input every turn).
  *
- *  Anthropic caps breakpoints at 4 and orders the cache prefix `tools → system → messages`, so a mark
- *  on `system` already caches tools+system (the big static block) in one shot. We then spend up to two
- *  rolling marks near the message tail: the last message (so THIS turn's full prefix is written) and one
- *  ~2 back (so the NEXT turn — which appends new messages — still finds a long cached prefix to read).
+ *  Anthropic caps breakpoints at 4 and orders the cache prefix `tools → system → messages`. Structured Hara
+ *  prompts spend up to two marks on the static and session boundaries, leaving the changing turn suffix
+ *  uncached; legacy strings keep one system mark. We then spend up to two rolling marks near the message
+ *  tail: the last message (so THIS turn's full prefix is written) and one ~2 back (so the NEXT turn — which
+ *  appends new messages — still finds a long cached prefix to read).
  *  Mutates `messages` in place (toAnthropic hands us a fresh array each turn); returns the request-shaped
  *  system. Exported pure for tests. */
-export function applyCacheControl(system, messages) {
+export function applyCacheControl(system, messages, systemParts) {
     const mark = (m) => {
         if (typeof m.content === "string") {
             if (m.content.length)
@@ -80,7 +81,29 @@ export function applyCacheControl(system, messages) {
     for (const i of idxs)
         mark(messages[i]);
     // Only cache system when it's substantial enough to matter (an empty text block would 400).
-    const cachedSystem = system ? [{ type: "text", text: system, cache_control: CACHE }] : system;
+    let cachedSystem = system;
+    const renderedParts = systemParts?.map((part) => part.content).join("\n\n");
+    if (system && systemParts?.length && renderedParts === system) {
+        const sections = [];
+        for (const part of systemParts) {
+            const tail = sections.at(-1);
+            if (tail?.stability === part.stability)
+                tail.text += `\n\n${part.content}`;
+            else
+                sections.push({ stability: part.stability, text: part.content });
+        }
+        cachedSystem = sections.map((section, index) => ({
+            type: "text",
+            // Anthropic concatenates adjacent text blocks directly. Preserve the authoritative rendered string
+            // byte-for-byte across our cache boundaries.
+            text: section.text + (index < sections.length - 1 ? "\n\n" : ""),
+            ...(section.stability === "turn" ? {} : { cache_control: CACHE }),
+        }));
+    }
+    else if (system) {
+        // Legacy/custom callers still receive the original single cached system block.
+        cachedSystem = [{ type: "text", text: system, cache_control: CACHE }];
+    }
     return { system: cachedSystem, messages };
 }
 /** Anthropic models whose only valid `thinking` setting is `{type: "adaptive"}` — they reject any
@@ -116,9 +139,9 @@ export function createAnthropicProvider(opts) {
     return {
         id: "anthropic",
         model: opts.model,
-        async turn({ system, history, tools, onText, onReasoning, signal }) {
+        async turn({ system, systemParts, history, tools, onText, onReasoning, signal }) {
             const thinking = buildThinkingParam(opts.model, opts.reasoningEffort);
-            const { system: cachedSystem, messages } = applyCacheControl(system, toAnthropic(history));
+            const { system: cachedSystem, messages } = applyCacheControl(system, toAnthropic(history), systemParts);
             const stream = client.messages.stream({
                 model: opts.model,
                 max_tokens: 32000,

package/dist/security/private-state.js

@@ -8,7 +8,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { FileReadLimitError, MAX_EDIT_READ_BYTES, decodeUtf8Strict, openVerifiedRegularFileNoFollow, verifyOpenedRegularFileSync, } from "../fs-read.js";
 import { optionalPosixOpenFlag } from "../fs-open-flags.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
-const PRIVATE_TREES = new Set(["sessions", "checkpoints", "index", "gateway", "cron", "weixin", "tool-results"]);
+const PRIVATE_TREES = new Set(["sessions", "checkpoints", "index", "gateway", "cron", "weixin", "tool-results", "plugin-receipts"]);
 const tightenedHomes = new Set();
 const DEFAULT_MIGRATION_CAP = 50_000;
 function isMissing(error) {

package/dist/serve/protocol.js

@@ -33,6 +33,8 @@
 // Server → client notifications (all carry sessionId):
 //   event.text / event.reasoning {delta} · event.tool {name,preview} · event.diff {text}
 //   event.notice {text} · event.turn_end {reply,usage,error?} · approval.request {approvalId,question}
+//   event.task_state {version,taskId,turnId,objective,state,taskStatus,phase,checkpoint,…}
+//                     authoritative execution plane; clients feature-detect it via capabilities.events
 export const PROTOCOL_VERSION = 1;
 /** JSON-RPC error codes: standard ones plus hara-specific (-320xx). */
 export const ERR = {

package/dist/serve/server.js

@@ -27,10 +27,11 @@ import { loadJobs, addJob, removeJob, setEnabled } from "../cron/store.js";
 import { parseSchedule, describeSchedule } from "../cron/schedule.js";
 import { loadTasks } from "../tools/task.js";
 import { listPending, resolvePending } from "../gateway/flows-pending.js";
-import { disposeTodoScope, restoreTodos, serializeTodos } from "../tools/todo.js";
+import { disposeTodoScope, onTodosChange, restoreTodos, serializeTodos } from "../tools/todo.js";
 import { INTERJECT_PREFIX, disposeReminderScope } from "../agent/reminders.js";
 import { SessionHub, realStore } from "./sessions.js";
 import { parseFrame, rpcResult, rpcError, rpcNotify, ERR, PROTOCOL_VERSION } from "./protocol.js";
+import { taskLifecycleEvent } from "./task-events.js";
 import { readModelContextFileSync } from "../fs-read.js";
 import { optionalPosixOpenFlag } from "../fs-open-flags.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
@@ -228,8 +229,15 @@ export function lastAssistantText(history) {
 export function historyForClient(history) {
     const out = [];
     for (const m of history) {
-        if (m.role === "user")
-            out.push({ role: "user", text: m.content });
+        if (m.role === "user") {
+            const steeringPrefix = `${INTERJECT_PREFIX}\n\n`;
+            out.push({
+                role: "user",
+                text: m.content.startsWith(steeringPrefix)
+                    ? m.content.slice(steeringPrefix.length)
+                    : m.content,
+            });
+        }
         else if (m.role === "assistant" && m.text)
             out.push({ role: "assistant", text: m.text });
         // tool results are omitted — clients see live tool events; persisted detail stays in the store
@@ -333,6 +341,11 @@ export async function startServe(opts, deps) {
             if (ws.readyState === ws.OPEN)
                 ws.send(frame);
     };
+    const broadcastTaskState = (session, activity) => {
+        if (!session.task)
+            return;
+        broadcast("event.task_state", { ...taskLifecycleEvent(session.meta.id, session.task, session.meta.todos ?? [], activity) });
+    };
     // Discovery file — the desktop shell reads this to find the running server (like a pid/port file).
     const discoveryDir = join(deps.discoveryHome ?? homedir(), ".hara");
     const discoveryPath = join(discoveryDir, "serve.json");
@@ -413,13 +426,37 @@ export async function startServe(opts, deps) {
             s.busy = false;
             throw error;
         }
+        let lastTaskStateSignature = "";
+        const emitTaskState = (activity, todos = s.meta.todos ?? []) => {
+            if (!s.task)
+                return;
+            const event = taskLifecycleEvent(sessionId, s.task, todos, activity);
+            const { at: _at, ...stableEvent } = event;
+            const signature = JSON.stringify(stableEvent);
+            if (signature === lastTaskStateSignature)
+                return;
+            lastTaskStateSignature = signature;
+            broadcast("event.task_state", { ...event });
+        };
         broadcast("event.turn_start", { sessionId, taskId: s.task.id, turnId: s.task.turnId });
+        emitTaskState({ state: "running", phase: "starting" });
         const historyStart = s.history.length;
         const before = { input: s.stats.input, output: s.stats.output };
         const sink = {
-            text: (d) => broadcast("event.text", { sessionId, delta: d }),
-            reasoning: (d) => broadcast("event.reasoning", { sessionId, delta: d }),
-            tool: (name, preview) => broadcast("event.tool", { sessionId, name, preview }),
+            text: (d) => {
+                emitTaskState({ state: "running", phase: "responding" });
+                broadcast("event.text", { sessionId, delta: d });
+            },
+            reasoning: (d) => {
+                emitTaskState({ state: "running", phase: "thinking" });
+                broadcast("event.reasoning", { sessionId, delta: d });
+            },
+            tool: (name, preview) => {
+                // The task/status plane is safe for ambient surfaces such as an always-on-top companion.
+                // Command/path previews remain on the explicit event.tool transcript plane only.
+                emitTaskState({ state: "running", phase: "tool", detail: name });
+                broadcast("event.tool", { sessionId, name, preview });
+            },
             diff: (t) => broadcast("event.diff", { sessionId, text: t }),
             notice: (t) => broadcast("event.notice", { sessionId, text: t }),
         };
@@ -434,6 +471,13 @@ export async function startServe(opts, deps) {
                 clearTimeout(timer);
                 pendingApprovals.delete(approvalId);
                 signal.removeEventListener("abort", onAbort);
+                if (!signal.aborted && s.task?.status === "running") {
+                    emitTaskState({
+                        state: "running",
+                        phase: "thinking",
+                        detail: v === false ? "Approval denied; continuing safely" : "Approval granted; continuing",
+                    });
+                }
                 resolve(v);
             };
             const onAbort = () => finish(false);
@@ -445,15 +489,28 @@ export async function startServe(opts, deps) {
                 // `signal` composes the owning turn cancellation with runAgent's lifecycle cancellation. Listening
                 // only to turnAbort would leave the approval map and Desktop prompt stale after an internal stop.
                 signal.addEventListener("abort", onAbort, { once: true });
+                emitTaskState({
+                    state: "waiting",
+                    phase: "approval",
+                    detail: q,
+                    approval: { id: approvalId, question: q },
+                });
                 broadcast("approval.request", { sessionId, approvalId, question: q });
             }
         });
+        let stopTodoEvents = () => { };
         try {
             if (!(await refreshSessionProvider(s))) {
                 throw new Error(`provider not authenticated for pinned model '${s.meta.model}' at ${s.meta.cwd}`);
             }
             const turnGuardian = deps.buildGuardian ? await deps.buildGuardian(s.meta.cwd) : deps.guardian;
             restoreTodos(s.meta.todos, sessionId);
+            stopTodoEvents = onTodosChange((todos) => {
+                // Keep the session snapshot current while the turn runs. Steering and task-intake checkpoints can
+                // then publish/persist the same checklist the model just wrote instead of regressing to turn-start.
+                s.meta.todos = serializeTodos(sessionId);
+                emitTaskState({ state: "running", phase: "checkpoint" }, s.meta.todos);
+            }, sessionId);
             // Slash skills, CLI parity: "/skill-id request…" expands into the skill-entering message, so a
             // desktop composer's "/" popup triggers the exact behavior the terminal gets. Unknown ids fall
             // through as plain text (the model sees what the user typed).
@@ -495,10 +552,12 @@ export async function startServe(opts, deps) {
                         current: () => s.task,
                         onUpdate: (next) => {
                             s.task = next;
+                            emitTaskState({ state: "running", phase: "checkpoint" }, serializeTodos(sessionId));
                         },
                         onCheckpoint: (next) => {
                             s.task = next;
                             hub.save(s);
+                            emitTaskState({ state: "running", phase: "checkpoint" }, serializeTodos(sessionId));
                         },
                     },
                     pendingInput: async () => {
@@ -521,6 +580,7 @@ export async function startServe(opts, deps) {
             s.meta.todos = serializeTodos(sessionId);
             s.task = finishTaskExecution(s.task, outcome, s.meta.todos, turnAbort.signal.aborted);
             hub.save(s);
+            emitTaskState({ phase: "finished" }, s.meta.todos);
             const usage = { input: s.stats.input - before.input, output: s.stats.output - before.output };
             // context watermark rides along with every turn end (codex thread/tokenUsage/updated pattern) —
             // clients render a meter without an extra round-trip.
@@ -544,10 +604,12 @@ export async function startServe(opts, deps) {
             if (s.task?.status === "running") {
                 s.task = finishTaskExecution(s.task, { status: "error", error: error instanceof Error ? error.message : String(error) }, s.meta.todos ?? [], turnAbort.signal.aborted);
                 hub.save(s);
+                emitTaskState({ phase: "finished" }, s.meta.todos ?? []);
             }
             throw error;
         }
         finally {
+            stopTodoEvents();
             s.abort = null;
             s.busy = s.pendingProviderTurns > 0 || s.pendingToolRuns > 0;
         }
@@ -682,7 +744,7 @@ export async function startServe(opts, deps) {
                             provider: runtime.providerId,
                             model: runtime.model,
                             setupState,
-                            capabilities: { methods },
+                            capabilities: { methods, events: ["event.task_state"] },
                         }));
                     }
                     if (!authed.has(ws))
@@ -749,6 +811,7 @@ export async function startServe(opts, deps) {
                                 return reply(rpcError(id, ERR.INTERNAL, `provider not authenticated for pinned model '${r.session.meta.model}'`));
                             }
                             r.session.projectContext = loadAgentContext(r.session.meta.cwd) || undefined;
+                            broadcastTaskState(r.session, { phase: "restored" });
                             return reply(rpcResult(id, {
                                 sessionId: r.session.meta.id,
                                 model: r.session.meta.model,
@@ -791,12 +854,16 @@ export async function startServe(opts, deps) {
                                 return reply(rpcError(id, ERR.BUSY, recorded.reason));
                             s.task = recorded.task;
                             hub.save(s); // executable inbox entry is durable before ACK
+                            broadcastTaskState(s, { state: "running", phase: "steering", detail: "Steering accepted" });
                             return reply(rpcResult(id, { accepted: true, taskId: s.task.id, turnId: s.task.turnId }));
                         }
                         case "session.interrupt": {
                             const s = typeof p.sessionId === "string" ? hub.get(p.sessionId) : undefined;
                             if (!s)
                                 return reply(rpcError(id, ERR.NO_SESSION, "no such live session"));
+                            if (s.abort && s.task?.status === "running") {
+                                broadcastTaskState(s, { state: "running", phase: "stopping", detail: "Stopping at a safe boundary" });
+                            }
                             s.abort?.abort();
                             return reply(rpcResult(id, {}));
                         }

package/dist/serve/task-events.js

@@ -0,0 +1,45 @@
+export const TASK_LIFECYCLE_EVENT_VERSION = 1;
+function bounded(value, max) {
+    const normalized = value?.replace(/\s+/g, " ").trim();
+    return normalized ? normalized.slice(0, max) : undefined;
+}
+/** Build the single task-state shape consumed by Desktop, IDE clients, and the companion. Conversation
+ * streaming remains separate; this event is the authoritative execution/status plane. */
+export function taskLifecycleEvent(sessionId, task, todos = [], activity, at = new Date().toISOString()) {
+    const current = todos.find((todo) => todo.status === "in_progress")
+        ?? todos.find((todo) => todo.status === "pending");
+    const detail = bounded(activity.detail, 500);
+    const approval = activity.approval
+        ? {
+            id: activity.approval.id,
+            question: bounded(activity.approval.question, 4_000) ?? "Approval required",
+        }
+        : undefined;
+    // Runtime phases may only refine an actively running task. Once durable state reaches a terminal or
+    // resumable boundary, a late notification cannot visually resurrect it as running/waiting.
+    const state = task.status === "running"
+        ? (activity.state ?? task.status)
+        : task.status;
+    return {
+        version: TASK_LIFECYCLE_EVENT_VERSION,
+        sessionId,
+        taskId: task.id,
+        turnId: task.turnId,
+        objective: task.objective,
+        state,
+        taskStatus: task.status,
+        phase: activity.phase,
+        at,
+        updatedAt: task.updatedAt,
+        ...(task.lastOutcome ? { lastOutcome: task.lastOutcome } : {}),
+        ...(task.brief ? { brief: { intent: task.brief.intent, goal: task.brief.goal } } : {}),
+        checkpoint: {
+            done: todos.filter((todo) => todo.status === "done").length,
+            total: todos.length,
+            ...(current ? { current: bounded(current.activeForm || current.text, 300) } : {}),
+            ...(current?.owner ? { owner: bounded(current.owner, 120) } : {}),
+        },
+        ...(detail ? { detail } : {}),
+        ...(approval ? { approval } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.126.0",
+  "version": "0.127.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "runtime-bootstrap.cjs"