@nanhara/hara 0.0.2 → 0.48.0

package/dist/tools/builtin.js

@@ -0,0 +1,106 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, resolve, isAbsolute } from "node:path";
+import { stdout as procOut } from "node:process";
+import { registerTool } from "./registry.js";
+import { runShell } from "../sandbox.js";
+import { nearestPaths } from "../fs-walk.js";
+import { emitDiff } from "../diff.js";
+import { recordEdit } from "../undo.js";
+const MAX = 100_000;
+function abs(p, cwd) {
+    return isAbsolute(p) ? p : resolve(cwd, p);
+}
+function cap(s) {
+    return s.length > MAX ? s.slice(0, MAX) + `\n…[truncated ${s.length - MAX} chars]` : s;
+}
+registerTool({
+    name: "read_file",
+    description: "Read a UTF-8 text file and return its contents.",
+    input_schema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path, relative to cwd or absolute" },
+        },
+        required: ["path"],
+    },
+    kind: "read",
+    async run(input, ctx) {
+        try {
+            return cap(await readFile(abs(input.path, ctx.cwd), "utf8"));
+        }
+        catch (e) {
+            const near = nearestPaths(ctx.cwd, input.path);
+            return `Error: cannot read ${input.path}: ${e.code ?? e.message}.` + (near.length ? ` Did you mean: ${near.join(", ")}?` : "");
+        }
+    },
+});
+registerTool({
+    name: "write_file",
+    description: "Create or overwrite a UTF-8 text file (creates parent directories).",
+    input_schema: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+            content: { type: "string" },
+        },
+        required: ["path", "content"],
+    },
+    kind: "edit",
+    async run(input, ctx) {
+        const p = abs(input.path, ctx.cwd);
+        let prev = null;
+        try {
+            prev = await readFile(p, "utf8");
+        }
+        catch {
+            /* new file */
+        }
+        await mkdir(dirname(p), { recursive: true });
+        await writeFile(p, input.content, "utf8");
+        emitDiff(input.path, prev ?? "", input.content, ctx.ui);
+        recordEdit([{ path: input.path, absPath: p, before: prev }]);
+        return `Wrote ${String(input.content).length} chars to ${p}`;
+    },
+});
+registerTool({
+    name: "bash",
+    description: "Run a shell command in the working directory; returns combined stdout/stderr.",
+    input_schema: {
+        type: "object",
+        properties: {
+            command: { type: "string" },
+            timeout_ms: { type: "number", description: "default 120000" },
+        },
+        required: ["command"],
+    },
+    kind: "exec",
+    async run(input, ctx) {
+        let buf = ""; // TUI: line-buffer live output into the sink (one notice per line)
+        const live = ctx.ui
+            ? (s) => {
+                buf += s;
+                let i;
+                while ((i = buf.indexOf("\n")) >= 0) {
+                    ctx.ui.notice(buf.slice(0, i));
+                    buf = buf.slice(i + 1);
+                }
+            }
+            : procOut.isTTY
+                ? (s) => procOut.write(s) // stream output in a plain terminal
+                : undefined;
+        try {
+            const { stdout, stderr } = await runShell(input.command, ctx.cwd, ctx.sandbox ?? "off", {
+                timeout: input.timeout_ms ?? 120_000,
+                maxBuffer: 10 * 1024 * 1024,
+                onData: live,
+            });
+            if (ctx.ui && buf)
+                ctx.ui.notice(buf); // flush trailing partial line
+            const combined = (stdout || "") + (stderr ? `\n[stderr]\n${stderr}` : "");
+            return cap(combined.trim() || "(no output)");
+        }
+        catch (e) {
+            return cap(`Command failed: ${e.message}\n${e.stdout || ""}${e.stderr || ""}`);
+        }
+    },
+});

package/dist/tools/codebase.js

@@ -0,0 +1,102 @@
+// codebase_search — treat the current project as a knowledge base. Lexical relevance search over the
+// repo's code/text (respects .gitignore via listProjectFiles), ranked by how many distinct query words a
+// file contains, returning the densest snippet. Distinct from grep (exact pattern): this finds *related*
+// code from a natural-language query. The interface a semantic (zvec) index slots into later.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { registerTool } from "./registry.js";
+import { listProjectFiles, isProbablyBinary, fileSize } from "../fs-walk.js";
+import { findProjectRoot } from "../context/agents-md.js";
+import { loadConfig } from "../config.js";
+import { getEmbedder } from "../search/embed.js";
+import { queryIndex, indexExists } from "../search/semindex.js";
+const MAX_FILE = 200_000; // skip very large files
+const CODE_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cc|cpp|hpp|cs|swift|scala|sh|bash|sql|md|mdx|json|ya?ml|toml|html|css|scss|less|vue|svelte|astro|tf|proto|graphql|gql|gradle|txt)$/i;
+registerTool({
+    name: "codebase_search",
+    description: "Find code in THIS project relevant to a natural-language query — ranked by relevance (not exact match). " +
+        "Use it to locate similar/related code while working ('where is auth handled?', 'retry logic'); use grep " +
+        "for exact strings/regex. Returns the top files with their most relevant snippet (file:line).",
+    input_schema: {
+        type: "object",
+        properties: { query: { type: "string" }, limit: { type: "number", description: "default 6 (max 20)" } },
+        required: ["query"],
+    },
+    kind: "read",
+    async run(input, ctx) {
+        const words = [...new Set(String(input.query ?? "").toLowerCase().split(/\s+/).filter((w) => w.length > 1))];
+        if (!words.length)
+            return "(empty query)";
+        const need = Math.min(2, words.length); // require most of the query to actually appear (conceptual overlap)
+        const limit = Math.min(Number(input.limit) || 6, 20);
+        const root = findProjectRoot(ctx.cwd);
+        const hits = [];
+        for (const rel of listProjectFiles(root)) {
+            if (!CODE_RE.test(rel))
+                continue;
+            const abs = join(root, rel);
+            if (fileSize(abs) > MAX_FILE)
+                continue;
+            let buf;
+            try {
+                buf = readFileSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (isProbablyBinary(buf))
+                continue;
+            const text = buf.toString("utf8");
+            const lower = text.toLowerCase();
+            const present = words.filter((w) => lower.includes(w));
+            if (present.length < need)
+                continue;
+            // densest line = the one matching the most distinct query words; show it with a little context
+            const lines = text.split("\n");
+            let bestLine = 0;
+            let bestHits = 0;
+            for (let i = 0; i < lines.length; i++) {
+                const ll = lines[i].toLowerCase();
+                const h = present.reduce((n, w) => (ll.includes(w) ? n + 1 : n), 0);
+                if (h > bestHits) {
+                    bestHits = h;
+                    bestLine = i;
+                }
+            }
+            const snippet = lines.slice(Math.max(0, bestLine - 2), bestLine + 4).join("\n");
+            hits.push({ file: rel, score: present.length * 100 + bestHits, line: bestLine + 1, snippet });
+        }
+        hits.sort((a, b) => b.score - a.score || a.file.length - b.file.length);
+        // Semantic layer (opt-in): if a repo index + embedder are configured, prepend the most relevant
+        // chunks (more precise than word overlap), then fill remaining slots with lexical hits. Falls back
+        // to pure lexical when no index/embedder — zero behaviour change for the default install.
+        const out = [];
+        const seen = new Set();
+        const cfg = loadConfig();
+        const embed = getEmbedder(cfg);
+        if (embed && indexExists("repo", ctx.cwd)) {
+            try {
+                for (const s of await queryIndex("repo", String(input.query), embed, ctx.cwd, limit)) {
+                    if (s.score < 0.2 || seen.has(s.file))
+                        continue;
+                    seen.add(s.file);
+                    out.push(`${s.file} (semantic ${s.score.toFixed(2)})\n${s.text.split("\n").slice(0, 6).join("\n")}`);
+                }
+            }
+            catch {
+                /* embedding endpoint down → degrade to lexical */
+            }
+        }
+        for (const h of hits) {
+            if (out.length >= limit)
+                break;
+            if (seen.has(h.file))
+                continue;
+            seen.add(h.file);
+            out.push(`${h.file}:${h.line}\n${h.snippet}`);
+        }
+        if (!out.length)
+            return "(no relevant code found)";
+        return out.join("\n\n---\n\n");
+    },
+});

package/dist/tools/computer.js

@@ -0,0 +1,376 @@
+// computer — native screen control (operate desktop software, not just the browser). Shell-out per OS, no
+// heavy deps: mac = screencapture + cliclick · windows = PowerShell + .NET/user32 · linux = scrot + xdotool.
+// Safety: opt-in tier (config computerUse off|read|click|full) + per-app allowlist (config computerApps:
+// frontmost-window check before any pointer/keyboard action) + dangerous-key blocklist + a once-per-session
+// grant (tool kind "computer" always confirms once, even in full-auto). Screenshots are read via the vision
+// sidecar (ctx.describeImage) so a text main model can still "see" them.
+import { spawnSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+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", 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. */
+export function actionAllowed(tier, action) {
+    return RANK[tier] >= RANK[ACTION_MIN[action] ?? "full"];
+}
+/** Whether a key combo is on the dangerous blocklist. Exported for tests. */
+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 });
+        return { ok: r.status === 0, out: ((r.stdout || "") + (r.stderr || "")).trim() };
+    }
+    catch (e) {
+        return { ok: false, out: e?.message || "spawn failed" };
+    }
+}
+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;
+    return join(tmpdir(), `hara-screen-${process.pid}-${Date.now()}-${seq}.png`);
+}
+function screenshot() {
+    const out = tmpShot();
+    if (process.platform === "darwin") {
+        if (!run("screencapture", ["-x", out]).ok)
+            return { error: "screencapture failed (grant Screen Recording permission)" };
+    }
+    else if (process.platform === "linux") {
+        if (has("scrot"))
+            run("scrot", ["-o", out]);
+        else if (has("import"))
+            run("import", ["-window", "root", out]);
+        else if (has("grim"))
+            run("grim", [out]);
+        else
+            return { error: "no screenshot tool — install scrot / imagemagick / grim" };
+    }
+    else if (process.platform === "win32") {
+        const script = `Add-Type -AssemblyName System.Windows.Forms,System.Drawing; $b=[System.Windows.Forms.Screen]::PrimaryScreen.Bounds; $bmp=New-Object System.Drawing.Bitmap($b.Width,$b.Height); $g=[System.Drawing.Graphics]::FromImage($bmp); $g.CopyFromScreen($b.Location,[System.Drawing.Point]::Empty,$b.Size); $bmp.Save(${JSON.stringify(out)})`;
+        if (!ps(script).ok)
+            return { error: "PowerShell screenshot failed" };
+    }
+    else {
+        return { error: `unsupported platform ${process.platform}` };
+    }
+    try {
+        if (!existsSync(out) || statSync(out).size === 0)
+            return { error: "screenshot produced no file" };
+    }
+    catch {
+        return { error: "screenshot produced no file" };
+    }
+    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") {
+        const r = run("osascript", ["-e", 'tell application "System Events" to get name of first application process whose frontmost is true']);
+        return r.ok ? r.out : "";
+    }
+    if (process.platform === "linux") {
+        const r = run("xdotool", ["getactivewindow", "getwindowclassname"]);
+        return r.ok ? r.out : "";
+    }
+    if (process.platform === "win32") {
+        const script = `Add-Type @"
+using System;using System.Runtime.InteropServices;public class Hw{[DllImport("user32.dll")]public static extern IntPtr GetForegroundWindow();[DllImport("user32.dll")]public static extern int GetWindowThreadProcessId(IntPtr h,out int p);}
+"@; $p=0;[void][Hw]::GetWindowThreadProcessId([Hw]::GetForegroundWindow(),[ref]$p);(Get-Process -Id $p).ProcessName`;
+        const r = ps(script);
+        return r.ok ? r.out : "";
+    }
+    return "";
+}
+function pointerOrKeyboard(action, input) {
+    const x = Math.round(Number(input.x));
+    const y = Math.round(Number(input.y));
+    const mac = process.platform === "darwin";
+    const lin = process.platform === "linux";
+    const win = process.platform === "win32";
+    if (action === "click" || action === "move") {
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            return { ok: false, msg: `${action} needs x,y` };
+        if (mac) {
+            if (!has("cliclick"))
+                return { ok: false, msg: "cliclick not found — install with `brew install cliclick`" };
+            const r = run("cliclick", [`${action === "click" ? "c" : "m"}:${x},${y}`]);
+            return { ok: r.ok, msg: r.ok ? `${action} at ${x},${y}` : r.out };
+        }
+        if (lin) {
+            if (!has("xdotool"))
+                return { ok: false, msg: "xdotool not found" };
+            const r = run("xdotool", action === "click" ? ["mousemove", `${x}`, `${y}`, "click", "1"] : ["mousemove", `${x}`, `${y}`]);
+            return { ok: r.ok, msg: r.ok ? `${action} at ${x},${y}` : r.out };
+        }
+        if (win) {
+            const move = `Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.Cursor]::Position=New-Object System.Drawing.Point(${x},${y})`;
+            const m1 = ps(`Add-Type -AssemblyName System.Drawing;${move}`);
+            if (action === "click" && m1.ok) {
+                ps(`Add-Type @"
+using System;using System.Runtime.InteropServices;public class Ms{[DllImport("user32.dll")]public static extern void mouse_event(int f,int x,int y,int d,int e);}
+"@; [Ms]::mouse_event(0x2,0,0,0,0);[Ms]::mouse_event(0x4,0,0,0,0)`);
+            }
+            return { ok: m1.ok, msg: m1.ok ? `${action} at ${x},${y}` : m1.out };
+        }
+    }
+    if (action === "type") {
+        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 (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 (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 (keystroke)` : r.out };
+        }
+    }
+    if (action === "key") {
+        const keys = String(input.keys ?? "");
+        if (!keys)
+            return { ok: false, msg: "key needs a key/combo" };
+        if (keyIsBlocked(keys))
+            return { ok: false, msg: `refused dangerous key combo: ${keys}` };
+        if (mac) {
+            if (!has("cliclick"))
+                return { ok: false, msg: "cliclick not found — install with `brew install cliclick`" };
+            const r = run("cliclick", [`kp:${keys}`]);
+            return { ok: r.ok, msg: r.ok ? `pressed ${keys}` : r.out };
+        }
+        if (lin) {
+            if (!has("xdotool"))
+                return { ok: false, msg: "xdotool not found" };
+            const r = run("xdotool", ["key", keys]);
+            return { ok: r.ok, msg: r.ok ? `pressed ${keys}` : r.out };
+        }
+        if (win) {
+            const r = ps(`Add-Type -AssemblyName System.Windows.Forms;[System.Windows.Forms.SendKeys]::SendWait(${JSON.stringify(keys)})`);
+            return { ok: r.ok, msg: r.ok ? `pressed ${keys}` : r.out };
+        }
+    }
+    return { ok: false, msg: `unknown or unsupported action '${action}' on ${process.platform}` };
+}
+/** Per-OS backend availability — for `hara doctor`. */
+export function computerBackends() {
+    if (process.platform === "darwin")
+        return `screencapture ✓ · cliclick ${has("cliclick") ? "✓" : "✗ (brew install cliclick)"}`;
+    if (process.platform === "linux")
+        return `scrot ${has("scrot") ? "✓" : "✗"} · xdotool ${has("xdotool") ? "✓" : "✗"}`;
+    if (process.platform === "win32")
+        return "PowerShell (built-in)";
+    return `unsupported (${process.platform})`;
+}
+registerTool({
+    name: "computer",
+    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", "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"],
+    },
+    kind: "computer",
+    async run(input, ctx) {
+        const cfg = loadConfig();
+        const tier = cfg.computerUse;
+        if (tier === "off")
+            return "Screen control is off. Enable it: `hara config set computerUse read|click|full` (and `hara config set computerApps \"App Name, …\"` for the click/type allowlist).";
+        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 …\`.`;
+        // 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.";
+            const app = frontmostApp();
+            const allowed = cfg.computerApps.some((a) => app.toLowerCase().includes(a.toLowerCase()) || a.toLowerCase().includes(app.toLowerCase()));
+            if (!allowed)
+                return `Refused: frontmost app "${app || "unknown"}" isn't in your allowlist (${cfg.computerApps.join(", ")}). Switch to an allowed app or update computerApps.`;
+        }
+        if (action === "screenshot") {
+            const s = screenshot();
+            if (s.error)
+                return fail(`screenshot — ${s.error}`);
+            if (ctx.describeImage) {
+                try {
+                    const desc = await ctx.describeImage(s.path, input.focus ? String(input.focus) : undefined);
+                    if (desc)
+                        return ok(`Screenshot (read via vision):\n${desc}`);
+                }
+                catch {
+                    /* fall through to path */
+                }
+            }
+            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 ? ok(`✓ ${r.msg}${needsLocate ? ` (located "${input.target}")` : ""}`) : fail(r.msg);
+    },
+});

package/dist/tools/edit.js

@@ -0,0 +1,62 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { registerTool } from "./registry.js";
+import { nearestPaths } from "../fs-walk.js";
+import { emitDiff } from "../diff.js";
+import { applyEdits } from "./apply-core.js";
+import { recordEdit } from "../undo.js";
+registerTool({
+    name: "edit_file",
+    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.",
+    input_schema: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+            old_string: { type: "string", description: "exact text to replace (verbatim, incl. whitespace)" },
+            new_string: { type: "string", description: "replacement text" },
+            replace_all: { type: "boolean", description: "replace every occurrence (default false)" },
+            edits: {
+                type: "array",
+                description: "multiple edits applied in sequence (alternative to a single old/new)",
+                items: {
+                    type: "object",
+                    properties: {
+                        old_string: { type: "string" },
+                        new_string: { type: "string" },
+                        replace_all: { type: "boolean" },
+                    },
+                    required: ["old_string", "new_string"],
+                },
+            },
+        },
+        required: ["path"],
+    },
+    kind: "edit",
+    async run(input, ctx) {
+        const p = isAbsolute(input.path) ? input.path : resolve(ctx.cwd, input.path);
+        const edits = Array.isArray(input.edits) && input.edits.length
+            ? input.edits
+            : [{ old_string: input.old_string, new_string: input.new_string, replace_all: input.replace_all }];
+        let text;
+        try {
+            text = await readFile(p, "utf8");
+        }
+        catch {
+            const near = nearestPaths(ctx.cwd, input.path);
+            return `Error: cannot read ${input.path} (use write_file to create a new file).` + (near.length ? ` Did you mean: ${near.join(", ")}?` : "");
+        }
+        const res = applyEdits(text, edits);
+        if ("error" in res)
+            return `Error: ${res.error} in ${input.path}. No changes written.`;
+        await writeFile(p, res.text, "utf8");
+        emitDiff(input.path, text, res.text, ctx.ui);
+        recordEdit([{ path: input.path, absPath: p, before: text }]);
+        const note = res.fuzzy ? " (quote-normalized)" : "";
+        const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+        return `Edited ${input.path}: ${plural(edits.length, "edit")}, ${plural(res.total, "replacement")}${note}.`;
+    },
+});