@nanhara/hara 0.70.0 → 0.89.0

package/dist/security/permissions.js

@@ -0,0 +1,211 @@
+// Fine-grained, command-level permission policy for the `bash` tool — the layer that turns "confirm every
+// command" / "full-auto, unguarded" into a personal allow/ask/deny policy. Pure-Node, zero-dep. This is
+// governance-as-config (hara's moat): it composes with approval modes rather than replacing them.
+//
+// Rules live in ~/.hara/permissions.json (+ a project .hara/permissions.json, deny-wins on merge):
+//   { "allow": ["npm test", "git commit", "npm run *"], "deny": ["git push", "rm -rf", "sudo"],
+//     "readonlyAutorun": true }
+// A pattern matches a command if the canonical command equals it, starts with "<pattern> ", or glob-matches
+// (with `*`). The decision for a compound command (&&, ||, ;, |) is the STRICTEST of its parts
+// (deny > ask > allow); anything we can't safely parse fails CLOSED to "ask".
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+const PROJECT_ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
+// Programs that are read-only when run as a plain command (no dangerous flags / redirection — see below).
+const READONLY_PROGRAMS = new Set([
+    "ls", "pwd", "cat", "head", "tail", "wc", "echo", "printf", "grep", "rg", "fd", "stat", "file", "which",
+    "type", "whoami", "id", "date", "tree", "du", "df", "ps", "uname", "hostname", "dirname", "basename",
+    "realpath", "sort", "uniq", "cut", "column", "jq", "true", "false", "env",
+]);
+// `git <sub>` is read-only only for these subcommands.
+const GIT_READONLY_SUB = new Set([
+    "status", "log", "diff", "show", "branch", "remote", "tag", "describe", "rev-parse", "ls-files",
+    "ls-remote", "config", "blame", "shortlog", "cat-file", "whatchanged", "grep", "rev-list", "name-rev",
+]);
+// Flags that can turn an otherwise-read-only command destructive → disqualify from autorun.
+const DANGER_FLAG = /(^|\s)(-i\b|-o\b|--output\b|--exec\b|-delete\b|-fprint\b|--write\b|-w\b|--in-place\b)/;
+/** Unwrap shell wrappers and strip leading env/wrappers to get the command's essential form. Lossy on
+ *  purpose — used only for matching/classification, never for execution. */
+export function canonicalize(command) {
+    let cmd = command.trim();
+    // Unwrap `bash -lc "…"` / `sh -c '…'` / `zsh -c …` (one level).
+    const wrap = /^(?:\/usr\/bin\/|\/bin\/)?(?:ba|z)?sh\s+-[a-z]*c\s+(['"])([\s\S]*)\1\s*$/.exec(cmd);
+    if (wrap)
+        cmd = wrap[2].trim();
+    // Strip leading `VAR=val` assignments (NODE_ENV=production foo …).
+    while (/^[A-Za-z_][A-Za-z0-9_]*=[^\s]*\s+/.test(cmd))
+        cmd = cmd.replace(/^[A-Za-z_][A-Za-z0-9_]*=[^\s]*\s+/, "");
+    // Strip benign leading wrappers that don't change what's actually run.
+    for (;;) {
+        const m = /^(timeout\s+\d+[a-z]?\s+|time\s+|nice\s+(-n\s+-?\d+\s+)?|command\s+|\\)/.exec(cmd);
+        if (!m)
+            break;
+        cmd = cmd.slice(m[0].length).trimStart();
+    }
+    return cmd.replace(/\s+/g, " ").trim();
+}
+/** True if the (already-canonical, simple) command is read-only and safe to autorun. */
+export function isReadOnlyCommand(canonical) {
+    if (!canonical)
+        return false;
+    if (/[>]/.test(canonical))
+        return false; // any output redirection → not read-only
+    if (DANGER_FLAG.test(canonical))
+        return false;
+    const parts = canonical.split(" ");
+    const prog = parts[0];
+    if (prog === "git")
+        return GIT_READONLY_SUB.has(parts[1] ?? "");
+    return READONLY_PROGRAMS.has(prog);
+}
+/** Split a command on top-level shell operators (&&, ||, ;, |, newline), quote-aware. Returns null if the
+ *  command uses constructs we don't safely model (command substitution / backticks / unbalanced quotes) —
+ *  the caller then fails closed. */
+export function splitCompound(command) {
+    const parts = [];
+    let buf = "";
+    let sq = false, dq = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        const next = command[i + 1];
+        if (sq) {
+            if (ch === "'")
+                sq = false;
+            buf += ch;
+            continue;
+        }
+        if (dq) {
+            if (ch === '"')
+                dq = false;
+            buf += ch;
+            continue;
+        }
+        if (ch === "'") {
+            sq = true;
+            buf += ch;
+            continue;
+        }
+        if (ch === '"') {
+            dq = true;
+            buf += ch;
+            continue;
+        }
+        if (ch === "`")
+            return null; // backtick command substitution → can't model, fail closed
+        if (ch === "$" && next === "(")
+            return null; // $(…) substitution → fail closed
+        if ((ch === "&" && next === "&") || (ch === "|" && next === "|")) {
+            parts.push(buf);
+            buf = "";
+            i++;
+            continue;
+        }
+        if (ch === ";" || ch === "|" || ch === "\n" || ch === "&") {
+            parts.push(buf);
+            buf = "";
+            continue;
+        }
+        buf += ch;
+    }
+    if (sq || dq)
+        return null; // unbalanced quotes → fail closed
+    parts.push(buf);
+    return parts.map((p) => canonicalize(p)).filter(Boolean);
+}
+/** Match a canonical command against a single rule pattern: exact, prefix (pattern + space), or glob (*). */
+export function matchesPattern(canonical, pattern) {
+    const pat = canonicalize(pattern);
+    if (!pat)
+        return false;
+    if (pat.includes("*")) {
+        const re = new RegExp("^" + pat.split("*").map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$");
+        return re.test(canonical);
+    }
+    return canonical === pat || canonical.startsWith(pat + " ");
+}
+const STRICTNESS = { allow: 0, ask: 1, deny: 2 };
+const strictest = (ds) => ds.reduce((a, b) => (STRICTNESS[b] > STRICTNESS[a] ? b : a), "allow");
+/** Decide a single simple (canonical) command against the rules. deny > allow-rule > read-only > ask. */
+function decideSimple(canonical, rules) {
+    if (rules.deny.some((p) => matchesPattern(canonical, p)))
+        return "deny";
+    if (rules.allow.some((p) => matchesPattern(canonical, p)))
+        return "allow";
+    if (rules.readonlyAutorun && isReadOnlyCommand(canonical))
+        return "allow";
+    return "ask";
+}
+/** Decide a (possibly compound) shell command. Strictest part wins; unparseable → deny if any deny pattern
+ *  hits the whole string, else "ask" (fail closed). */
+export function decideCommand(command, rules) {
+    const canonical = canonicalize(command);
+    const parts = splitCompound(command);
+    if (!parts) {
+        return rules.deny.some((p) => matchesPattern(canonical, p)) ? "deny" : "ask";
+    }
+    if (!parts.length)
+        return "ask";
+    return strictest(parts.map((p) => decideSimple(p, rules)));
+}
+const DEFAULTS = { allow: [], deny: [], readonlyAutorun: true };
+function readRules(p) {
+    if (!existsSync(p))
+        return {};
+    try {
+        const j = JSON.parse(readFileSync(p, "utf8"));
+        return {
+            allow: Array.isArray(j.allow) ? j.allow.filter((x) => typeof x === "string") : undefined,
+            deny: Array.isArray(j.deny) ? j.deny.filter((x) => typeof x === "string") : undefined,
+            readonlyAutorun: typeof j.readonlyAutorun === "boolean" ? j.readonlyAutorun : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+export function globalPermissionsPath() {
+    return join(homedir(), ".hara", "permissions.json");
+}
+/** Nearest project `.hara/permissions.json`, cwd → repo root. */
+export function projectPermissionsPath(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const p = join(dir, ".hara", "permissions.json");
+        if (existsSync(p))
+            return p;
+        if (PROJECT_ROOT_MARKERS.some((m) => existsSync(join(dir, m))))
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Effective rules: project ∪ global, deny-wins (union of denies); project's readonlyAutorun overrides
+ *  global's. Missing/invalid files → safe defaults (read-only autorun on, no allow/deny rules). */
+export function loadPermissionRules(cwd) {
+    const g = readRules(globalPermissionsPath());
+    const projPath = projectPermissionsPath(cwd);
+    const p = projPath ? readRules(projPath) : {};
+    return {
+        allow: [...(g.allow ?? []), ...(p.allow ?? [])],
+        deny: [...(g.deny ?? []), ...(p.deny ?? [])],
+        readonlyAutorun: p.readonlyAutorun ?? g.readonlyAutorun ?? DEFAULTS.readonlyAutorun,
+    };
+}
+const SCAFFOLD = {
+    allow: ["npm test", "npm run lint", "npm run build", "git commit"],
+    deny: ["git push", "rm -rf", "sudo", "git reset --hard"],
+    readonlyAutorun: true,
+};
+/** Write a starter permissions.json (global by default). Returns the path, or null if one already exists. */
+export function scaffoldPermissions(cwd, scope = "global") {
+    const p = scope === "project" ? join(resolve(cwd), ".hara", "permissions.json") : globalPermissionsPath();
+    if (existsSync(p))
+        return null;
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(SCAFFOLD, null, 2) + "\n", "utf8");
+    return p;
+}

package/dist/tools/builtin.js

@@ -6,6 +6,7 @@ import { runShell } from "../sandbox.js";
 import { nearestPaths } from "../fs-walk.js";
 import { emitDiff } from "../diff.js";
 import { recordEdit } from "../undo.js";
+import { startJob, listJobs, tailJob, killJob } from "../exec/jobs.js";
 const MAX = 100_000;
 function abs(p, cwd) {
     return isAbsolute(p) ? p : resolve(cwd, p);
@@ -13,6 +14,14 @@ function abs(p, cwd) {
 function cap(s) {
     return s.length > MAX ? s.slice(0, MAX) + `\n…[truncated ${s.length - MAX} chars]` : s;
 }
+/** Truncate keeping the HEAD and the TAIL — for command output, where the start gives context but the END
+ *  usually holds the error/result, so plain head-truncation would cut exactly the part that matters most. */
+export function capHeadTail(s, max = MAX) {
+    if (s.length <= max)
+        return s;
+    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));
+}
 registerTool({
     name: "read_file",
     description: "Read a UTF-8 text file and return its contents.",
@@ -70,11 +79,16 @@ registerTool({
         properties: {
             command: { type: "string" },
             timeout_ms: { type: "number", description: "default 120000" },
+            background: { type: "boolean", description: "run as a background job (dev server, watcher, long task); returns a job id immediately — tail/kill it with the `job` tool" },
         },
         required: ["command"],
     },
     kind: "exec",
     async run(input, ctx) {
+        if (input.background) {
+            const id = startJob(input.command, ctx.cwd, ctx.sandbox ?? "off");
+            return `Started background job ${id}: \`${input.command}\`. Manage with the \`job\` tool — {action:"tail",id:"${id}"} for output, {action:"kill",id:"${id}"} to stop, {action:"list"} for all.`;
+        }
         let buf = ""; // TUI: line-buffer live output into the sink (one notice per line)
         const live = ctx.ui
             ? (s) => {
@@ -97,10 +111,43 @@ registerTool({
             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)");
+            return capHeadTail(combined.trim() || "(no output)");
         }
         catch (e) {
-            return cap(`Command failed: ${e.message}\n${e.stdout || ""}${e.stderr || ""}`);
+            return capHeadTail(`Command failed: ${e.message}\n${e.stdout || ""}${e.stderr || ""}`);
+        }
+    },
+});
+registerTool({
+    name: "job",
+    description: "Manage background shell jobs (started via bash {background:true}) — dev servers, watchers, long tasks. action: list | tail | kill.",
+    input_schema: {
+        type: "object",
+        properties: {
+            action: { type: "string", enum: ["list", "tail", "kill"] },
+            id: { type: "string", description: "job id (required for tail/kill)" },
+            lines: { type: "number", description: "tail: number of trailing lines to show (default 40)" },
+        },
+        required: ["action"],
+    },
+    kind: "read", // manages only the agent's own background jobs; safe to run unconfirmed
+    async run(input) {
+        const action = String(input.action);
+        if (action === "list") {
+            const js = listJobs();
+            if (!js.length)
+                return "(no background jobs)";
+            return js.map((j) => `${j.id}  [${j.status}${j.code != null ? " " + j.code : ""}]  ${Math.round(j.ageMs / 1000)}s  ${j.command}`).join("\n");
+        }
+        const id = String(input.id ?? "");
+        if (!id)
+            return "Error: `id` is required for tail/kill.";
+        if (action === "tail") {
+            const t = tailJob(id, Number(input.lines) || 40);
+            return t == null ? `No job ${id}.` : t.trim() || "(no output yet)";
         }
+        if (action === "kill")
+            return killJob(id) ? `Killed ${id}.` : `No running job ${id} (already exited/killed or unknown).`;
+        return `Error: unknown action '${action}'.`;
     },
 });

package/dist/tools/send.js

@@ -0,0 +1,35 @@
+import { registerTool } from "./registry.js";
+import { appendFileSync, existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+// `send_file` — the agent's ONLY way to push a file/image to the user when running inside `hara gateway`
+// (Telegram / WeChat). The gateway sets HARA_GATEWAY_OUTBOX to a per-message temp file; this tool appends the
+// path there, and after the headless run ends the daemon delivers each queued file to the chat via the platform
+// adapter (images inline, everything else as an attachment). It does NOT touch the desktop client — driving the
+// WeChat/desktop app with the `computer` tool targets a different surface and never reaches this chat peer.
+//
+// Self-gated on HARA_GATEWAY: registered only in the gateway subprocess, so it never clutters normal CLI/TUI runs.
+if (process.env.HARA_GATEWAY) {
+    registerTool({
+        name: "send_file",
+        description: "Send a local file (image, document, audio, zip, …) to the user in the CURRENT chat. Use this whenever the " +
+            "user asks you to send/share/发 a file or image. Pass an absolute path to a file that already exists (generate " +
+            "it first if needed). Images are delivered inline; other files as attachments. This is the only channel that " +
+            "reaches the user — do NOT use the computer tool or desktop automation to deliver files.",
+        kind: "exec",
+        input_schema: {
+            type: "object",
+            properties: { path: { type: "string", description: "Absolute path to the file to send." } },
+            required: ["path"],
+        },
+        async run(input, ctx) {
+            const outbox = process.env.HARA_GATEWAY_OUTBOX;
+            if (!outbox)
+                return "send_file only works inside `hara gateway` — there is no chat to send to here.";
+            const p = resolve(ctx.cwd, String(input.path ?? ""));
+            if (!existsSync(p) || !statSync(p).isFile())
+                return `No such file: ${p || "(none)"} — create the file first, then call send_file with its absolute path.`;
+            appendFileSync(outbox, p + "\n");
+            return `Queued for delivery to the user in this chat: ${p}`;
+        },
+    });
+}

package/dist/tools/web.js

@@ -5,6 +5,7 @@
 import { registerTool } from "./registry.js";
 import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
+import { wrapUntrusted } from "../security/external-content.js";
 const MAX = 60_000;
 /** True for loopback / private / link-local / ULA / CGNAT addresses we must not let web_fetch reach. */
 export function isPrivateIp(ip) {
@@ -150,7 +151,7 @@ registerTool({
                     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);
+                        return wrapUntrusted(fmt(rs), `web_search: ${q}`);
                 }
                 // Tavily failed → fall through to the keyless best-effort path.
             }
@@ -171,7 +172,7 @@ registerTool({
             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);
+            return wrapUntrusted(fmt(results), `web_search: ${q}`);
         }
         catch (e) {
             return `Search failed: ${e?.name === "AbortError" ? "timed out (20s)" : (e?.message ?? e)}`;
@@ -231,7 +232,7 @@ registerTool({
             let text = /html/i.test(ct) ? htmlToText(raw) : raw;
             if (text.length > cap)
                 text = text.slice(0, cap) + `\n…[truncated ${text.length - cap} chars]`;
-            return `# ${current.href} (HTTP ${res.status})\n\n${text || "(empty body)"}`;
+            return `# ${current.href} (HTTP ${res.status})\n\n${wrapUntrusted(text || "(empty body)", current.href)}`;
         }
         catch (e) {
             return `Error fetching ${url.href}: ${e?.name === "AbortError" ? "timed out (30s)" : (e?.message ?? e)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.70.0",
+  "version": "0.89.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"
@@ -51,6 +51,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.104.2",
+    "@larksuiteoapi/node-sdk": "^1.68.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^15.0.0",
     "ink": "^6.8.0",
@@ -65,6 +66,7 @@
     "typescript": "^6.0.3"
   },
   "optionalDependencies": {
-    "@zvec/zvec": "^0.5.0"
+    "@zvec/zvec": "^0.5.0",
+    "qrcode-terminal": "^0.12.0"
   }
 }