@nanhara/hara 0.0.1 → 0.33.0

package/dist/search/hybrid.js

@@ -0,0 +1,38 @@
+// Hybrid search — lexical (always) blended with semantic (when an index + embedder are configured).
+// One entry point for `recall` and `memory_search`: semantic hits lead (more relevant), lexical fills the
+// rest, deduped by path. With no index/embedder it's exactly the lexical result — zero behaviour change.
+import { searchAssets, titleOf } from "../recall.js";
+import { loadConfig } from "../config.js";
+import { getEmbedder } from "./embed.js";
+import { queryIndex, indexExists } from "./semindex.js";
+export async function searchHybrid(query, cwd, opts) {
+    const limit = opts.limit ?? 5;
+    const lex = searchAssets(query, limit, opts.roots);
+    const embed = getEmbedder(loadConfig());
+    if (!embed || !indexExists(opts.indexName, cwd))
+        return lex;
+    let sem;
+    try {
+        sem = await queryIndex(opts.indexName, query, embed, cwd, limit);
+    }
+    catch {
+        return lex; // embedding endpoint down → degrade to lexical
+    }
+    const out = [];
+    const seen = new Set();
+    for (const s of sem) {
+        if (s.score < 0.2 || seen.has(s.file))
+            continue;
+        seen.add(s.file);
+        out.push({ path: s.file, title: titleOf(s.text, s.file), snippet: s.text.slice(0, 800), score: s.score });
+    }
+    for (const h of lex) {
+        if (out.length >= limit)
+            break;
+        if (seen.has(h.path))
+            continue;
+        seen.add(h.path);
+        out.push(h);
+    }
+    return out;
+}

package/dist/search/semindex.js

@@ -0,0 +1,141 @@
+// Semantic index — a zero-dependency, JSON-backed vector store with brute-force cosine. Fine for the
+// 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 { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { findProjectRoot } from "../context/agents-md.js";
+import { listProjectFiles, walkFiles, isProbablyBinary, fileSize } from "../fs-walk.js";
+// Same code/text extensions codebase_search ranks lexically — keep the two walks in sync.
+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;
+/** Index location — repo index lives in the project (gitignore it); the rest are global. Derived/rebuildable. */
+export function indexPath(name, cwd) {
+    if (name === "repo")
+        return join(findProjectRoot(cwd), ".hara", "index", "repo.json");
+    return join(homedir(), ".hara", "index", `${name}.json`);
+}
+/** 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) {
+    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 });
+    };
+    if (/\.(md|mdx)$/i.test(file)) {
+        const parts = text.split(/^(?=#{1,6}\s)/m);
+        parts.forEach((p, i) => push(p, i));
+    }
+    else {
+        const lines = text.split("\n");
+        const W = 40;
+        const STEP = 30; // overlap so a function spanning a boundary still lands in one chunk
+        for (let i = 0, n = 0; i < lines.length; i += STEP, n++)
+            push(lines.slice(i, i + W).join("\n"), n);
+    }
+    return out;
+}
+function cosine(a, b) {
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    return na && nb ? dot / (Math.sqrt(na) * Math.sqrt(nb)) : 0;
+}
+/** Embed all chunks and write the index file. Returns the count written. */
+export async function buildIndex(name, chunks, embed, cwd, model = "embed") {
+    const items = [];
+    const B = 64;
+    for (let i = 0; i < chunks.length; i += B) {
+        const batch = chunks.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;
+}
+export function indexExists(name, cwd) {
+    return existsSync(indexPath(name, cwd));
+}
+/** Walk one knowledge directory (code-assets / skills / memory) and chunk its files. Files come back as
+ *  absolute paths so recall/memory_search can read or open them directly. */
+export function collectDirChunks(dir, source) {
+    if (!existsSync(dir))
+        return [];
+    const chunks = [];
+    for (const rel of walkFiles(dir)) {
+        if (!CODE_RE.test(rel))
+            continue;
+        const abs = join(dir, rel);
+        if (fileSize(abs) > 200_000)
+            continue;
+        let buf;
+        try {
+            buf = readFileSync(abs);
+        }
+        catch {
+            continue;
+        }
+        if (isProbablyBinary(buf))
+            continue;
+        chunks.push(...chunkText(buf.toString("utf8"), abs, source));
+    }
+    return chunks;
+}
+/** Walk the repo (respecting .gitignore) and chunk every code/text file — the corpus `hara index` embeds. */
+export function collectRepoChunks(root) {
+    const chunks = [];
+    for (const rel of listProjectFiles(root)) {
+        if (!CODE_RE.test(rel))
+            continue;
+        const abs = join(root, rel);
+        if (fileSize(abs) > 200_000)
+            continue;
+        let buf;
+        try {
+            buf = readFileSync(abs);
+        }
+        catch {
+            continue;
+        }
+        if (isProbablyBinary(buf))
+            continue;
+        chunks.push(...chunkText(buf.toString("utf8"), rel, "repo"));
+    }
+    return chunks;
+}
+/** Cosine-rank the index against the query embedding. Returns top-k hits (empty if no index). */
+export async function queryIndex(name, query, embed, cwd, k = 6) {
+    const p = indexPath(name, cwd);
+    if (!existsSync(p))
+        return [];
+    let idx;
+    try {
+        idx = JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (!idx.items?.length)
+        return [];
+    const [qv] = await embed([query]);
+    if (!qv)
+        return [];
+    return idx.items
+        .map((it) => ({ file: it.file, source: it.source, text: it.text, score: cosine(qv, it.vec) }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, k);
+}

package/dist/session/store.js

@@ -0,0 +1,95 @@
+// Session persistence — conversations saved as JSON under ~/.hara/sessions, resumable.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+function sessionsDir() {
+    const d = join(homedir(), ".hara", "sessions");
+    mkdirSync(d, { recursive: true });
+    return d;
+}
+const sessionFile = (id) => join(sessionsDir(), `${id}.json`);
+/** A full UUID per session (the stable identity). */
+export const newSessionId = () => randomUUID();
+/** First segment of the UUID — a compact label for the status bar / `/sessions`. */
+export const shortId = (id) => id.slice(0, 8);
+/** Resolve a full id OR a unique prefix (e.g. the short id) to a session id, for `--resume`. */
+export function resolveSessionId(idOrPrefix) {
+    if (existsSync(sessionFile(idOrPrefix)))
+        return idOrPrefix;
+    const hit = listSessions().find((m) => m.id.startsWith(idOrPrefix));
+    return hit ? hit.id : null;
+}
+const STOP = new Set("the a an to of for and or with in on at my our your this that it is please can could you help me we add fix make do run create update change implement".split(" "));
+const WORDS = "amber basalt cedar delta ember flint grove harbor indigo jade kelp larch maple onyx quartz river slate terra umber vale willow zephyr".split(" ");
+/** A short, ASCII, few-word session name from the first message — no CJK or garbled chars. For
+ *  all-CJK / empty input, a stable word derived from the text. Keeps the status bar tidy. */
+export function cleanSessionName(raw) {
+    const words = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]+/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 1 && !STOP.has(w));
+    const slug = words.slice(0, 3).join("-").slice(0, 24).replace(/^-+|-+$/g, "");
+    if (slug)
+        return slug;
+    let h = 0;
+    for (const ch of raw)
+        h = (h * 31 + ch.charCodeAt(0)) >>> 0;
+    return WORDS[h % WORDS.length] ?? "session";
+}
+/** A concise, human session name auto-summarized from the first message. Language-agnostic — keeps CJK
+ *  (unlike the ASCII-slug `cleanSessionName`), trims code/whitespace, caps length. Empty for blank input
+ *  (callers fall back to the short id, never "new session"). */
+export function deriveTitle(text) {
+    const t = text
+        .replace(/^\/\S+\s*/, "") // drop a leading slash-command
+        .replace(/```[\s\S]*?```/g, " ") // drop fenced code blocks
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!t)
+        return "";
+    const max = 40;
+    return t.length <= max ? t : t.slice(0, max).replace(/\s+\S*$/, "").trim() + "…";
+}
+export function titleFrom(history) {
+    const firstUser = history.find((h) => h.role === "user");
+    return deriveTitle(firstUser && firstUser.role === "user" ? firstUser.content : "");
+}
+export function saveSession(meta, history) {
+    meta.updatedAt = new Date().toISOString();
+    const data = { meta, history };
+    writeFileSync(sessionFile(meta.id), JSON.stringify(data, null, 2), "utf8");
+}
+export function loadSession(id) {
+    const p = sessionFile(id);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Session metas, newest first; optionally filtered to a cwd. */
+export function listSessions(cwd) {
+    let metas = [];
+    for (const f of readdirSync(sessionsDir())) {
+        if (!f.endsWith(".json"))
+            continue;
+        try {
+            metas.push(JSON.parse(readFileSync(join(sessionsDir(), f), "utf8")).meta);
+        }
+        catch {
+            /* skip corrupt */
+        }
+    }
+    if (cwd)
+        metas = metas.filter((m) => m.cwd === cwd);
+    return metas.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+export function latestForCwd(cwd) {
+    const [m] = listSessions(cwd);
+    return m ? loadSession(m.id) : null;
+}

package/dist/skills/skills.js

@@ -0,0 +1,141 @@
+// Skills — agentskills.io-standard capabilities at <project>/.hara/skills/<name>/SKILL.md (+ global
+// ~/.hara/skills). Frontmatter: name, description (required) + when_to_use / allowed-tools /
+// context inline|fork / model / paths / user-invocable / disable-model-invocation. The body is the
+// instructions, loaded ON DEMAND (progressive disclosure) — only the frontmatter index sits in context.
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { findProjectRoot } from "../context/agents-md.js";
+import { scanMemory } from "../memory/guard.js";
+import { pluginSkillDirs } from "../plugins/plugins.js";
+export function skillsDir(cwd) {
+    return join(findProjectRoot(cwd), ".hara", "skills");
+}
+export function globalSkillsDir() {
+    return join(homedir(), ".hara", "skills");
+}
+/** Search roots, lowest→highest precedence (later wins on id clash): plugins < global < project. */
+export function skillsDirs(cwd) {
+    return [...pluginSkillDirs(), globalSkillsDir(), skillsDir(cwd)];
+}
+function listVal(v) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === "string" && v.trim())
+        return v.split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+    return undefined;
+}
+const isFalse = (v) => v === "false" || v === false;
+const isTrue = (v) => v === "true" || v === true;
+/** Parse YAML-ish frontmatter (keys may contain hyphens, unlike roles.ts). Only the head is needed for the index. */
+function parseFrontmatter(text) {
+    const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
+    if (!m)
+        return { fm: {}, body: text.trim() };
+    const fm = {};
+    for (const raw of m[1].split("\n")) {
+        const kv = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(raw.trim());
+        if (!kv)
+            continue;
+        const val = kv[2].trim();
+        if (val.startsWith("[") && val.endsWith("]")) {
+            fm[kv[1]] = val.slice(1, -1).split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+        }
+        else {
+            fm[kv[1]] = val.replace(/^["']|["']$/g, "");
+        }
+    }
+    return { fm, body: m[2].trim() };
+}
+/** All skills' frontmatter (the index) — cheap; the body is loaded separately by loadSkillBody. */
+export function loadSkillIndex(cwd) {
+    const byId = new Map();
+    const gdir = globalSkillsDir();
+    const pdir = skillsDir(cwd);
+    for (const dir of skillsDirs(cwd)) {
+        if (!existsSync(dir))
+            continue;
+        for (const entry of readdirSync(dir)) {
+            const file = join(dir, entry, "SKILL.md"); // agentskills layout: <name>/SKILL.md
+            if (!existsSync(file))
+                continue;
+            try {
+                const { fm } = parseFrontmatter(readFileSync(file, "utf8"));
+                const id = fm.name || entry;
+                byId.set(id, {
+                    id,
+                    description: fm.description || "",
+                    whenToUse: fm.when_to_use || undefined,
+                    allowedTools: listVal(fm["allowed-tools"]),
+                    context: fm.context === "fork" ? "fork" : "inline",
+                    model: fm.model || undefined,
+                    paths: listVal(fm.paths),
+                    userInvocable: !isFalse(fm["user-invocable"]),
+                    modelInvocable: !isTrue(fm["disable-model-invocation"]),
+                    file,
+                    source: dir === gdir ? "global" : dir === pdir ? "project" : "plugin",
+                });
+            }
+            catch {
+                /* skip bad skill */
+            }
+        }
+    }
+    return [...byId.values()];
+}
+/** Read a skill's instruction body (progressive disclosure — only when the model/user opens it). */
+export function loadSkillBody(skill) {
+    try {
+        return parseFrontmatter(readFileSync(skill.file, "utf8")).body;
+    }
+    catch {
+        return "";
+    }
+}
+const DIGEST_CAP = 4000;
+let _digestCache = new Map();
+/** Compact, frozen-per-session index injected into the system prompt (name + description, one line each).
+ *  Drops model-hidden skills and any whose description fails the guard (plugin skills may be untrusted). */
+export function skillsDigest(cwd) {
+    if (_digestCache.has(cwd))
+        return _digestCache.get(cwd);
+    const lines = [];
+    for (const s of loadSkillIndex(cwd)) {
+        if (!s.modelInvocable || !s.description || !scanMemory(s.description).ok)
+            continue;
+        lines.push(`- ${s.id}: ${s.description}${s.whenToUse ? ` — ${s.whenToUse}` : ""}`);
+    }
+    let digest = lines.join("\n");
+    if (digest.length > DIGEST_CAP)
+        digest = digest.slice(0, DIGEST_CAP) + "\n…";
+    _digestCache.set(cwd, digest);
+    return digest;
+}
+/** Drop the cached digest (call after skill_create so a new skill surfaces next turn). */
+export function invalidateSkillsCache() {
+    _digestCache.clear();
+}
+const SCAFFOLD = `---
+name: verify-change
+description: Verify a code change does what it should by building and running the tests.
+when_to_use: after editing code, before declaring a task done
+---
+
+# Verify a change
+
+1. Identify how this project builds and tests (check AGENTS.md / package.json scripts).
+2. Run the build (e.g. \`tsc\` / \`npm run build\`) and report any errors.
+3. Run the relevant tests; if none exist for the change, note that.
+4. Summarize: what you ran, pass/fail, and anything still unverified.
+`;
+/** Create ~/.hara/skills/verify-change/SKILL.md as a starter example. Returns the paths written. */
+export function scaffoldSkills(cwd) {
+    const dir = join(skillsDir(cwd), "verify-change");
+    mkdirSync(dir, { recursive: true });
+    const p = join(dir, "SKILL.md");
+    if (existsSync(p))
+        return [];
+    writeFileSync(p, SCAFFOLD, "utf8");
+    invalidateSkillsCache();
+    return [p];
+}

package/dist/statusbar.js

@@ -0,0 +1,69 @@
+// REPL input frame — a border line above and below the prompt, session name in the top-right,
+// mode/tokens/concurrency in the bottom border. Drawn around the readline prompt (plain printed
+// lines — no scroll region, works everywhere). `borderTop`/`borderBottom` are pure, for tests.
+import { stdout } from "node:process";
+import { c } from "./ui.js";
+import { activity } from "./activity.js";
+export const MODES = ["suggest", "auto-edit", "full-auto"];
+let state = { sessionName: "new session", model: "", approval: "suggest", input: 0, output: 0, ctxPct: 0 };
+let active = false;
+const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
+const vlen = (s) => stripAnsi(s).length;
+const fmtTok = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : `${n}`);
+const truncate = (s, max) => (s.length <= max ? s : s.slice(0, Math.max(0, max - 1)) + "…");
+const rule = (n) => c.dim("─".repeat(Math.max(0, n)));
+export function contextWindow(model) {
+    const m = model.toLowerCase();
+    if (/haiku/.test(m))
+        return 200_000;
+    if (/(opus|sonnet|fable)|claude-4|qwen3|glm-[45]|max-2026|coder|1m/.test(m))
+        return 1_000_000;
+    return 200_000;
+}
+export const ctxPctFor = (model, lastInput) => lastInput > 0 ? Math.min(99, Math.round((lastInput / contextWindow(model)) * 100)) : 0;
+/** Top border with the session name in the right corner: `────────── ⏺ session ─` */
+export function borderTop(s, cols) {
+    const name = truncate(s.sessionName || "new session", Math.max(8, cols - 14));
+    const label = `${c.cyan("⏺")} ${c.bold(name)}`;
+    return rule(cols - vlen(label) - 3) + " " + label + " " + rule(1);
+}
+/** Bottom border carrying mode · tokens · concurrency: `── ◆suggest auto-edit full-auto · ↑0 ↓0 · ⛁ ──` */
+export function borderBottom(s, cols, agents) {
+    const sel = MODES.map((m) => (m === s.approval ? c.green(`◆${m}`) : c.dim(m))).join(" ");
+    const ctx = s.ctxPct > 0 ? ` · ctx ${s.ctxPct}%` : "";
+    const ag = agents > 0 ? c.yellow(`⛁${agents}`) : c.dim("⛁");
+    const info = `${sel} ${c.dim("·")} ${c.dim(`↑${fmtTok(s.input)} ↓${fmtTok(s.output)}${ctx}`)} ${c.dim("·")} ${ag}`;
+    return rule(2) + " " + info + " " + rule(cols - vlen(info) - 4);
+}
+export function install(initial) {
+    state = { ...state, ...initial };
+    active = process.env.HARA_FOOTER !== "0" && !!stdout.isTTY;
+}
+export function update(partial) {
+    state = { ...state, ...partial };
+}
+const w = (s) => {
+    try {
+        stdout.write(s);
+    }
+    catch {
+        /* ignore */
+    }
+};
+/** Top border — call right before the prompt. */
+export function renderTop() {
+    if (active)
+        w(borderTop(state, stdout.columns ?? 80) + "\n");
+}
+/** Bottom border — call right after the prompt is submitted. */
+export function renderBottom() {
+    if (active)
+        w(borderBottom(state, stdout.columns ?? 80, activity.running) + "\n");
+}
+export const isActive = () => active;
+export function uninstall() {
+    /* no-op (border model — nothing pinned) */
+}
+export function nextMode(m) {
+    return MODES[(MODES.indexOf(m) + 1) % MODES.length];
+}

package/dist/tools/agent.js

@@ -0,0 +1,26 @@
+// agent — delegate a self-contained sub-task to a fresh sub-agent. Several `agent` calls in one
+// turn run in PARALLEL (kind "read" → concurrent), making the footer's ⛁ count real. Sub-agents are
+// read-only by default (safe to parallelize); the actual spawn is provided via ctx.spawn.
+import { registerTool } from "./registry.js";
+registerTool({
+    name: "agent",
+    description: "Delegate an independent sub-task to a fresh sub-agent and get its result. Spawn SEVERAL in one " +
+        "turn to run them in parallel (e.g. analyze/search/review N things at once). Sub-agents are " +
+        "read-only by default; pass a `role` id to use that role's persona + tools. Not for edits.",
+    input_schema: {
+        type: "object",
+        properties: {
+            task: { type: "string", description: "the self-contained sub-task to delegate" },
+            role: { type: "string", description: "optional role id (uses its persona + tool subset)" },
+        },
+        required: ["task"],
+    },
+    kind: "read", // parallel-safe: multiple agent() calls in a turn run concurrently
+    async run(input, ctx) {
+        if (!ctx.spawn)
+            return "Error: sub-agents are not available in this context.";
+        if (typeof input.task !== "string" || !input.task.trim())
+            return "Error: agent needs a `task`.";
+        return await ctx.spawn(input.task, input.role ? String(input.role) : undefined);
+    },
+});

package/dist/tools/apply-core.js

@@ -0,0 +1,63 @@
+// Shared edit-application core — applies old→new string edits to file text with a
+// quote-insensitive fallback. Used by edit_file (single file) and apply_patch (multi-file).
+// Quote variants — models often emit curly quotes where the file has straight ones (or vice versa).
+const SINGLE = "'‘’‚‛";
+const DOUBLE = '"“”„‟';
+const reEscape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** RegExp source for `s` where any quote char matches any of its typographic variants. */
+function quoteFlexSource(s) {
+    let out = "";
+    for (const ch of s) {
+        if (SINGLE.includes(ch))
+            out += `[${SINGLE}]`;
+        else if (DOUBLE.includes(ch))
+            out += `[${DOUBLE}]`;
+        else
+            out += reEscape(ch);
+    }
+    return out;
+}
+/** Apply one old→new replacement to `src`. Returns an error reason on not-found/ambiguous. */
+function applyOne(src, oldStr, newStr, replaceAll) {
+    // 1) exact
+    let count = src.split(oldStr).length - 1;
+    if (count > 0) {
+        if (count > 1 && !replaceAll)
+            return { error: `appears ${count}×; add context or set replace_all` };
+        const text = replaceAll ? src.split(oldStr).join(newStr) : src.replace(oldStr, () => newStr);
+        return { text, count, fuzzy: false };
+    }
+    // 2) quote-flexible fallback
+    const re = new RegExp(quoteFlexSource(oldStr), "g");
+    const matches = src.match(re);
+    count = matches ? matches.length : 0;
+    if (count === 0)
+        return { error: "not found" };
+    if (count > 1 && !replaceAll)
+        return { error: `appears ${count}× (quote-insensitive); add context or set replace_all` };
+    const text = src.replace(re, () => newStr);
+    return { text, count, fuzzy: true };
+}
+/** Apply a sequence of edits to `text`. All-or-nothing: returns an error (no partial result). */
+export function applyEdits(text, edits) {
+    if (!edits.length)
+        return { error: "no edits provided" };
+    for (const e of edits) {
+        if (typeof e.old_string !== "string" || typeof e.new_string !== "string")
+            return { error: "each edit needs string old_string and new_string" };
+        if (e.old_string === e.new_string)
+            return { error: "an edit has identical old_string and new_string" };
+    }
+    let out = text;
+    let total = 0;
+    let fuzzy = false;
+    for (let i = 0; i < edits.length; i++) {
+        const r = applyOne(out, edits[i].old_string, edits[i].new_string, !!edits[i].replace_all);
+        if ("error" in r)
+            return { error: `edit ${i + 1}/${edits.length} — old_string ${r.error}` };
+        out = r.text;
+        total += r.count;
+        fuzzy = fuzzy || r.fuzzy;
+    }
+    return { text: out, total, fuzzy };
+}

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 || ""}`);
+        }
+    },
+});