@nanhara/hara 0.113.0 → 0.115.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.115.0 — serve exposes plugins & skills (desktop plugin panel)
+
+- **`hara serve` protocol grows a plugin surface**: `plugins.list` (installed plugins with enabled state +
+  contribution counts), `plugins.set` (enable/disable by name — applies to future sessions/turns), and
+  `skills.list` (the skill index for a cwd). This powers the hara desktop app's plugin manager panel;
+  any WS client gets it for free.
+
+## 0.114.0 — long files read in slices · repeat-guard anti-spinning · `hara serve` (the desktop/IDE backbone)
+
+- **Long files no longer flood the context.** `read_file` now returns cat-n numbered lines with
+  `offset`/`limit` slicing (2000-line default window, per-line truncation, a header that says how to
+  continue). The old behavior dumped the whole file (100K-char cap) — ~25k tokens per read, tail
+  unreachable. Paired prompt rules: grep-then-slice on long files, and **no whole-file re-read after a
+  successful edit** (the slowest habit an agent can have). This is the "hara is slow on long files" fix.
+- **Repeat-guard — the anti-spinning tripwire.** When the EXACT same tool call (same tool, same
+  arguments) fails twice in a row, the result now carries an explicit "repeating this unchanged will
+  fail again — change something or ask the user" note. The guardian breaker covers DENIED actions;
+  this covers FAILED ones (observed: 4× the same `git pull` into a dead network). Successes reset the
+  streak; `/reset` clears it. Plus prompt rules: diagnose before retrying, two failed variants → step
+  back and re-plan.
+- **`hara serve` — a persistent local server (WebSocket JSON-RPC v1)** that desktop shells, ACP and
+  IDE clients drive: `initialize` (token auth) · `session.create/resume/list/send/interrupt` ·
+  streamed `event.text/reasoning/tool/diff/notice/turn_end` · **approval round-trips**
+  (`approval.request` ⇄ `approval.reply`, 5-min deny-timeout, deny-on-disconnect) · sessions are the
+  SAME `~/.hara/sessions` store the CLI uses (single-writer lock respected) · `~/.hara/serve.json`
+  discovery file. This is the backbone the new hara desktop app (Tauri) speaks to.
+- `tools/all.ts` — library entries (serve, embedders) now register the full built-in toolset; an
+  unregistered tool was silently unplannable.
+
 ## 0.113.0 — DeepSeek reasoning control (thinking + effort, incl. `max`) · host-unreachable memory
 
 - **DeepSeek reasoning is now a real dial.** DeepSeek's V4 models (`deepseek-v4-pro` / `deepseek-v4-flash`)

package/dist/agent/loop.js

@@ -8,6 +8,7 @@ import { runHooks } from "../hooks.js";
 import { mapLimit, maxParallel } from "../concurrency.js";
 import { decideCommand, loadPermissionRules } from "../security/permissions.js";
 import { classifyRisk, guardianVeto, guardianEnabled, newBreaker, recordBlock } from "../security/guardian.js";
+import { recordCall } from "./repeat-guard.js";
 import { subdirHint } from "../context/subdir-hints.js";
 import { classifyError, failoverAction, errorHint } from "./failover.js";
 import { currentTodos, renderTodos } from "../tools/todo.js";
@@ -57,7 +58,14 @@ them whole. Batch INDEPENDENT tool calls in a single response — especially rea
 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,
+grep/glob; don't read whole large files when a targeted search answers the question. For a long file,
+grep to locate then read_file just that region with offset/limit — not the whole file. After a successful
+edit_file/write_file do NOT re-read the file to verify — the tool already applied and diffed the change;
+re-reading a big file after every edit is the slowest habit an agent can have.
+When an attempt FAILS, never repeat it unchanged — read the error, form a hypothesis about the cause, and
+change something (arguments / approach / tool) before trying again. After two failed variants of the same
+approach, stop: re-plan from what you learned, or ask the user, stating concisely what you tried and what
+the errors said. Repeating a failed action hoping for a different result is how sessions die. 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. Messages the user sends
 mid-task arrive marked as interjections — triage them (refine current / queue as todo / urgent-switch)
@@ -437,11 +445,13 @@ export async function runAgent(history, opts) {
                 }
                 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) };
+                // + the repeat-guard's anti-spinning note when this exact call keeps failing (repeat-guard.ts)
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: res + subdirHint(p.tu.input, ctx.cwd) + recordCall(p.tu.name, p.tu.input, res) };
                 runHooks("PostToolUse", p.tu.name, { input: p.tu.input, result: res }, ctx.cwd); // observe-only
             }
             catch (e) {
-                results[idx] = { id: p.tu.id, name: p.tu.name, content: `Error: ${e.message}`, isError: true };
+                const msg = `Error: ${e.message}`;
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: msg + recordCall(p.tu.name, p.tu.input, msg, true), isError: true };
             }
             finally {
                 activity.dec();

package/dist/agent/repeat-guard.js

@@ -0,0 +1,42 @@
+// Repeat guard — the anti-spinning tripwire. The classic way an agent wastes a session is repeating the
+// EXACT same failing tool call, unchanged, expecting a different result (observed: 4x `git pull` into the
+// same wall; Nx the same failing build command). The guardian breaker only covers DENIED actions; this
+// covers FAILED ones. Deterministic and session-scoped (module state, same pattern as net-reachability):
+// when an identical (tool, args) call fails twice in a row, the tool result gets an explicit "stop
+// repeating this" note the model can't miss. Successful repeats are NOT flagged — a re-read after an edit
+// or a re-run after a fix is legitimate, and a success resets the failure streak.
+const seen = new Map();
+/** Identity of a call = tool name + exact JSON of its arguments (tool names contain no spaces,
+ *  so a space separator is unambiguous). */
+export function keyOf(name, input) {
+    try {
+        return name + " " + JSON.stringify(input ?? {});
+    }
+    catch {
+        return name + " <unserializable>";
+    }
+}
+/** Does a tool RESULT string look like a failure? hara tools report failures as ordinary strings
+ *  (bash -> "Command failed: ...", file tools -> "Error: ...", net guard -> "Skipped without running: ..."),
+ *  so the loop's isError flag alone misses them. Pure — exported for tests. */
+export function looksFailed(content) {
+    return /^\s*(Command failed|Error\b|Skipped without running)/.test(content);
+}
+/** Record a completed call; returns a warning to APPEND to the tool result when the same call has now
+ *  failed >=2x in a row (empty string otherwise). Pure aside from the session-scoped map. */
+export function recordCall(name, input, content, isError = false) {
+    const k = keyOf(name, input);
+    const failed = isError || looksFailed(content);
+    const s = seen.get(k) ?? { fails: 0 };
+    s.fails = failed ? s.fails + 1 : 0; // success resets the streak
+    seen.set(k, s);
+    if (s.fails < 2)
+        return "";
+    return (`\n\n⟳ hara: this exact ${name} call has now FAILED ${s.fails}× with identical arguments — ` +
+        `repeating it unchanged will fail again. Read the error above, change something (arguments / approach / tool), ` +
+        `or step back and re-plan; if you're out of ideas, ask the user and say what you tried.`);
+}
+/** Clear the streaks — /reset (fresh start) and tests. */
+export function resetRepeatGuard() {
+    seen.clear();
+}

package/dist/cron/deliver.js

@@ -1,12 +1,3 @@
-// Cron result delivery — push a finished job's output to a chat channel (openclaw/hermes parity),
-// WITHOUT needing the gateway process: adapters are constructed one-shot from the same env vars the
-// gateway uses, send once, and are dropped. Spec format: "<target>:<id>" —
-//   telegram:<chatId>   (HARA_TELEGRAM_TOKEN)
-//   feishu:<chatId>     (HARA_FEISHU_APP_ID + HARA_FEISHU_APP_SECRET)
-//   webhook:<url>       (plain POST {name,status,text} JSON — for anything else)
-// WeChat is intentionally absent: its transport needs the long-lived gateway session, so a one-shot
-// cron process can't speak it — use feishu/telegram/webhook for cron delivery.
-// Adapters are imported LAZILY so the (heavy) SDKs never load unless a job actually delivers.
 /** Parse a `--deliver` spec; error string on anything unsupported (listing what IS supported). */
 export function parseDeliver(spec) {
     const i = spec.indexOf(":");

package/dist/gateway/flows.js

@@ -0,0 +1,89 @@
+// hara gateway flows — user-configured rules that intercept inbound gateway messages and route matching
+// ones to an agent task + a delivery target, instead of the gateway's default DM-driver reply. This turns
+// any chat gateway (Telegram / WeChat / Feishu / Slack / …) into an automation trigger: "when a message
+// matching <trigger> arrives, run <agent task> and deliver the result to <target>".
+//
+// Opt-in: config lives in the user's ~/.hara/flows.json — no file, no flows (zero behaviour change).
+// Platform-agnostic: matching only reads the generic InboundMsg fields each adapter populates (chatType,
+// mentions), so a flow works on whatever platform surfaces the data it asks for.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { deliverResult } from "../cron/deliver.js";
+const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+/** Load ~/.hara/flows.json — accepts a bare array or `{ "flows": [...] }`. Missing/malformed → [] (never throws). */
+export function loadFlows() {
+    try {
+        const parsed = JSON.parse(readFileSync(join(homedir(), ".hara", "flows.json"), "utf8"));
+        const flows = Array.isArray(parsed) ? parsed : parsed?.flows;
+        return Array.isArray(flows) ? flows.filter((f) => f && f.enabled !== false && f.name && f.do) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Pure predicate: does message `m` on `platform` satisfy rule `r`'s trigger? */
+export function matchFlow(r, m, platform) {
+    const on = r.on ?? {};
+    if (on.platform && on.platform.toLowerCase() !== platform.toLowerCase())
+        return false;
+    const chats = asArray(on.chat);
+    if (chats.length && !chats.includes(String(m.chatId)))
+        return false;
+    if (on.chatType && on.chatType !== "any") {
+        if (!m.chatType || m.chatType !== on.chatType)
+            return false; // rule wants a specific kind the adapter didn't confirm
+    }
+    if (on.mention && on.mention !== "any") {
+        const ms = m.mentions ?? [];
+        if (on.mention === "self") {
+            if (!ms.some((x) => x.isSelf))
+                return false;
+        }
+        else {
+            const want = asArray(on.mention);
+            if (!ms.some((x) => x.id && want.includes(x.id)))
+                return false;
+        }
+    }
+    const kws = asArray(on.keyword);
+    if (kws.length && !kws.some((k) => (m.text ?? "").includes(k)))
+        return false;
+    return true;
+}
+/** Compose the agent prompt for a matched flow (English scaffolding; the user's do/guard carry the intent). */
+export function buildFlowPrompt(r, m) {
+    return (r.do +
+        (r.guard ? `\n\nConstraint: ${r.guard}` : "") +
+        `\n\n--- Triggering message ---\nchat ${m.chatId}${m.chatType ? ` (${m.chatType})` : ""} · from ${m.userName || m.userId}\n${m.text}`);
+}
+/** Try to handle `m` via configured flows. Returns true if ≥1 rule matched (caller should STOP default routing).
+ *  The agent run + delivery are fire-and-forget so a slow LLM call never blocks the gateway's event loop.
+ *  `runAgent` runs the prompt (injected by the gateway so we reuse its session/env plumbing); `reply` (optional)
+ *  sends text back to the originating chat. */
+export async function dispatchFlows(m, platform, runAgent, reply) {
+    const matched = loadFlows().filter((r) => matchFlow(r, m, platform));
+    if (!matched.length)
+        return false;
+    for (const r of matched) {
+        console.error(`hara flow: "${r.name}" matched · ${platform} ${m.chatType ?? "?"} ${m.chatId}`);
+        void (async () => {
+            try {
+                const output = (await runAgent(buildFlowPrompt(r, m))).trim();
+                if (!output)
+                    return;
+                if (r.deliver) {
+                    const err = await deliverResult(r.deliver, output);
+                    if (err)
+                        console.error(`hara flow "${r.name}": deliver failed — ${err}`);
+                }
+                if (r.reply && reply)
+                    await reply(output).catch(() => { });
+            }
+            catch (e) {
+                console.error(`hara flow "${r.name}": ${e instanceof Error ? e.message : String(e)}`);
+            }
+        })();
+    }
+    return true;
+}

package/dist/index.js

@@ -40,6 +40,7 @@ import { runTick, runJobOnce, selfArgv } from "./cron/runner.js";
 import { installScheduler, uninstallScheduler, isInstalled } from "./cron/install.js";
 import { getTools } from "./tools/registry.js";
 import { resetReachability } from "./tools/net-reachability.js";
+import { resetRepeatGuard } from "./agent/repeat-guard.js";
 import { EXPLORE_SYSTEM } from "./tools/agent.js";
 import { createAnthropicProvider } from "./providers/anthropic.js";
 import { createOpenAIProvider } from "./providers/openai.js";
@@ -1553,6 +1554,44 @@ program
     const cwd = opts.cwd ? (await import("node:path")).resolve(opts.cwd) : undefined; // undefined → ~/.hara/workspace
     await mod.runGateway({ cwd, platform: opts.platform });
 });
+program
+    .command("serve")
+    .description("run the local hara server (WebSocket JSON-RPC) that desktop shells / IDE clients drive — persistent sessions, streaming events, approval round-trips")
+    .option("--host <host>", "bind address — keep it loopback unless you know what you're doing", "127.0.0.1")
+    .option("--port <n>", "port to listen on", "8790")
+    .option("--token <token>", "auth token (default: generated; written to ~/.hara/serve.json for clients to discover)")
+    .option("--cwd <dir>", "default working directory for new sessions (default: current directory)")
+    .option("--approval <mode>", "default approval mode for sessions: suggest | auto-edit | full-auto", "auto-edit")
+    .action(async (o) => {
+    const cfg = loadConfig();
+    const provider0 = await withRouting(await buildProvider(cfg), cfg);
+    if (!provider0) {
+        out(c.red(`Not authenticated for '${cfg.provider}' — run \`hara setup\` first.\n`));
+        process.exit(1);
+    }
+    const guardianOpt = await buildGuardian(cfg, provider0);
+    const cwd = o.cwd ? (await import("node:path")).resolve(o.cwd) : process.cwd();
+    const sandbox = (process.env.HARA_SANDBOX ?? cfg.sandbox ?? "off");
+    const approval = APPROVAL_MODES.includes(o.approval) ? o.approval : "auto-edit";
+    const { startServe } = await import("./serve/server.js");
+    const handle = await startServe({ host: o.host, port: Number(o.port) || 8790, token: o.token, cwd }, {
+        version: pkg.version,
+        providerId: cfg.provider,
+        model: cfg.model,
+        buildSessionProvider: async () => withRouting(await buildProvider(cfg), cfg),
+        spawnSubagent: (provider, scwd, projectContext, stats, task, role) => runSubagent(cfg, provider, scwd, sandbox, projectContext, stats, task, role),
+        guardian: guardianOpt,
+        sandbox,
+        approval,
+    });
+    out(c.bold("hara serve") + c.dim(`  ·  ws://${o.host}:${handle.port}  ·  ${cfg.provider}:${cfg.model}  ·  approval ${approval}  ·  token → ~/.hara/serve.json\n`));
+    const bye = async () => {
+        await handle.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", bye);
+    process.on("SIGTERM", bye);
+});
 program
     .command("remote [action] [text]")
     .description("drive THIS tmux session from chat: register the pane so WeChat replies inject back into it. actions: ask \"<q>\" | bind | back | status")
@@ -2928,6 +2967,7 @@ program.action(async (opts) => {
                         history.length = 0;
                         recalledContext = "";
                         resetReachability(); // fresh start — drop any "host unreachable" marks (network may be fixed)
+                        resetRepeatGuard(); // …and the repeated-failure streaks (the user may have fixed the cause)
                         return void h.sink.notice("(context cleared)");
                     }
                     if (nm === "undo") {

package/dist/serve/protocol.js

@@ -0,0 +1,61 @@
+// hara serve protocol v1 — JSON-RPC 2.0 over WebSocket text frames. This is the contract the desktop
+// shell (and any ACP/IDE client) speaks; the transport lives in server.ts, sessions in sessions.ts.
+// Everything here is PURE (parse + frame builders + error codes) and unit-tested.
+//
+// Client → server requests:
+//   initialize        {token}                    → {name,version,protocol,cwd,provider,model}
+//   session.list      {cwd?}                     → {sessions:[{id,title,cwd,model,updatedAt}]}
+//   session.create    {cwd?,approval?}           → {sessionId,model}
+//   session.resume    {sessionId}                → {sessionId,model,history:[{role,text}]}
+//   session.send      {sessionId,text}           → (streams events, then) {reply,usage}
+//   session.interrupt {sessionId}                → {}
+//   approval.reply    {approvalId,allow,always?}  → {}
+//   plugins.list      {}                          → {plugins:[{name,version,description,enabled,skills,agents,mcpServers}]}
+//   plugins.set       {name,enabled}              → {name,enabled}   (applies to future sessions/turns)
+//   skills.list       {cwd?}                      → {skills:[{id,description,source}]}
+// 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}
+export const PROTOCOL_VERSION = 1;
+/** JSON-RPC error codes: standard ones plus hara-specific (-320xx). */
+export const ERR = {
+    PARSE: -32700,
+    INVALID: -32600,
+    METHOD: -32601,
+    PARAMS: -32602,
+    INTERNAL: -32603,
+    UNAUTHORIZED: -32001, // initialize first (or bad token)
+    BUSY: -32002, // session already has a turn in flight
+    NO_SESSION: -32003, // unknown/expired sessionId
+    LOCKED: -32004, // session held by another live hara process (single-writer lock)
+};
+/** Parse one inbound text frame into a request. Returns {error} (never throws) on malformed input —
+ *  the transport turns that into a PARSE/INVALID error response. */
+export function parseFrame(raw) {
+    let v;
+    try {
+        v = JSON.parse(raw);
+    }
+    catch {
+        return { error: "not JSON" };
+    }
+    const o = v;
+    if (!o || typeof o !== "object" || o.jsonrpc !== "2.0" || typeof o.method !== "string" || !o.method) {
+        return { error: "not a JSON-RPC 2.0 request" };
+    }
+    if (o.id !== undefined && typeof o.id !== "number" && typeof o.id !== "string")
+        return { error: "bad id" };
+    if (o.params !== undefined && (typeof o.params !== "object" || o.params === null || Array.isArray(o.params))) {
+        return { error: "params must be an object" };
+    }
+    return { req: o };
+}
+export function rpcResult(id, result) {
+    return JSON.stringify({ jsonrpc: "2.0", id, result });
+}
+export function rpcError(id, code, message) {
+    return JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
+}
+export function rpcNotify(method, params) {
+    return JSON.stringify({ jsonrpc: "2.0", method, params });
+}

package/dist/serve/server.js

@@ -0,0 +1,246 @@
+// hara serve — the persistent local server (WebSocket JSON-RPC, protocol.ts) that desktop shells, ACP
+// clients, and IDE plugins drive. codex's app-server layering in TypeScript: shell ↔ protocol ↔ agent
+// core, with the agent core (runAgent + plugins + skills + memory) running IN-PROCESS — plugins need no
+// bridging. Provider building / subagent spawn / guardian stay in index.ts and are injected as ServeDeps
+// (no import cycle back into the CLI entry).
+import { WebSocketServer } from "ws";
+import { randomBytes, randomUUID, timingSafeEqual, createHash } from "node:crypto";
+import { writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import "../tools/all.js"; // register the full built-in toolset — serve must work as a standalone entry
+import { runAgent } from "../agent/loop.js";
+import { loadAgentsMd } from "../context/agents-md.js";
+import { memoryDigest } from "../memory/store.js";
+import { listInstalled, enabledPlugins, setPluginEnabled } from "../plugins/plugins.js";
+import { loadSkillIndex } from "../skills/skills.js";
+import { SessionHub, realStore } from "./sessions.js";
+import { parseFrame, rpcResult, rpcError, rpcNotify, ERR, PROTOCOL_VERSION } from "./protocol.js";
+const APPROVAL_TIMEOUT_MS = 300_000; // an unanswered approval denies after 5 min (never hangs a turn)
+const sameToken = (a, b) => {
+    // constant-time compare over digests (inputs differ in length)
+    const ha = createHash("sha256").update(a).digest();
+    const hb = createHash("sha256").update(b).digest();
+    return timingSafeEqual(ha, hb);
+};
+/** Last assistant text in a history — the turn's "reply" for request/response clients. */
+export function lastAssistantText(history) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        const m = history[i];
+        if (m.role === "assistant")
+            return m.text ?? "";
+    }
+    return "";
+}
+/** Compact history for session.resume — enough for a client to render the transcript. */
+export function historyForClient(history) {
+    const out = [];
+    for (const m of history) {
+        if (m.role === "user")
+            out.push({ role: "user", text: 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
+    }
+    return out;
+}
+export async function startServe(opts, deps) {
+    const token = opts.token ?? randomBytes(16).toString("hex");
+    const hub = new SessionHub(deps.store ?? realStore);
+    const wss = new WebSocketServer({ host: opts.host, port: opts.port, maxPayload: 10 * 1024 * 1024 });
+    await new Promise((res, rej) => {
+        wss.once("listening", res);
+        wss.once("error", rej);
+    });
+    const port = wss.address().port;
+    const authed = new Set();
+    const pendingApprovals = new Map();
+    const broadcast = (method, params) => {
+        const frame = rpcNotify(method, params);
+        for (const ws of authed)
+            if (ws.readyState === ws.OPEN)
+                ws.send(frame);
+    };
+    // Discovery file — the desktop shell reads this to find the running server (like a pid/port file).
+    const discoveryPath = join(homedir(), ".hara", "serve.json");
+    if (!deps.quietDiscovery) {
+        mkdirSync(join(homedir(), ".hara"), { recursive: true });
+        writeFileSync(discoveryPath, JSON.stringify({ host: opts.host, port, token, pid: process.pid, version: deps.version }, null, 2), { mode: 0o600 });
+    }
+    /** Run one turn on a session, streaming events to all authed clients. */
+    const runTurn = async (s, text) => {
+        const sessionId = s.meta.id;
+        s.busy = true;
+        s.abort = new AbortController();
+        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 }),
+            diff: (t) => broadcast("event.diff", { sessionId, text: t }),
+            notice: (t) => broadcast("event.notice", { sessionId, text: t }),
+        };
+        const confirm = (q) => new Promise((resolve) => {
+            const approvalId = randomUUID();
+            const timer = setTimeout(() => {
+                if (pendingApprovals.delete(approvalId))
+                    resolve(false); // unanswered → deny, turn continues
+            }, APPROVAL_TIMEOUT_MS);
+            pendingApprovals.set(approvalId, (v) => {
+                clearTimeout(timer);
+                pendingApprovals.delete(approvalId);
+                resolve(v);
+            });
+            broadcast("approval.request", { sessionId, approvalId, question: q });
+        });
+        try {
+            s.history.push({ role: "user", content: text });
+            await runAgent(s.history, {
+                provider: s.provider,
+                ctx: {
+                    cwd: s.meta.cwd,
+                    sandbox: deps.sandbox,
+                    spawn: (t, role) => deps.spawnSubagent(s.provider, s.meta.cwd, s.projectContext, s.stats, t, role),
+                    ui: sink,
+                },
+                approval: s.approval,
+                confirm,
+                autoApprove: s.autoApprove,
+                projectContext: s.projectContext,
+                memory: memoryDigest(s.meta.cwd),
+                stats: s.stats,
+                signal: s.abort.signal,
+                guardian: deps.guardian,
+            });
+            hub.save(s);
+            const usage = { input: s.stats.input - before.input, output: s.stats.output - before.output };
+            const reply = lastAssistantText(s.history);
+            broadcast("event.turn_end", { sessionId, reply, usage });
+            return { reply, usage };
+        }
+        finally {
+            s.busy = false;
+            s.abort = null;
+        }
+    };
+    wss.on("connection", (ws) => {
+        ws.on("message", async (raw) => {
+            const parsed = parseFrame(String(raw));
+            if ("error" in parsed)
+                return void ws.send(rpcError(null, ERR.PARSE, parsed.error));
+            const { req } = parsed;
+            const id = req.id ?? null;
+            const reply = (frame) => void (id !== null && ws.send(frame));
+            const p = (req.params ?? {});
+            try {
+                if (req.method === "initialize") {
+                    if (typeof p.token !== "string" || !sameToken(p.token, token))
+                        return reply(rpcError(id, ERR.UNAUTHORIZED, "bad token"));
+                    authed.add(ws);
+                    return reply(rpcResult(id, { name: "hara", version: deps.version, protocol: PROTOCOL_VERSION, cwd: opts.cwd, provider: deps.providerId, model: deps.model }));
+                }
+                if (!authed.has(ws))
+                    return reply(rpcError(id, ERR.UNAUTHORIZED, "initialize first"));
+                switch (req.method) {
+                    case "session.list":
+                        return reply(rpcResult(id, { sessions: hub.list(typeof p.cwd === "string" ? p.cwd : undefined).map((m) => ({ id: m.id, title: m.title, cwd: m.cwd, model: m.model, updatedAt: m.updatedAt })) }));
+                    case "session.create": {
+                        const provider = await deps.buildSessionProvider();
+                        if (!provider)
+                            return reply(rpcError(id, ERR.INTERNAL, "provider not authenticated — run `hara setup`"));
+                        const cwd = typeof p.cwd === "string" && p.cwd ? p.cwd : opts.cwd;
+                        const approval = ["suggest", "auto-edit", "full-auto"].includes(p.approval) ? p.approval : deps.approval;
+                        const s = hub.create({ cwd, provider, providerId: deps.providerId, model: deps.model, approval, projectContext: loadAgentsMd(cwd) || undefined });
+                        return reply(rpcResult(id, { sessionId: s.meta.id, model: s.meta.model }));
+                    }
+                    case "session.resume": {
+                        if (typeof p.sessionId !== "string")
+                            return reply(rpcError(id, ERR.PARAMS, "sessionId required"));
+                        const provider = await deps.buildSessionProvider();
+                        if (!provider)
+                            return reply(rpcError(id, ERR.INTERNAL, "provider not authenticated — run `hara setup`"));
+                        const r = hub.resume(p.sessionId, { provider, approval: deps.approval, projectContext: undefined });
+                        if ("missing" in r)
+                            return reply(rpcError(id, ERR.NO_SESSION, `no session ${p.sessionId}`));
+                        if ("lockedBy" in r)
+                            return reply(rpcError(id, ERR.LOCKED, `session held by live pid ${r.lockedBy}`));
+                        r.session.projectContext = loadAgentsMd(r.session.meta.cwd) || undefined;
+                        return reply(rpcResult(id, { sessionId: r.session.meta.id, model: r.session.meta.model, history: historyForClient(r.session.history) }));
+                    }
+                    case "session.send": {
+                        if (typeof p.sessionId !== "string" || typeof p.text !== "string" || !p.text)
+                            return reply(rpcError(id, ERR.PARAMS, "sessionId + text required"));
+                        const s = hub.get(p.sessionId);
+                        if (!s)
+                            return reply(rpcError(id, ERR.NO_SESSION, `no live session ${p.sessionId} — session.create/resume first`));
+                        if (s.busy)
+                            return reply(rpcError(id, ERR.BUSY, "a turn is already running on this session"));
+                        const r = await runTurn(s, p.text);
+                        return reply(rpcResult(id, r));
+                    }
+                    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"));
+                        s.abort?.abort();
+                        return reply(rpcResult(id, {}));
+                    }
+                    case "approval.reply": {
+                        if (typeof p.approvalId !== "string")
+                            return reply(rpcError(id, ERR.PARAMS, "approvalId required"));
+                        const resolve = pendingApprovals.get(p.approvalId);
+                        if (resolve)
+                            resolve(p.always === true ? "always" : p.allow === true);
+                        return reply(rpcResult(id, {})); // idempotent — a late/duplicate reply is a no-op
+                    }
+                    case "plugins.list": {
+                        const on = new Set(enabledPlugins().map((pl) => pl.name));
+                        return reply(rpcResult(id, { plugins: listInstalled().map((pl) => ({ name: pl.name, version: pl.version, description: pl.manifest.description ?? "", enabled: on.has(pl.name), skills: (pl.manifest.skills ?? []).length, agents: (pl.manifest.agents ?? []).length, mcpServers: Object.keys(pl.manifest.mcpServers ?? {}).length })) }));
+                    }
+                    case "plugins.set": {
+                        if (typeof p.name !== "string" || typeof p.enabled !== "boolean")
+                            return reply(rpcError(id, ERR.PARAMS, "name + enabled required"));
+                        if (!listInstalled().some((pl) => pl.name === p.name))
+                            return reply(rpcError(id, ERR.PARAMS, `no installed plugin "${p.name}"`));
+                        setPluginEnabled(p.name, p.enabled);
+                        return reply(rpcResult(id, { name: p.name, enabled: p.enabled })); // takes effect on the next session/turn (loaders re-read)
+                    }
+                    case "skills.list": {
+                        const cwd = typeof p.cwd === "string" && p.cwd ? p.cwd : opts.cwd;
+                        return reply(rpcResult(id, { skills: loadSkillIndex(cwd).map((s) => ({ id: s.id, description: s.description, source: s.source })) }));
+                    }
+                    default:
+                        return reply(rpcError(id, ERR.METHOD, `unknown method ${req.method}`));
+                }
+            }
+            catch (e) {
+                return reply(rpcError(id, ERR.INTERNAL, String(e?.message ?? e)));
+            }
+        });
+        ws.on("close", () => {
+            authed.delete(ws);
+            if (authed.size === 0) {
+                // nobody left to answer — deny pending approvals now instead of stalling turns for the timeout
+                for (const resolve of pendingApprovals.values())
+                    resolve(false);
+                pendingApprovals.clear();
+            }
+        });
+    });
+    const close = async () => {
+        for (const resolve of pendingApprovals.values())
+            resolve(false);
+        pendingApprovals.clear();
+        hub.releaseAll();
+        if (!deps.quietDiscovery) {
+            try {
+                unlinkSync(discoveryPath);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        await new Promise((res) => wss.close(() => res()));
+    };
+    return { port, token, close };
+}

package/dist/serve/sessions.js

@@ -0,0 +1,67 @@
+import { newSessionId, saveSession, loadSession, listSessions, acquireSessionLock, releaseSessionLock, deriveTitle, } from "../session/store.js";
+/** The real ~/.hara/sessions store (default). */
+export const realStore = {
+    load: loadSession,
+    save: saveSession,
+    list: listSessions,
+    acquire: acquireSessionLock,
+    release: releaseSessionLock,
+};
+export class SessionHub {
+    store;
+    sessions = new Map();
+    constructor(store = realStore) {
+        this.store = store;
+    }
+    create(o) {
+        const meta = {
+            id: newSessionId(),
+            cwd: o.cwd,
+            provider: o.providerId,
+            model: o.model,
+            title: "",
+            createdAt: new Date().toISOString(),
+            updatedAt: "",
+        };
+        this.store.acquire(meta.id); // fresh id — always ours; registers the single-writer claim
+        const s = { meta, history: [], provider: o.provider, approval: o.approval, autoApprove: new Set(), stats: { input: 0, output: 0 }, projectContext: o.projectContext, busy: false, abort: null };
+        this.sessions.set(meta.id, s);
+        return s;
+    }
+    /** Resume a persisted session. Returns the live session, or a lock/missing failure. */
+    resume(id, o) {
+        const live = this.sessions.get(id);
+        if (live)
+            return { session: live }; // already attached to this server
+        const prior = this.store.load(id);
+        if (!prior)
+            return { missing: true };
+        const lock = this.store.acquire(id);
+        if (!lock.ok)
+            return { lockedBy: lock.pid ?? 0 };
+        const s = { meta: prior.meta, history: [...prior.history], provider: o.provider, approval: o.approval, autoApprove: new Set(), stats: { input: 0, output: 0 }, projectContext: o.projectContext, busy: false, abort: null };
+        this.sessions.set(id, s);
+        return { session: s };
+    }
+    get(id) {
+        return this.sessions.get(id);
+    }
+    list(cwd) {
+        return this.store.list(cwd);
+    }
+    /** Persist a session after a turn (sets a title from the first user message once). */
+    save(s) {
+        if (!s.meta.title) {
+            const first = s.history.find((m) => m.role === "user");
+            if (first && "content" in first && typeof first.content === "string")
+                s.meta.title = deriveTitle(first.content);
+        }
+        this.store.save(s.meta, s.history);
+    }
+    /** Release all locks (server shutdown). In-flight turns are aborted by the caller first. */
+    releaseAll() {
+        for (const id of this.sessions.keys())
+            this.store.release(id);
+        this.sessions.clear();
+    }
+}

package/dist/tools/all.js

@@ -0,0 +1,19 @@
+// Side-effect aggregate: register EVERY built-in tool. The CLI entry (index.ts) has always done these
+// imports itself; library entries (serve/server.ts, future embedders) import THIS so the registry is
+// never empty when runAgent plans a turn — an unregistered tool is silently unplannable, which shows up
+// as "the model called write_file and nothing happened".
+import "./builtin.js"; // read_file / write_file / bash / job
+import "./edit.js"; // edit_file
+import "./search.js"; // grep / glob / ls
+import "./patch.js"; // apply_patch
+import "./web.js"; // web_search / web_fetch
+import "./agent.js"; // agent (subagent spawn)
+import "./memory.js"; // memory_search/get/write/forget + skill_create
+import "./skill.js"; // skill loader
+import "./codebase.js"; // codebase_search
+import "./todo.js"; // todo_write
+import "./send.js"; // send_file (self-gates on HARA_GATEWAY)
+import "./external_agent.js"; // external_agent (claude-code / codex delegation)
+import "./ask_user.js"; // ask_user
+import "./cron.js"; // cronjob
+import "./computer.js"; // computer (desktop control; self-gates on config)

package/dist/tools/builtin.js

@@ -43,20 +43,48 @@ export function capHeadTail(s, max = MAX) {
     const head = Math.floor(max * 0.6);
     return s.slice(0, head) + `\n…[${s.length - max} chars truncated]…\n` + s.slice(s.length - (max - head));
 }
+const READ_LINES = 2000; // default lines per read_file call (a long file is read in slices, not dumped whole)
+const LINE_CAP = 2000; // chars per line before truncation (minified bundles / data lines)
+/** Render a line slice of a file, cat -n style. The old read_file dumped the WHOLE file (100K-char cap,
+ *  tail simply lost) — on long files that both flooded the context (~25k tokens per read, again on every
+ *  re-read) and made everything past the cap unreachable. Now: line numbers (anchor for edits and for
+ *  "read around line N"), a default window of READ_LINES, and a header that says how to continue. Pure —
+ *  exported for tests. */
+export function renderFileSlice(text, offset, limit) {
+    const lines = text.split("\n");
+    // A trailing newline yields one phantom "" line at the end — don't count or show it.
+    if (lines.length > 1 && lines[lines.length - 1] === "")
+        lines.pop();
+    const total = lines.length;
+    const start = Math.max(1, Math.floor(offset ?? 1));
+    const want = Math.max(1, Math.floor(limit ?? READ_LINES));
+    if (start > total)
+        return `(file has ${total} lines — offset ${start} is past the end)`;
+    const end = Math.min(total, start + want - 1);
+    const body = lines
+        .slice(start - 1, end)
+        .map((l, i) => `${String(start + i).padStart(6)}\t${l.length > LINE_CAP ? l.slice(0, LINE_CAP) + `…[+${l.length - LINE_CAP} chars]` : l}`)
+        .join("\n");
+    const sliced = start > 1 || end < total;
+    const head = sliced ? `(lines ${start}–${end} of ${total}${end < total ? ` — continue with offset:${end + 1}` : ""})\n` : "";
+    return head + body;
+}
 registerTool({
     name: "read_file",
-    description: "Read a UTF-8 text file and return its contents.",
+    description: "Read a UTF-8 text file; returns cat -n style numbered lines. Reads up to 2000 lines by default — for a longer file pass offset/limit to read the next slice (the output header tells you the total and where to continue). Prefer grep to locate, then read just that region.",
     input_schema: {
         type: "object",
         properties: {
             path: { type: "string", description: "File path, relative to cwd or absolute" },
+            offset: { type: "number", description: "1-based line number to start from (for long files)" },
+            limit: { type: "number", description: "max lines to return (default 2000)" },
         },
         required: ["path"],
     },
     kind: "read",
     async run(input, ctx) {
         try {
-            return cap(await readFile(abs(input.path, ctx.cwd), "utf8"));
+            return cap(renderFileSlice(await readFile(abs(input.path, ctx.cwd), "utf8"), input.offset, input.limit));
         }
         catch (e) {
             const near = nearestPaths(ctx.cwd, input.path);

package/dist/tools/edit.js

@@ -10,8 +10,9 @@ registerTool({
     description: "Edit an existing file by replacing exact strings. Provide a single `old_string`/`new_string`, " +
         "or `edits` (an array of {old_string,new_string,replace_all?}) applied in order. Each `old_string` " +
         "must match exactly and appear once (include surrounding context) unless `replace_all` is true. " +
-        "Quote variants (straight/curly) are matched leniently. Use write_file to create a new file, or " +
-        "apply_patch to change several files at once.",
+        "`old_string` is matched against the RAW file text — strip read_file's line-number prefix " +
+        "(the leading `   123\\t`) before matching. Quote variants (straight/curly) are matched leniently. " +
+        "Use write_file to create a new file, or apply_patch to change several files at once.",
     input_schema: {
         type: "object",
         properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.113.0",
+  "version": "0.115.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"
@@ -56,11 +56,13 @@
     "commander": "^15.0.0",
     "ink": "^6.8.0",
     "openai": "^6.44.0",
-    "react": "^19.2.7"
+    "react": "^19.2.7",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",
     "@types/react": "^19.2.17",
+    "@types/ws": "^8.18.1",
     "ink-testing-library": "^4.0.0",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3"