@nanhara/hara 0.0.2 → 0.48.0

package/dist/tools/memory.js

@@ -0,0 +1,147 @@
+// Memory tools — the agent's interface to durable memory. memory_search/get are read-only
+// (parallel-safe, never prompt); memory_write/forget are edits (gated by the approval mode).
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { isAbsolute, resolve, join } from "node:path";
+import { registerTool } from "./registry.js";
+import { searchAssets, assetSearchRoots } from "../recall.js";
+import { searchHybrid } from "../search/hybrid.js";
+import { memoryRoots, appendMemory, replaceMemory, forgetMemory } from "../memory/store.js";
+import { scanMemory, redactSecrets, scrubLocal } from "../memory/guard.js";
+import { globalSkillsDir, skillsDir, invalidateSkillsCache } from "../skills/skills.js";
+const asTarget = (v) => (["memory", "user", "log"].includes(v) ? v : "memory");
+const asScope = (v) => (v === "global" ? "global" : "project");
+registerTool({
+    name: "memory_search",
+    description: "Search your durable memory (facts, decisions, user preferences, daily notes) by keywords. " +
+        "Use BEFORE answering about prior work, project conventions, or the user's preferences.",
+    input_schema: {
+        type: "object",
+        properties: { query: { type: "string" }, limit: { type: "number", description: "default 5" } },
+        required: ["query"],
+    },
+    kind: "read",
+    async run(input, ctx) {
+        const hits = await searchHybrid(String(input.query ?? ""), ctx.cwd, { indexName: "memory", roots: memoryRoots(ctx.cwd), limit: Math.min(Number(input.limit) || 5, 10) });
+        if (!hits.length)
+            return "(no memory matches)";
+        return hits.map((h) => `${h.path} — ${h.title}\n${h.snippet}`).join("\n\n");
+    },
+});
+registerTool({
+    name: "memory_get",
+    description: "Read a memory file in full (use after memory_search to pull the exact entry).",
+    input_schema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+    kind: "read",
+    async run(input, ctx) {
+        const p = isAbsolute(String(input.path)) ? String(input.path) : resolve(ctx.cwd, String(input.path));
+        if (!memoryRoots(ctx.cwd).some((r) => p.startsWith(r)))
+            return `Error: ${input.path} is outside the memory store.`;
+        if (!existsSync(p))
+            return `Error: no memory file at ${p}.`;
+        try {
+            return readFileSync(p, "utf8").slice(0, 50_000);
+        }
+        catch (e) {
+            return `Error: ${e.message}`;
+        }
+    },
+});
+registerTool({
+    name: "memory_write",
+    description: "Persist a durable fact/decision/preference to memory so future sessions recall it. Save proactively " +
+        "when you learn something worth keeping: project conventions, the user's preferences, a tricky solution.",
+    input_schema: {
+        type: "object",
+        properties: {
+            content: { type: "string" },
+            target: { type: "string", enum: ["memory", "user", "log"], description: "memory=durable facts, user=user prefs (global), log=today's note. default memory" },
+            scope: { type: "string", enum: ["project", "global"], description: "default project" },
+            mode: { type: "string", enum: ["append", "replace"], description: "default append" },
+        },
+        required: ["content"],
+    },
+    kind: "edit",
+    async run(input, ctx) {
+        const content = String(input.content ?? "").trim();
+        if (!content)
+            return "Error: empty content.";
+        const scan = scanMemory(content);
+        if (!scan.ok)
+            return `Blocked: this looks unsafe to store (${scan.hits.join(", ")}). Rephrase without secrets/injection text.`;
+        const scope = asScope(input.scope);
+        const target = asTarget(input.target);
+        const f = input.mode === "replace" ? replaceMemory(scope, target, content, ctx.cwd) : appendMemory(scope, target, content, ctx.cwd);
+        return `Saved to ${f}`;
+    },
+});
+registerTool({
+    name: "skill_create",
+    description: "Save a reusable skill (a how-to / capability) as a SKILL.md so you and future sessions can load it " +
+        "later via the `skill` tool. Use after solving something worth reusing. The `description` is how you'll " +
+        "recognize when to load it, so make it specific (what it does + when to use it).",
+    input_schema: {
+        type: "object",
+        properties: {
+            name: { type: "string", description: "short kebab-case skill id" },
+            description: { type: "string", description: "one line: what it does + when to use it" },
+            body: { type: "string", description: "the instructions in Markdown (steps, code, gotchas)" },
+            scope: { type: "string", enum: ["project", "personal"], description: "project = this repo's .hara/skills; personal = ~/.hara/skills (default). Sharing to company/public is a separate, human-confirmed step." },
+        },
+        required: ["name", "description", "body"],
+    },
+    kind: "edit",
+    async run(input, ctx) {
+        const slug = String(input.name ?? "")
+            .toLowerCase()
+            .replace(/[^a-z0-9-]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .slice(0, 48);
+        if (!slug)
+            return "Error: invalid name.";
+        let description = String(input.description ?? "").replace(/\s+/g, " ").trim();
+        if (!description)
+            return "Error: a description is required (it's how the skill gets surfaced).";
+        // sanitize on capture: generalize local paths/emails, then redact secrets; block only on residue.
+        description = scrubLocal(description, ctx.cwd);
+        let body = scrubLocal(String(input.body ?? ""), ctx.cwd);
+        const rd = redactSecrets(description);
+        const rb = redactSecrets(body);
+        description = rd.text;
+        body = rb.text;
+        const redactions = [...rd.redactions, ...rb.redactions];
+        const scan = scanMemory(`${description}\n${body}`);
+        if (!scan.ok)
+            return `Blocked: content still looks unsafe (${scan.hits.join(", ")}). Remove injection/exfil text.`;
+        const scope = input.scope === "project" ? "project" : "personal";
+        const dir = join(scope === "project" ? skillsDir(ctx.cwd) : globalSkillsDir(), slug);
+        const f = join(dir, "SKILL.md");
+        // dedup: surface a near-duplicate so the agent updates instead of piling up (lexical signal, not a block)
+        const dups = searchAssets(`${slug} ${description}`, 3, assetSearchRoots(ctx.cwd)).filter((h) => h.path !== f && h.score >= 2);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(f, `---\nname: ${slug}\ndescription: ${description}\n---\n\n${body.trim()}\n`, "utf8");
+        invalidateSkillsCache();
+        const notes = [
+            redactions.length ? `redacted ${redactions.length} secret(s)` : "",
+            dups.length ? `⚠ similar already exists: ${dups.map((d) => d.path).join(", ")} — consider updating instead` : "",
+        ].filter(Boolean);
+        return `Saved ${scope} skill to ${f}${notes.length ? ` (${notes.join("; ")})` : ""}`;
+    },
+});
+registerTool({
+    name: "memory_forget",
+    description: "Remove memory lines matching a substring (prune stale or wrong facts).",
+    input_schema: {
+        type: "object",
+        properties: {
+            match: { type: "string" },
+            target: { type: "string", enum: ["memory", "user", "log"] },
+            scope: { type: "string", enum: ["project", "global"] },
+        },
+        required: ["match"],
+    },
+    kind: "edit",
+    async run(input, ctx) {
+        const n = forgetMemory(asScope(input.scope), asTarget(input.target), String(input.match ?? ""), ctx.cwd);
+        return n ? `Removed ${n} line(s).` : "(no matching lines)";
+    },
+});

package/dist/tools/patch.js

@@ -0,0 +1,123 @@
+// apply_patch — change MULTIPLE files atomically (all-or-nothing). Everything is validated and
+// computed in memory first; nothing is written unless every change applies cleanly.
+import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
+import { isAbsolute, resolve, dirname } from "node:path";
+import { registerTool } from "./registry.js";
+import { applyEdits } from "./apply-core.js";
+import { emitDiff } from "../diff.js";
+import { recordEdit } from "../undo.js";
+registerTool({
+    name: "apply_patch",
+    description: "Change SEVERAL files in one atomic step (all-or-nothing). `changes` is an array of " +
+        "{path, type:'update'|'create'|'delete', edits?:[{old_string,new_string,replace_all?}], content?}. " +
+        "update applies edits (or replaces the whole file with content); create writes a new file; delete removes it. " +
+        "If ANY change fails to apply, nothing is written. Prefer this over multiple edit_file calls for multi-file changes.",
+    input_schema: {
+        type: "object",
+        properties: {
+            changes: {
+                type: "array",
+                description: "the file changes to apply together",
+                items: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string" },
+                        type: { type: "string", enum: ["update", "create", "delete"] },
+                        content: { type: "string", description: "full file content (for create, or whole-file update)" },
+                        edits: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    old_string: { type: "string" },
+                                    new_string: { type: "string" },
+                                    replace_all: { type: "boolean" },
+                                },
+                                required: ["old_string", "new_string"],
+                            },
+                        },
+                    },
+                    required: ["path"],
+                },
+            },
+        },
+        required: ["changes"],
+    },
+    kind: "edit",
+    async run(input, ctx) {
+        const changes = Array.isArray(input.changes) ? input.changes : [];
+        if (!changes.length)
+            return "Error: apply_patch needs a non-empty `changes` array.";
+        const abs = (pth) => (isAbsolute(pth) ? pth : resolve(ctx.cwd, pth));
+        // PHASE 1 — validate + compute every change in memory; bail before writing anything.
+        const plans = [];
+        for (let i = 0; i < changes.length; i++) {
+            const ch = changes[i];
+            const tag = `change ${i + 1}/${changes.length}`;
+            if (typeof ch.path !== "string" || !ch.path)
+                return `Error: ${tag} is missing a path. Nothing written.`;
+            const p = abs(ch.path);
+            const type = ch.type ?? (ch.edits ? "update" : "create");
+            if (type === "delete") {
+                let before;
+                try {
+                    before = await readFile(p, "utf8");
+                }
+                catch {
+                    return `Error: ${tag} delete ${ch.path}: file not found. Nothing written.`;
+                }
+                plans.push({ path: ch.path, abs: p, type, before, after: null, existed: true });
+            }
+            else if (type === "create") {
+                if (typeof ch.content !== "string")
+                    return `Error: ${tag} create ${ch.path} needs \`content\`. Nothing written.`;
+                let before = "";
+                let existed = false;
+                try {
+                    before = await readFile(p, "utf8");
+                    existed = true;
+                }
+                catch {
+                    /* new file */
+                }
+                plans.push({ path: ch.path, abs: p, type, before, after: ch.content, existed });
+            }
+            else {
+                // update
+                let before;
+                try {
+                    before = await readFile(p, "utf8");
+                }
+                catch {
+                    return `Error: ${tag} update ${ch.path}: cannot read (use type:create for a new file). Nothing written.`;
+                }
+                if (typeof ch.content === "string" && !ch.edits) {
+                    plans.push({ path: ch.path, abs: p, type, before, after: ch.content, existed: true });
+                }
+                else {
+                    const res = applyEdits(before, ch.edits ?? []);
+                    if ("error" in res)
+                        return `Error: ${tag} ${ch.path} — ${res.error}. Nothing written.`;
+                    plans.push({ path: ch.path, abs: p, type, before, after: res.text, existed: true });
+                }
+            }
+        }
+        // PHASE 2 — commit all changes + show each diff.
+        const summary = [];
+        for (const pl of plans) {
+            if (pl.type === "delete") {
+                await unlink(pl.abs);
+                emitDiff(pl.path, pl.before, "", ctx.ui);
+                summary.push(`deleted ${pl.path}`);
+            }
+            else {
+                await mkdir(dirname(pl.abs), { recursive: true });
+                await writeFile(pl.abs, pl.after, "utf8");
+                emitDiff(pl.path, pl.before, pl.after, ctx.ui);
+                summary.push(`${pl.type === "create" ? "created" : "updated"} ${pl.path}`);
+            }
+        }
+        recordEdit(plans.map((pl) => ({ path: pl.path, absPath: pl.abs, before: pl.existed ? pl.before : null })));
+        return `apply_patch: ${plans.length} file(s) — ${summary.join("; ")}.`;
+    },
+});

package/dist/tools/registry.js

@@ -0,0 +1,18 @@
+const registry = new Map();
+export function registerTool(t) {
+    registry.set(t.name, t);
+}
+export function getTool(name) {
+    return registry.get(name);
+}
+export function getTools() {
+    return [...registry.values()];
+}
+/** Provider-neutral tool specs derived from the registry. */
+export function toolSpecs() {
+    return getTools().map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.input_schema,
+    }));
+}

package/dist/tools/search.js

@@ -0,0 +1,176 @@
+// Search/listing tools — grep (regex across files), glob (path patterns), ls (one directory).
+// All read-only (kind: "read"), so they never hit the approval gate and run in parallel.
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, resolve, join, relative, sep } from "node:path";
+import { registerTool } from "./registry.js";
+import { walkFiles, isProbablyBinary } from "../fs-walk.js";
+const MAX_OUT = 60_000;
+const MAX_MATCHES = 300;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const toPosix = (p) => (sep === "/" ? p : p.split(sep).join("/"));
+const absOf = (p, cwd) => (p ? (isAbsolute(p) ? p : resolve(cwd, p)) : cwd);
+/** Convert a glob (supports **, *, ?) to an anchored RegExp over POSIX paths. */
+function globToRegExp(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === "*") {
+            if (glob[i + 1] === "*") {
+                // ** matches across path separators (optionally swallow a trailing slash)
+                i++;
+                if (glob[i + 1] === "/")
+                    i++;
+                re += "(?:.*/)?";
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (ch === "?")
+            re += "[^/]";
+        else if (".+^${}()|[]\\".includes(ch))
+            re += "\\" + ch;
+        else
+            re += ch;
+    }
+    return new RegExp("^" + re + "$");
+}
+registerTool({
+    name: "grep",
+    description: "Search file contents by regular expression. Returns matching `path:line: text`. " +
+        "Scopes to `path` (dir or file, default cwd); optional `glob` filters which files; `ignore_case`.",
+    input_schema: {
+        type: "object",
+        properties: {
+            pattern: { type: "string", description: "JavaScript regular expression" },
+            path: { type: "string", description: "directory or file to search (default: cwd)" },
+            glob: { type: "string", description: "only search files whose path matches this glob (e.g. **/*.ts)" },
+            ignore_case: { type: "boolean" },
+        },
+        required: ["pattern"],
+    },
+    kind: "read",
+    async run(input, ctx) {
+        let re;
+        try {
+            re = new RegExp(input.pattern, input.ignore_case ? "i" : "");
+        }
+        catch (e) {
+            return `Error: invalid regex: ${e.message}`;
+        }
+        const root = absOf(input.path, ctx.cwd);
+        let isFile = false;
+        try {
+            isFile = statSync(root).isFile();
+        }
+        catch {
+            return `Error: no such path: ${input.path ?? "."}`;
+        }
+        const rel = (abs) => toPosix(relative(ctx.cwd, abs)) || toPosix(relative(root, abs));
+        const files = isFile ? [root] : walkFiles(root).map((f) => join(root, f));
+        const globRe = input.glob ? globToRegExp(input.glob) : null;
+        const lines = [];
+        let matches = 0;
+        let scanned = 0;
+        for (const abs of files) {
+            if (matches >= MAX_MATCHES)
+                break;
+            const r = toPosix(relative(ctx.cwd, abs));
+            if (globRe && !globRe.test(toPosix(relative(isFile ? ctx.cwd : root, abs))))
+                continue;
+            let buf;
+            try {
+                if (statSync(abs).size > MAX_FILE_BYTES)
+                    continue;
+                buf = readFileSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (isProbablyBinary(buf))
+                continue;
+            scanned++;
+            const text = buf.toString("utf8");
+            const fileLines = text.split("\n");
+            for (let i = 0; i < fileLines.length; i++) {
+                if (re.test(fileLines[i])) {
+                    lines.push(`${r}:${i + 1}: ${fileLines[i].trim().slice(0, 300)}`);
+                    if (++matches >= MAX_MATCHES)
+                        break;
+                }
+            }
+        }
+        if (!lines.length)
+            return `No matches for /${input.pattern}/ (scanned ${scanned} files).`;
+        let body = lines.join("\n");
+        if (body.length > MAX_OUT)
+            body = body.slice(0, MAX_OUT) + "\n…[truncated]";
+        const head = matches >= MAX_MATCHES ? `(showing first ${MAX_MATCHES} matches)\n` : "";
+        return head + body;
+    },
+});
+registerTool({
+    name: "glob",
+    description: "List files whose path matches a glob pattern (supports **, *, ?). Scopes to `path` (default cwd).",
+    input_schema: {
+        type: "object",
+        properties: {
+            pattern: { type: "string", description: "e.g. **/*.ts, src/**/index.*" },
+            path: { type: "string", description: "base directory (default: cwd)" },
+        },
+        required: ["pattern"],
+    },
+    kind: "read",
+    async run(input, ctx) {
+        const root = absOf(input.path, ctx.cwd);
+        const re = globToRegExp(input.pattern);
+        const hits = walkFiles(root).filter((f) => re.test(f));
+        if (!hits.length)
+            return `No files match ${input.pattern}.`;
+        const shown = hits.slice(0, 400);
+        const head = hits.length > shown.length ? `(${hits.length} matches, showing 400)\n` : "";
+        return head + shown.join("\n");
+    },
+});
+registerTool({
+    name: "ls",
+    description: "List the entries of one directory (name, type, size). Non-recursive; use glob/grep to search deeper.",
+    input_schema: {
+        type: "object",
+        properties: { path: { type: "string", description: "directory (default: cwd)" } },
+    },
+    kind: "read",
+    async run(input, ctx) {
+        const dir = absOf(input.path, ctx.cwd);
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch (e) {
+            return `Error: cannot list ${input.path ?? "."}: ${e.message}`;
+        }
+        const rows = entries
+            .filter((e) => !(e.isDirectory() && e.name === ".git"))
+            .sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name))
+            .map((e) => {
+            if (e.isDirectory())
+                return `  ${e.name}/`;
+            let size = 0;
+            try {
+                size = statSync(join(dir, e.name)).size;
+            }
+            catch {
+                /* ignore */
+            }
+            return `  ${e.name}  ${c_size(size)}`;
+        });
+        return rows.length ? rows.join("\n") : "(empty directory)";
+    },
+});
+function c_size(n) {
+    if (n < 1024)
+        return `${n}B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)}K`;
+    return `${(n / 1024 / 1024).toFixed(1)}M`;
+}

package/dist/tools/skill.js

@@ -0,0 +1,30 @@
+// The `skill` tool — load a skill's full instructions on demand. The system prompt lists available
+// skills (id + description); the model calls this to pull the body before doing a task the skill covers.
+// Returning the body as a tool RESULT (not editing the system prompt) keeps the cached prefix stable.
+import { registerTool } from "./registry.js";
+import { loadSkillIndex, loadSkillBody } from "../skills/skills.js";
+import { scanMemory } from "../memory/guard.js";
+registerTool({
+    name: "skill",
+    description: "Load the full instructions for a skill by id. The system prompt's Skills list shows what's available; " +
+        "call this to get a skill's steps before performing a task it covers, then follow them.",
+    input_schema: { type: "object", properties: { id: { type: "string", description: "the skill id from the Skills list" } }, required: ["id"] },
+    kind: "read",
+    async run(input, ctx) {
+        const id = String(input.id ?? "").trim();
+        const sk = loadSkillIndex(ctx.cwd).find((s) => s.id === id);
+        if (!sk)
+            return `No skill '${id}'. See the Skills list in the system prompt for available ids.`;
+        const body = loadSkillBody(sk);
+        if (!body)
+            return `Skill '${id}' has no instructions.`;
+        const scan = scanMemory(body); // skills may come from plugins (untrusted) — guard at load time
+        if (!scan.ok)
+            return `Skill '${id}' blocked: its content looks unsafe (${scan.hits.join(", ")}).`;
+        if (sk.context === "fork" && ctx.spawn) {
+            // fork: run the skill as a delegated sub-agent rather than inlining it into this turn
+            return await ctx.spawn(`Follow this skill to complete the current task:\n\n${body}`);
+        }
+        return body; // inline (default): the body enters the conversation as this tool's result
+    },
+});

package/dist/tools/web.js

@@ -0,0 +1,73 @@
+// web_fetch — fetch an http(s) URL and return readable text (HTML reduced to text). Read-only.
+// Uses Node's global fetch (Node >=20). NOT sandboxed (network egress is in-process, not via bash).
+import { registerTool } from "./registry.js";
+const MAX = 60_000;
+/** Strip HTML to a readable-ish plain-text approximation (no dependency). */
+export function htmlToText(html) {
+    return html
+        .replace(/<head[\s\S]*?<\/head>/gi, " ")
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<!--[\s\S]*?-->/g, " ")
+        .replace(/<li[^>]*>/gi, "\n- ")
+        .replace(/<\/(p|div|h[1-6]|li|tr|section|article|header|footer|ul|ol|blockquote)>/gi, "\n")
+        .replace(/<br\s*\/?>/gi, "\n")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/[ \t]+/g, " ")
+        .replace(/ *\n */g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+registerTool({
+    name: "web_fetch",
+    description: "Fetch an http(s) URL and return its text content (HTML is reduced to readable text). Read-only. " +
+        "Use for docs, references, or pages the user mentions. Not sandboxed.",
+    input_schema: {
+        type: "object",
+        properties: {
+            url: { type: "string", description: "http:// or https:// URL" },
+            max_chars: { type: "number", description: "cap on returned text (default 60000)" },
+        },
+        required: ["url"],
+    },
+    kind: "read",
+    async run(input) {
+        let url;
+        try {
+            url = new URL(input.url);
+        }
+        catch {
+            return `Error: invalid URL: ${input.url}`;
+        }
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return "Error: only http/https URLs are supported.";
+        const cap = Math.min(Math.max(1000, input.max_chars ?? MAX), 200_000);
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 30_000);
+        try {
+            const res = await fetch(url, {
+                signal: ctrl.signal,
+                redirect: "follow",
+                headers: { "user-agent": "hara-cli", accept: "text/html,text/plain,application/json,*/*" },
+            });
+            const ct = res.headers.get("content-type") ?? "";
+            const raw = await res.text();
+            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 `# ${url.href} (HTTP ${res.status})\n\n${text || "(empty body)"}`;
+        }
+        catch (e) {
+            return `Error fetching ${url.href}: ${e?.name === "AbortError" ? "timed out (30s)" : (e?.message ?? e)}`;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    },
+});