@nanhara/hara 0.33.0 → 0.53.0

package/dist/org/planner.js

@@ -91,6 +91,25 @@ export function topoOrder(atoms) {
         return { error: "plan has a dependency cycle — cannot sequence" };
     return { ok: order };
 }
+/** Group atoms into dependency "waves": every atom in a wave depends only on atoms in EARLIER waves, so a
+ *  wave's atoms are mutually independent and may run concurrently. Preserves atom order; errors on a cycle. */
+export function topoWaves(atoms) {
+    const byId = new Map(atoms.map((a) => [a.id, a]));
+    const remaining = new Map(atoms.map((a) => [a.id, a]));
+    const done = new Set();
+    const waves = [];
+    while (remaining.size) {
+        const wave = [...remaining.values()].filter((a) => a.deps.every((d) => !byId.has(d) || done.has(d)));
+        if (!wave.length)
+            return { error: "plan has a dependency cycle — cannot sequence" };
+        for (const a of wave)
+            remaining.delete(a.id);
+        for (const a of wave)
+            done.add(a.id);
+        waves.push(wave);
+    }
+    return { ok: waves };
+}
 /** Prompt to execute a single atom in the context of the overall plan. */
 export function atomPrompt(atom, plan, done) {
     const priors = done.length ? `Already completed: ${done.map((a) => a.title).join("; ")}.\n` : "";

package/dist/plugins/plugins.js

@@ -66,6 +66,20 @@ export function pluginMcpServers() {
         Object.assign(out, p.manifest.mcpServers ?? {});
     return out;
 }
+/** Lifecycle hooks contributed by enabled plugins (appended after user-config hooks). */
+export function pluginHooks() {
+    const out = { PreToolUse: [], PostToolUse: [] };
+    for (const p of enabledPlugins()) {
+        const h = p.manifest.hooks;
+        if (!h || typeof h !== "object")
+            continue;
+        if (Array.isArray(h.PreToolUse))
+            out.PreToolUse.push(...h.PreToolUse);
+        if (Array.isArray(h.PostToolUse))
+            out.PostToolUse.push(...h.PostToolUse);
+    }
+    return out;
+}
 /** Install a plugin from `file:<path>`, `github:<owner/repo>`, or `git:<url>` into ~/.hara/plugins/<name>. */
 export function installPlugin(source) {
     mkdirSync(pluginsDir(), { recursive: true });

package/dist/providers/anthropic.js

@@ -2,6 +2,19 @@ import Anthropic from "@anthropic-ai/sdk";
 import { imageToBase64 } from "../images.js";
 export function toAnthropic(history) {
     const msgs = [];
+    // Append a user message, merging into the previous one if it's also `user` — Anthropic requires
+    // alternating roles, and tool-results map to a user message, so a mid-turn-injected user message
+    // (type-ahead steering) lands right after one. Merging keeps the request valid; dormant otherwise.
+    const pushUser = (content) => {
+        const last = msgs[msgs.length - 1];
+        if (last && last.role === "user") {
+            const toBlocks = (c) => typeof c === "string" ? [{ type: "text", text: c }] : c;
+            last.content = [...toBlocks(last.content), ...toBlocks(content)];
+        }
+        else {
+            msgs.push({ role: "user", content });
+        }
+    };
     for (const m of history) {
         if (m.role === "user") {
             if (m.images?.length) {
@@ -13,10 +26,10 @@ export function toAnthropic(history) {
                     if (data)
                         blocks.push({ type: "image", source: { type: "base64", media_type: img.mediaType, data } });
                 }
-                msgs.push({ role: "user", content: blocks.length ? blocks : m.content });
+                pushUser(blocks.length ? blocks : m.content);
             }
             else {
-                msgs.push({ role: "user", content: m.content });
+                pushUser(m.content);
             }
         }
         else if (m.role === "assistant") {
@@ -28,15 +41,12 @@ export function toAnthropic(history) {
             msgs.push({ role: "assistant", content: content.length ? content : [{ type: "text", text: "(no output)" }] });
         }
         else {
-            msgs.push({
-                role: "user",
-                content: m.results.map((r) => ({
-                    type: "tool_result",
-                    tool_use_id: r.id,
-                    content: r.content,
-                    is_error: r.isError,
-                })),
-            });
+            pushUser(m.results.map((r) => ({
+                type: "tool_result",
+                tool_use_id: r.id,
+                content: r.content,
+                is_error: r.isError,
+            })));
         }
     }
     return msgs;

package/dist/search/semindex.js

@@ -2,7 +2,7 @@
 // code-asset / repo / knowledge-base scale (hundreds–low-thousands of chunks); the optional zvec adapter is
 // the scale-up path later. Markdown/code stays the SSOT; this index is a derived, rebuildable, gitignored
 // artifact. The embedder is injected (see embed.ts) so the store + chunking are testable without a model.
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { findProjectRoot } from "../context/agents-md.js";
@@ -15,14 +15,22 @@ export function indexPath(name, cwd) {
         return join(findProjectRoot(cwd), ".hara", "index", "repo.json");
     return join(homedir(), ".hara", "index", `${name}.json`);
 }
+function statMtime(p) {
+    try {
+        return statSync(p).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
 /** Split a file into chunks: Markdown by `#` headings, code by ~40-line windows. Heuristic, zero-dep —
- *  also the substrate embeddings reuse. */
-export function chunkText(text, file, source) {
+ *  also the substrate embeddings reuse. `mtime` (when given) is stamped on every chunk for incremental reuse. */
+export function chunkText(text, file, source, mtime) {
     const out = [];
     const push = (body, n) => {
         const t = body.trim();
         if (t.length >= 12)
-            out.push({ id: `${file}#${n}`, text: t.slice(0, 2000), file, source });
+            out.push({ id: `${file}#${n}`, text: t.slice(0, 2000), file, source, mtime });
     };
     if (/\.(md|mdx)$/i.test(file)) {
         const parts = text.split(/^(?=#{1,6}\s)/m);
@@ -49,23 +57,66 @@ function cosine(a, b) {
     }
     return na && nb ? dot / (Math.sqrt(na) * Math.sqrt(nb)) : 0;
 }
-/** Embed all chunks and write the index file. Returns the count written. */
+/** Build/refresh the index. **Incremental**: files whose mtime is unchanged since the last build keep their
+ *  existing vectors (no re-embed); only new/changed files are embedded, and deleted files drop out. A changed
+ *  embedding model forces a full rebuild (old vectors aren't comparable). Returns counts. */
 export async function buildIndex(name, chunks, embed, cwd, model = "embed") {
+    const p = indexPath(name, cwd);
+    // Load the previous index → reuse vectors for unchanged files.
+    const prevByFile = new Map();
+    let prevModel = "";
+    if (existsSync(p)) {
+        try {
+            const old = JSON.parse(readFileSync(p, "utf8"));
+            prevModel = old.model;
+            for (const it of old.items ?? []) {
+                const arr = prevByFile.get(it.file);
+                if (arr)
+                    arr.push(it);
+                else
+                    prevByFile.set(it.file, [it]);
+            }
+        }
+        catch {
+            /* corrupt index → full rebuild */
+        }
+    }
+    const sameModel = prevModel === model;
+    const byFile = new Map();
+    for (const c of chunks) {
+        const arr = byFile.get(c.file);
+        if (arr)
+            arr.push(c);
+        else
+            byFile.set(c.file, [c]);
+    }
     const items = [];
+    const toEmbed = [];
+    let reused = 0;
+    for (const [file, fchunks] of byFile) {
+        const mtime = fchunks[0].mtime ?? 0;
+        const prev = prevByFile.get(file);
+        if (sameModel && prev?.length && mtime > 0 && prev.every((it) => it.mtime === mtime)) {
+            items.push(...prev); // file unchanged → keep its vectors
+            reused += prev.length;
+        }
+        else {
+            toEmbed.push(...fchunks);
+        }
+    }
     const B = 64;
-    for (let i = 0; i < chunks.length; i += B) {
-        const batch = chunks.slice(i, i + B);
+    for (let i = 0; i < toEmbed.length; i += B) {
+        const batch = toEmbed.slice(i, i + B);
         const vecs = await embed(batch.map((c) => c.text));
         batch.forEach((c, j) => vecs[j] && items.push({ ...c, vec: vecs[j] }));
     }
-    const p = indexPath(name, cwd);
     const dir = dirname(p);
     mkdirSync(dir, { recursive: true });
     // The index is derived + rebuildable (and may embed file contents) — never let it be committed.
     if (!existsSync(join(dir, ".gitignore")))
         writeFileSync(join(dir, ".gitignore"), "*\n", "utf8");
     writeFileSync(p, JSON.stringify({ model, items }), "utf8");
-    return items.length;
+    return { total: items.length, embedded: toEmbed.length, reused };
 }
 export function indexExists(name, cwd) {
     return existsSync(indexPath(name, cwd));
@@ -91,7 +142,7 @@ export function collectDirChunks(dir, source) {
         }
         if (isProbablyBinary(buf))
             continue;
-        chunks.push(...chunkText(buf.toString("utf8"), abs, source));
+        chunks.push(...chunkText(buf.toString("utf8"), abs, source, statMtime(abs)));
     }
     return chunks;
 }
@@ -113,7 +164,7 @@ export function collectRepoChunks(root) {
         }
         if (isProbablyBinary(buf))
             continue;
-        chunks.push(...chunkText(buf.toString("utf8"), rel, "repo"));
+        chunks.push(...chunkText(buf.toString("utf8"), rel, "repo", statMtime(abs)));
     }
     return chunks;
 }

package/dist/session/store.js

@@ -56,6 +56,20 @@ export function titleFrom(history) {
     const firstUser = history.find((h) => h.role === "user");
     return deriveTitle(firstUser && firstUser.role === "user" ? firstUser.content : "");
 }
+/** Normalize a phrase to an ASCII kebab-case slug (lowercase, a–z0–9 + single hyphens, capped). Non-ASCII
+ *  is dropped — used to clean a model-generated English session name. Returns "" if nothing ASCII remains. */
+export function slugify(text, max = 40) {
+    return text
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+/, "")
+        .slice(0, max)
+        .replace(/-+$/, "");
+}
 export function saveSession(meta, history) {
     meta.updatedAt = new Date().toISOString();
     const data = { meta, history };

package/dist/tools/computer.js

@@ -11,7 +11,7 @@ import { join } from "node:path";
 import { registerTool } from "./registry.js";
 import { loadConfig } from "../config.js";
 const RANK = { off: 0, read: 1, click: 2, full: 3 };
-const ACTION_MIN = { screenshot: "read", move: "click", click: "click", type: "full", key: "full" };
+const ACTION_MIN = { screenshot: "read", find: "read", activate: "click", move: "click", click: "click", type: "full", key: "full" };
 // dangerous combos refused even at full tier (quit / close / delete / task-switch-kill)
 const KEY_BLOCK = /(?:\b(cmd|command|ctrl|control|alt|option|win|super|meta)\b.*\+.*\b(q|w|delete|del|f4|escape|esc)\b)|ctrl\+alt\+(?:delete|del|backspace)/i;
 /** Whether the configured tier permits the action. Exported for tests. */
@@ -22,6 +22,25 @@ export function actionAllowed(tier, action) {
 export function keyIsBlocked(keys) {
     return KEY_BLOCK.test(keys);
 }
+// Circuit breaker (learned from codex): bound consecutive screen-control failures so the agent can't loop
+// forever on a broken setup. Reset on any success; after FAIL_LIMIT in a row, return a clear stop + how to fix.
+const FAIL_LIMIT = 3;
+let consecFails = 0;
+export function resetComputerFails() {
+    consecFails = 0;
+}
+function ok(msg) {
+    consecFails = 0;
+    return msg;
+}
+function fail(msg) {
+    consecFails += 1;
+    if (consecFails >= FAIL_LIMIT) {
+        consecFails = 0;
+        return `⛔ Stopping screen control — ${FAIL_LIMIT} actions failed in a row (last: ${msg}). Most likely a missing macOS permission (Accessibility for click/type, Screen Recording for screenshots) or the target app isn't reachable. Fix that, then ask me to try again — I won't keep retrying blindly.`;
+    }
+    return `Failed: ${msg}  [${consecFails}/${FAIL_LIMIT} before I stop]`;
+}
 function run(cmd, args) {
     try {
         const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 15000 });
@@ -35,6 +54,23 @@ function has(cmd) {
     return (process.platform === "win32" ? run("where", [cmd]) : run("which", [cmd])).ok;
 }
 const ps = (script) => run("powershell", ["-NoProfile", "-Command", script]);
+/** Put text on the OS clipboard (so `type` can paste it — IME-safe + Unicode-safe, unlike keystroke injection). */
+function setClipboard(text) {
+    try {
+        if (process.platform === "darwin")
+            return spawnSync("pbcopy", [], { input: text, timeout: 5000 }).status === 0;
+        if (process.platform === "win32")
+            return spawnSync("clip", [], { input: text, timeout: 5000 }).status === 0;
+        if (has("wl-copy"))
+            return spawnSync("wl-copy", [], { input: text, timeout: 5000 }).status === 0;
+        if (has("xclip"))
+            return spawnSync("xclip", ["-selection", "clipboard"], { input: text, timeout: 5000 }).status === 0;
+    }
+    catch {
+        /* fall through */
+    }
+    return false;
+}
 let seq = 0;
 function tmpShot() {
     seq += 1;
@@ -73,6 +109,49 @@ function screenshot() {
     }
     return { path: out };
 }
+/** Bring an app to the foreground so screenshots/clicks land on IT, not the terminal hara runs in. */
+function activateApp(app) {
+    if (process.platform === "darwin") {
+        // `open -a` reliably launches+foregrounds; `osascript … activate` often leaves another window on top.
+        const r = run("open", ["-a", app]);
+        return { ok: r.ok, msg: r.ok ? `activated ${app}` : r.out || `couldn't activate ${app}` };
+    }
+    if (process.platform === "win32") {
+        const r = ps(`(New-Object -ComObject WScript.Shell).AppActivate(${JSON.stringify(app)})`);
+        return { ok: r.ok, msg: r.ok ? `activated ${app}` : r.out || `couldn't activate ${app}` };
+    }
+    if (process.platform === "linux") {
+        const r = has("wmctrl") ? run("wmctrl", ["-a", app]) : run("xdotool", ["search", "--name", app, "windowactivate"]);
+        return { ok: r.ok, msg: r.ok ? `activated ${app}` : r.out || `couldn't activate ${app} (need wmctrl/xdotool)` };
+    }
+    return { ok: false, msg: `activate unsupported on ${process.platform}` };
+}
+/** Logical screen size in the coordinate space the click backends use (points on mac, pixels on win/linux).
+ *  Grounding returns 0..1 fractions, so click = fraction × this. null if undetectable. */
+function screenSize() {
+    try {
+        if (process.platform === "darwin") {
+            const r = run("osascript", ["-e", 'tell application "Finder" to get bounds of window of desktop']);
+            const n = r.out.match(/-?\d+/g);
+            if (n && n.length >= 4)
+                return { w: Number(n[2]), h: Number(n[3]) };
+        }
+        else if (process.platform === "linux") {
+            const [w, h] = run("xdotool", ["getdisplaygeometry"]).out.trim().split(/\s+/).map(Number);
+            if (w && h)
+                return { w, h };
+        }
+        else if (process.platform === "win32") {
+            const [w, h] = ps('Add-Type -AssemblyName System.Windows.Forms; $b=[System.Windows.Forms.Screen]::PrimaryScreen.Bounds; "$($b.Width) $($b.Height)"').out.trim().split(/\s+/).map(Number);
+            if (w && h)
+                return { w, h };
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return null;
+}
 /** Name of the frontmost application/window (for the allowlist check). "" if undetectable. */
 function frontmostApp() {
     if (process.platform === "darwin") {
@@ -128,21 +207,41 @@ using System;using System.Runtime.InteropServices;public class Ms{[DllImport("us
         const text = String(input.text ?? "");
         if (!text)
             return { ok: false, msg: "type needs text" };
+        // IME-safe path: set the clipboard and paste. Keystroke injection (below) is intercepted/garbled by a
+        // CJK input method and can't enter Chinese/emoji reliably; pasting is immune and Unicode-safe.
+        if (setClipboard(text)) {
+            if (mac && has("cliclick")) {
+                const r = run("cliclick", ["kd:cmd", "t:v", "ku:cmd"]); // Cmd+V
+                if (r.ok)
+                    return { ok: true, msg: `pasted ${text.length} chars` };
+            }
+            else if (lin && has("xdotool")) {
+                const r = run("xdotool", ["key", "ctrl+v"]);
+                if (r.ok)
+                    return { ok: true, msg: `pasted ${text.length} chars` };
+            }
+            else if (win) {
+                const r = ps("Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.SendKeys]::SendWait('^v')");
+                if (r.ok)
+                    return { ok: true, msg: `pasted ${text.length} chars` };
+            }
+        }
+        // Fallback: keystroke injection (fine for ASCII when no IME is active).
         if (mac) {
             if (!has("cliclick"))
                 return { ok: false, msg: "cliclick not found — install with `brew install cliclick`" };
             const r = run("cliclick", [`t:${text}`]);
-            return { ok: r.ok, msg: r.ok ? `typed ${text.length} chars` : r.out };
+            return { ok: r.ok, msg: r.ok ? `typed ${text.length} chars (keystroke)` : r.out };
         }
         if (lin) {
             if (!has("xdotool"))
                 return { ok: false, msg: "xdotool not found" };
             const r = run("xdotool", ["type", "--clearmodifiers", text]);
-            return { ok: r.ok, msg: r.ok ? `typed ${text.length} chars` : r.out };
+            return { ok: r.ok, msg: r.ok ? `typed ${text.length} chars (keystroke)` : r.out };
         }
         if (win) {
             const r = ps(`Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.SendKeys]::SendWait(${JSON.stringify(text)})`);
-            return { ok: r.ok, msg: r.ok ? `typed ${text.length} chars` : r.out };
+            return { ok: r.ok, msg: r.ok ? `typed ${text.length} chars (keystroke)` : r.out };
         }
     }
     if (action === "key") {
@@ -182,17 +281,23 @@ export function computerBackends() {
 }
 registerTool({
     name: "computer",
-    description: "Control the screen to operate desktop software (not just the browser): take a screenshot, then " +
-        "click/move/type/press keys at coordinates. Workflow: screenshot → read what's on screen → act. " +
-        "Opt-in and permission-gated (tier + per-app allowlist).",
+    description: "Control the screen to operate desktop software (not just the browser). ALWAYS `activate` the target app " +
+        "FIRST (e.g. activate WeChat) — otherwise screenshots/clicks hit the terminal hara runs in, not the app. " +
+        "Then prefer grounding over guessing pixels: pass `target` (e.g. 'the Send button') to click/move and it's " +
+        "located by a vision model; or `find` to just get coordinates. Workflow: activate → screenshot → click a " +
+        "target → re-screenshot to verify. When typing, type the ACTUAL text — never placeholders. Opt-in and " +
+        "permission-gated (tier + per-app allowlist).",
     input_schema: {
         type: "object",
         properties: {
-            action: { type: "string", enum: ["screenshot", "click", "move", "type", "key"] },
-            x: { type: "number", description: "x pixel (click/move)" },
-            y: { type: "number", description: "y pixel (click/move)" },
+            action: { type: "string", enum: ["screenshot", "activate", "find", "click", "move", "type", "key"] },
+            app: { type: "string", description: "app to bring to the foreground (activate) — e.g. 'WeChat'. Do this BEFORE screenshot/click so they hit the app, not the terminal." },
+            target: { type: "string", description: "describe a UI element to locate (find) or click/move to — e.g. 'the Send button'. Preferred over x,y." },
+            x: { type: "number", description: "x pixel (click/move; or use `target`)" },
+            y: { type: "number", description: "y pixel (click/move; or use `target`)" },
             text: { type: "string", description: "text to type (type)" },
             keys: { type: "string", description: "key or combo, e.g. 'return', 'cmd+c' (key)" },
+            focus: { type: "string", description: "screenshot only: what to look for — focuses the read" },
         },
         required: ["action"],
     },
@@ -205,7 +310,17 @@ registerTool({
         const action = String(input.action ?? "");
         if (!actionAllowed(tier, action))
             return `'${action}' needs a higher tier (current computerUse=${tier}). Raise it with \`hara config set computerUse …\`.`;
-        if (action !== "screenshot") {
+        // Bring the target app to the foreground first — without this, clicks land on the terminal hara runs in.
+        if (action === "activate") {
+            const app = String(input.app ?? input.target ?? "");
+            if (!app)
+                return "activate needs an `app` name (e.g. 'WeChat').";
+            if (!cfg.computerApps.some((a) => app.toLowerCase().includes(a.toLowerCase()) || a.toLowerCase().includes(app.toLowerCase())))
+                return `Refused: "${app}" isn't in your allowlist (${cfg.computerApps.join(", ") || "empty"}). Add it: \`hara config set computerApps "${app}"\`.`;
+            const r = activateApp(app);
+            return r.ok ? ok(`✓ ${r.msg} — now screenshot/find/click to act on it`) : fail(r.msg);
+        }
+        if (action !== "screenshot" && action !== "find") {
             // per-app allowlist: only act when an allowlisted app is frontmost (the key guard against wrong-window clicks)
             if (!cfg.computerApps.length)
                 return "No apps allowlisted — set `hara config set computerApps \"App Name, …\"` before clicking/typing.";
@@ -217,20 +332,45 @@ registerTool({
         if (action === "screenshot") {
             const s = screenshot();
             if (s.error)
-                return `Screenshot failed: ${s.error}`;
+                return fail(`screenshot — ${s.error}`);
             if (ctx.describeImage) {
                 try {
-                    const desc = await ctx.describeImage(s.path);
+                    const desc = await ctx.describeImage(s.path, input.focus ? String(input.focus) : undefined);
                     if (desc)
-                        return `Screenshot (read via vision):\n${desc}`;
+                        return ok(`Screenshot (read via vision):\n${desc}`);
                 }
                 catch {
                     /* fall through to path */
                 }
             }
-            return `Screenshot saved to ${s.path}. Configure a vision model so I can read it: \`hara config set visionModel <model>\`.`;
+            return ok(`Screenshot saved to ${s.path}. Configure a vision model so I can read it: \`hara config set visionModel <model>\`.`);
+        }
+        // Grounding: locate a described element and turn it into screen coordinates (more reliable than guessing
+        // pixels from a text description). Used for `find`, and for click/move when given a `target` and no x,y.
+        const needsLocate = action === "find" || ((action === "click" || action === "move") && input.target != null && (input.x == null || input.y == null));
+        if (needsLocate) {
+            const target = String(input.target ?? "");
+            if (!target)
+                return action === "find" ? "find needs a `target` (what to locate)." : "click/move needs `x,y` or a `target`.";
+            if (!ctx.locate)
+                return "Grounding needs a vision model that can see images — set one: `hara config set visionModel <model>`.";
+            const s = screenshot();
+            if (s.error)
+                return fail(`screenshot — ${s.error}`);
+            const loc = await ctx.locate(s.path, target);
+            if (!loc)
+                return fail(`couldn't locate "${target}" on screen — try a screenshot first, or rephrase the target`);
+            const size = screenSize();
+            if (!size)
+                return fail(`located "${target}" but couldn't read the screen size to convert coordinates`);
+            const gx = Math.round(loc.x * size.w);
+            const gy = Math.round(loc.y * size.h);
+            if (action === "find")
+                return ok(`"${target}" is at ~${gx},${gy} (${Math.round(loc.x * 100)}% across, ${Math.round(loc.y * 100)}% down).`);
+            input.x = gx;
+            input.y = gy;
         }
         const r = pointerOrKeyboard(action, input);
-        return r.ok ? `✓ ${r.msg}` : `Failed: ${r.msg}`;
+        return r.ok ? ok(`✓ ${r.msg}${needsLocate ? ` (located "${input.target}")` : ""}`) : fail(r.msg);
     },
 });

package/dist/tools/todo.js

@@ -0,0 +1,51 @@
+// todo_write — an inline task checklist the agent maintains during a turn (like codex's update_plan /
+// Claude Code's TodoWrite). Keeps the model organized on multi-step work and shows the user live progress.
+// In-memory, replace-whole-list semantics; kind:"read" so it never prompts and is safe to call freely.
+import { registerTool } from "./registry.js";
+let todos = [];
+/** The current checklist (latest todo_write wins) — for a TUI/statusline to render. */
+export function currentTodos() {
+    return todos;
+}
+const MARK = { pending: "☐", in_progress: "▶", done: "☑" };
+export function renderTodos(list) {
+    if (!list.length)
+        return "(todo list cleared)";
+    const done = list.filter((t) => t.status === "done").length;
+    return `Todos (${done}/${list.length} done):\n` + list.map((t) => `  ${MARK[t.status]} ${t.text}`).join("\n");
+}
+registerTool({
+    name: "todo_write",
+    description: "Maintain a short task checklist for the CURRENT work. Use it to plan a multi-step task up front, then " +
+        "update it as you go: keep exactly one item 'in_progress', flip items to 'done' as you finish, add items " +
+        "you discover. Pass the FULL list each call (it replaces the previous). Skip it for trivial one-step tasks.",
+    input_schema: {
+        type: "object",
+        properties: {
+            todos: {
+                type: "array",
+                description: "the full checklist, in order",
+                items: {
+                    type: "object",
+                    properties: {
+                        text: { type: "string", description: "the task, a short imperative phrase" },
+                        status: { type: "string", enum: ["pending", "in_progress", "done"] },
+                    },
+                    required: ["text", "status"],
+                },
+            },
+        },
+        required: ["todos"],
+    },
+    kind: "read", // pure state + display: never prompts, parallel-safe
+    async run(input) {
+        const raw = Array.isArray(input.todos) ? input.todos : [];
+        todos = raw
+            .map((t) => ({
+            text: String(t?.text ?? "").trim(),
+            status: (["pending", "in_progress", "done"].includes(t?.status) ? t.status : "pending"),
+        }))
+            .filter((t) => t.text);
+        return renderTodos(todos);
+    },
+});

package/dist/tools/web.js

@@ -24,6 +24,103 @@ export function htmlToText(html) {
         .replace(/\n{3,}/g, "\n\n")
         .trim();
 }
+/** Parse DuckDuckGo HTML results → [{title, url, snippet}]. Best-effort HTML scrape (no key, no dependency). */
+export function parseSearchResults(html, limit) {
+    const strip = (s) => s
+        .replace(/<[^>]+>/g, "")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#x27;|&#39;/g, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+    const snippets = [];
+    const snipRe = /class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g;
+    let m;
+    while ((m = snipRe.exec(html)))
+        snippets.push(strip(m[1]));
+    const out = [];
+    const linkRe = /class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+    let i = 0;
+    while ((m = linkRe.exec(html)) && out.length < limit) {
+        let href = m[1].replace(/&amp;/g, "&");
+        const uddg = /[?&]uddg=([^&]+)/.exec(href); // DuckDuckGo wraps results in a /l/?uddg=<real-url> redirect
+        if (uddg)
+            href = decodeURIComponent(uddg[1]);
+        else if (href.startsWith("//"))
+            href = "https:" + href;
+        out.push({ title: strip(m[2]), url: href, snippet: snippets[i++] ?? "" });
+    }
+    return out;
+}
+registerTool({
+    name: "web_search",
+    description: "Search the web and return the top results (title, URL, snippet). Use it to FIND information or pages you " +
+        "don't already have a URL for, then `web_fetch` a result to read it. Read-only. Reliable with a Tavily key " +
+        "(env HARA_SEARCH_API_KEY); otherwise a best-effort keyless fallback that may be rate-limited.",
+    input_schema: {
+        type: "object",
+        properties: {
+            query: { type: "string" },
+            limit: { type: "number", description: "max results (default 6, max 10)" },
+        },
+        required: ["query"],
+    },
+    kind: "read",
+    async run(input) {
+        const q = String(input.query ?? "").trim();
+        if (!q)
+            return "(empty query)";
+        const limit = Math.min(Math.max(1, Number(input.limit) || 6), 10);
+        const fmt = (rs) => rs.map((r, n) => `${n + 1}. ${r.title}\n   ${r.url}${r.snippet ? `\n   ${r.snippet}` : ""}`).join("\n\n");
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 20_000);
+        try {
+            // Reliable path: Tavily (designed for agents, free tier) when a key is configured.
+            const key = process.env.HARA_SEARCH_API_KEY || process.env.TAVILY_API_KEY;
+            if (key) {
+                const res = await fetch("https://api.tavily.com/search", {
+                    method: "POST",
+                    signal: ctrl.signal,
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ api_key: key, query: q, max_results: limit }),
+                });
+                if (res.ok) {
+                    const j = (await res.json());
+                    const rs = (j.results ?? []).map((x) => ({ title: String(x.title ?? x.url ?? ""), url: String(x.url ?? ""), snippet: String(x.content ?? "").slice(0, 200) }));
+                    if (rs.length)
+                        return fmt(rs);
+                }
+                // Tavily failed → fall through to the keyless best-effort path.
+            }
+            // Keyless fallback: DuckDuckGo HTML (POST — GET returns a 202 challenge). May be rate-limited.
+            const res = await fetch("https://html.duckduckgo.com/html/", {
+                method: "POST",
+                signal: ctrl.signal,
+                redirect: "follow",
+                headers: {
+                    "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36",
+                    "content-type": "application/x-www-form-urlencoded",
+                    accept: "text/html",
+                },
+                body: `q=${encodeURIComponent(q)}`,
+            });
+            if (!res.ok)
+                return `Search failed: HTTP ${res.status}. Keyless search is rate-limited — set HARA_SEARCH_API_KEY (Tavily) for reliable search, or web_fetch a known URL.`;
+            const results = parseSearchResults(await res.text(), limit);
+            if (!results.length)
+                return "(no results — the keyless endpoint is rate-limited or changed. Set HARA_SEARCH_API_KEY (Tavily) for reliable search, or web_fetch a known URL.)";
+            return fmt(results);
+        }
+        catch (e) {
+            return `Search failed: ${e?.name === "AbortError" ? "timed out (20s)" : (e?.message ?? e)}`;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    },
+});
 registerTool({
     name: "web_fetch",
     description: "Fetch an http(s) URL and return its text content (HTML is reduced to readable text). Read-only. " +