@nanhara/hara 0.0.2 → 0.48.0

package/dist/mcp/client.js

@@ -0,0 +1,54 @@
+// MCP client — connect to configured MCP servers (stdio) and register their tools into hara.
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { registerTool } from "../tools/registry.js";
+const clients = [];
+/** Connect each server, register its tools as `mcp__<server>__<tool>`. Returns #tools registered. */
+export async function connectMcpServers(servers, log) {
+    let count = 0;
+    for (const [name, cfg] of Object.entries(servers)) {
+        try {
+            const transport = new StdioClientTransport({
+                command: cfg.command,
+                args: cfg.args ?? [],
+                env: { ...process.env, ...(cfg.env ?? {}) },
+            });
+            const client = new Client({ name: "hara", version: "0.4.0" }, { capabilities: {} });
+            await client.connect(transport);
+            clients.push(client);
+            const { tools } = await client.listTools();
+            for (const t of tools) {
+                const schema = t.inputSchema ?? { type: "object", properties: {} };
+                registerTool({
+                    name: `mcp__${name}__${t.name}`,
+                    description: t.description ?? `${name}/${t.name}`,
+                    input_schema: schema,
+                    kind: "exec",
+                    async run(input) {
+                        const res = await client.callTool({ name: t.name, arguments: input ?? {} });
+                        const blocks = Array.isArray(res?.content) ? res.content : [];
+                        const text = blocks.map((b) => (b?.type === "text" ? b.text : JSON.stringify(b))).join("\n");
+                        return text || "(no output)";
+                    },
+                });
+                count++;
+            }
+            log(`mcp: ${name} → ${tools.length} tool(s)`);
+        }
+        catch (e) {
+            log(`mcp: ${name} failed (${e?.message ?? e})`);
+        }
+    }
+    return count;
+}
+export async function closeMcp() {
+    for (const cl of clients) {
+        try {
+            await cl.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    clients.length = 0;
+}

package/dist/md.js

@@ -0,0 +1,52 @@
+// Tiny streaming Markdown renderer for assistant output. Line-buffered (style on complete lines,
+// codex-style) so headers/bold/inline-code/bullets render in a terminal instead of showing raw
+// `**`/`##`/backticks. Code fences are passed through verbatim (copy-paste accurate). Color via the
+// shared `c` helper, so in a non-TTY it degrades to the structural transform only.
+import { c } from "./ui.js";
+const inline = (s) => s.replace(/\*\*([^*]+)\*\*/g, (_, x) => c.bold(x)).replace(/`([^`]+)`/g, (_, x) => c.cyan(x));
+/** Style one complete line given the running fence state. */
+export function styleLine(line, state) {
+    if (line.trimStart().startsWith("```")) {
+        state.inFence = !state.inFence;
+        return c.dim(line);
+    }
+    if (state.inFence)
+        return line; // inside a code block — leave verbatim
+    const h = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (h)
+        return c.bold(inline(h[2]));
+    const b = /^(\s*)[-*]\s+(.*)$/.exec(line);
+    if (b)
+        return `${b[1]}${c.cyan("•")} ${inline(b[2])}`;
+    return inline(line);
+}
+/** Whole-block render (non-streaming) — used in tests. */
+export function renderMarkdown(text) {
+    const state = { inFence: false };
+    return text
+        .split("\n")
+        .map((l) => styleLine(l, state))
+        .join("\n");
+}
+/** Streaming sink: feed deltas via push(), flush the tail with end(). Styles complete lines. */
+export function makeRenderer(write) {
+    const state = { inFence: false };
+    let buf = "";
+    return {
+        push(d) {
+            buf += d;
+            let nl;
+            while ((nl = buf.indexOf("\n")) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                write(styleLine(line, state) + "\n");
+            }
+        },
+        end() {
+            if (buf) {
+                write(styleLine(buf, state));
+                buf = "";
+            }
+        },
+    };
+}

package/dist/memory/guard.js

@@ -0,0 +1,51 @@
+// Lexical guard for agent-written content (memory + skills). No embeddings — small pattern lists.
+// Two policies by direction (the asset pipeline's "redact on the way in, block on the way out"):
+//   • scanMemory()  — BLOCK: used at LOAD/inject time (skill bodies, memory) — poisoned content must not
+//                     come back into the prompt. Checks secrets AND injection phrases.
+//   • redactSecrets()/scrubLocal() — REDACT: used at CAPTURE time (skill_create) — strip secrets +
+//                     local identifiers so a reusable snippet is safe to persist (and later share).
+import { homedir } from "node:os";
+// Secret-shaped tokens — redactable to a typed placeholder on capture; still blocked on load.
+const SECRETS = [
+    [/\bsk-[a-zA-Z0-9_-]{16,}\b/, "sk-key"],
+    [/\bAKIA[0-9A-Z]{16}\b/, "aws-key"],
+    [/\bghp_[A-Za-z0-9]{20,}\b/, "github-token"],
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/, "private-key"],
+];
+// Prompt-injection phrases + exfil URLs — block-only (can't meaningfully "redact" an instruction).
+const INJECTION = [
+    [/ignore (all |your )?(previous|prior|above) (instructions|prompts?)/i, "prompt-injection phrase"],
+    [/disregard (your |the )?(system prompt|instructions|rules|guidelines)/i, "prompt-injection phrase"],
+    [/\bfile:\/\/\/?\S+/i, "file:// URL"],
+];
+const ALL = [...SECRETS, ...INJECTION];
+/** Scan agent-written text; ok=false (with labels) when something looks unsafe to persist/inject. */
+export function scanMemory(text) {
+    const hits = [...new Set(ALL.filter(([re]) => re.test(text)).map(([, label]) => label))];
+    return { ok: hits.length === 0, hits };
+}
+/** Replace secret-shaped tokens with typed placeholders (capture path). Injection phrases are left for
+ *  scanMemory to block — they aren't redactable. */
+export function redactSecrets(text) {
+    const redactions = [];
+    let out = text;
+    for (const [re, label] of SECRETS) {
+        const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g");
+        out = out.replace(g, () => {
+            redactions.push(label);
+            return `<REDACTED:${label}>`;
+        });
+    }
+    return { text: out, redactions };
+}
+/** Deterministically generalize local identifiers so a captured snippet isn't tied to this machine:
+ *  the project path → <project>, the home dir → ~, and email addresses → <email>. Light + reversible. */
+export function scrubLocal(text, cwd) {
+    let out = text;
+    if (cwd)
+        out = out.split(cwd).join("<project>");
+    const home = homedir();
+    if (home)
+        out = out.split(home).join("~");
+    return out.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, "<email>");
+}

package/dist/memory/store.js

@@ -0,0 +1,93 @@
+// Agent-curated memory — durable facts/decisions/prefs hara records and recalls across sessions.
+// File-backed Markdown (git-versionable, human-readable), two scopes: global ~/.hara/memory and
+// project <root>/.hara/memory. Lexical search reuses recall.ts; no embeddings (local-first).
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync } from "node:fs";
+import { findProjectRoot } from "../context/agents-md.js";
+const DIGEST_CAP = 4000; // chars of MEMORY/USER injected at session start (logs reached via search)
+export function memoryDir(scope, cwd) {
+    if (scope === "global")
+        return process.env.HARA_MEMORY || join(homedir(), ".hara", "memory");
+    return join(findProjectRoot(cwd), ".hara", "memory");
+}
+/** Dirs to search for memory (project first, then global). */
+export function memoryRoots(cwd) {
+    return [memoryDir("project", cwd), memoryDir("global", cwd)];
+}
+function today() {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+function targetFile(scope, target, cwd) {
+    const dir = memoryDir(scope, cwd);
+    if (target === "user")
+        return join(dir, "USER.md");
+    if (target === "log")
+        return join(dir, "log", `${today()}.md`);
+    return join(dir, "MEMORY.md");
+}
+export function appendMemory(scope, target, content, cwd) {
+    const f = targetFile(scope, target, cwd);
+    mkdirSync(dirname(f), { recursive: true });
+    appendFileSync(f, (existsSync(f) ? "\n" : "") + content.trim() + "\n", "utf8");
+    return f;
+}
+export function replaceMemory(scope, target, content, cwd) {
+    const f = targetFile(scope, target, cwd);
+    mkdirSync(dirname(f), { recursive: true });
+    writeFileSync(f, content.trim() + "\n", "utf8");
+    return f;
+}
+export function forgetMemory(scope, target, match, cwd) {
+    const f = targetFile(scope, target, cwd);
+    if (!existsSync(f) || !match)
+        return 0;
+    const lines = readFileSync(f, "utf8").split("\n");
+    const kept = lines.filter((l) => !l.includes(match));
+    writeFileSync(f, kept.join("\n"), "utf8");
+    return lines.length - kept.length;
+}
+/** Capped MEMORY + USER digest (project + global) for frozen-snapshot injection at session start. */
+export function memoryDigest(cwd) {
+    const sources = [
+        ["project", "memory", "project MEMORY"],
+        ["global", "memory", "global MEMORY"],
+        ["global", "user", "USER preferences"],
+    ];
+    const parts = [];
+    for (const [scope, target, label] of sources) {
+        const f = targetFile(scope, target, cwd);
+        if (!existsSync(f))
+            continue;
+        try {
+            const t = readFileSync(f, "utf8").trim();
+            if (t)
+                parts.push(`## ${label}\n${t}`);
+        }
+        catch {
+            /* skip unreadable */
+        }
+    }
+    const out = parts.join("\n\n");
+    return out.length > DIGEST_CAP ? out.slice(0, DIGEST_CAP) + "\n…[memory truncated — use memory_search]" : out;
+}
+/** Create memory dirs + seed files (global + project). Returns files written. */
+export function scaffoldMemory(cwd) {
+    const written = [];
+    for (const scope of ["global", "project"]) {
+        mkdirSync(join(memoryDir(scope, cwd), "log"), { recursive: true });
+        const mem = join(memoryDir(scope, cwd), "MEMORY.md");
+        if (!existsSync(mem)) {
+            writeFileSync(mem, `# hara ${scope} memory\n\nDurable facts & decisions hara records and recalls across sessions. Git-versionable — edit freely.\n`, "utf8");
+            written.push(mem);
+        }
+    }
+    const user = join(memoryDir("global", cwd), "USER.md");
+    if (!existsSync(user)) {
+        writeFileSync(user, "# User preferences\n\nHow you like hara to work — voice, conventions, do/don't.\n", "utf8");
+        written.push(user);
+    }
+    return written;
+}

package/dist/org/planner.js

@@ -0,0 +1,174 @@
+// Atomization planner — the execution methodology made real:
+// FRAME the task → ATOMIZE into smallest verifiable steps → SEQUENCE as a DAG →
+// execute each atom (optionally routed to a role) → VERIFY gate. State is the SSOT
+// at .hara/org/plan.json. This is hara's differentiator: not one agent, an org that plans.
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { runShell } from "../sandbox.js";
+const PLAN_SYSTEM = `You are hara's planner. Decompose a coding task using this method:
+1) FRAME the goal in one sentence.
+2) ATOMIZE into the smallest independently-verifiable steps.
+3) SEQUENCE them with dependencies (a step lists the ids it depends on).
+Return ONLY a JSON object, no prose:
+{"atoms":[{"id":"a1","title":"imperative step","detail":"how/where","deps":[],"verify":"observable done-criteria","check":"shell command exiting 0 iff done (optional)","role":"<roleId or omit>"}]}
+Rules: short ids (a1,a2,…); deps reference earlier ids only; typically 3-8 atoms; each atom small and verifiable. Prefer a concrete 'check' command (e.g. "npm test", "tsc --noEmit", "test -f src/x.ts") so a step is verified objectively; omit 'check' if none fits.`;
+/** Ask the model to decompose `task` into an atomized, sequenced plan. */
+export async function decompose(provider, task, roles) {
+    const roleHint = roles.length ? `\nAvailable roles for the optional "role" field: ${roles.map((r) => r.id).join(", ")}.` : "";
+    const r = await provider.turn({
+        system: PLAN_SYSTEM + roleHint,
+        history: [{ role: "user", content: `Task: ${task}\n\nReturn the JSON plan.` }],
+        tools: [],
+        onText: () => { },
+    });
+    return { task, atoms: parsePlan(r.text), createdAt: new Date().toISOString() };
+}
+/** Extract + normalize atoms from the model's (possibly fenced/noisy) JSON reply. */
+export function parsePlan(text) {
+    const json = extractJson(text);
+    if (!json)
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch {
+        return [];
+    }
+    const list = Array.isArray(raw) ? raw : Array.isArray(raw?.atoms) ? raw.atoms : [];
+    const atoms = [];
+    list.forEach((a, i) => {
+        if (!a || typeof a.title !== "string")
+            return;
+        atoms.push({
+            id: typeof a.id === "string" && a.id ? a.id : `a${i + 1}`,
+            title: a.title.trim(),
+            detail: typeof a.detail === "string" ? a.detail : undefined,
+            deps: Array.isArray(a.deps) ? a.deps.filter((d) => typeof d === "string") : [],
+            verify: typeof a.verify === "string" ? a.verify : undefined,
+            check: typeof a.check === "string" && a.check ? a.check : undefined,
+            role: typeof a.role === "string" && a.role ? a.role : undefined,
+            status: "pending",
+        });
+    });
+    return atoms;
+}
+function extractJson(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenced)
+        return fenced[1].trim();
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start >= 0 && end > start)
+        return text.slice(start, end + 1);
+    return null;
+}
+/** Topological order (Kahn). Unknown deps are ignored; returns an error on a cycle. */
+export function topoOrder(atoms) {
+    const byId = new Map(atoms.map((a) => [a.id, a]));
+    const indeg = new Map(atoms.map((a) => [a.id, 0]));
+    const adj = new Map(atoms.map((a) => [a.id, []]));
+    for (const a of atoms) {
+        for (const d of a.deps) {
+            if (!byId.has(d))
+                continue; // ignore dangling deps
+            indeg.set(a.id, (indeg.get(a.id) ?? 0) + 1);
+            adj.get(d).push(a.id);
+        }
+    }
+    const q = atoms.filter((a) => (indeg.get(a.id) ?? 0) === 0).map((a) => a.id);
+    const order = [];
+    while (q.length) {
+        const id = q.shift();
+        order.push(byId.get(id));
+        for (const nx of adj.get(id)) {
+            indeg.set(nx, indeg.get(nx) - 1);
+            if (indeg.get(nx) === 0)
+                q.push(nx);
+        }
+    }
+    if (order.length !== atoms.length)
+        return { error: "plan has a dependency cycle — cannot sequence" };
+    return { ok: order };
+}
+/** Group atoms into dependency "waves": every atom in a wave depends only on atoms in EARLIER waves, so a
+ *  wave's atoms are mutually independent and may run concurrently. Preserves atom order; errors on a cycle. */
+export function topoWaves(atoms) {
+    const byId = new Map(atoms.map((a) => [a.id, a]));
+    const remaining = new Map(atoms.map((a) => [a.id, a]));
+    const done = new Set();
+    const waves = [];
+    while (remaining.size) {
+        const wave = [...remaining.values()].filter((a) => a.deps.every((d) => !byId.has(d) || done.has(d)));
+        if (!wave.length)
+            return { error: "plan has a dependency cycle — cannot sequence" };
+        for (const a of wave)
+            remaining.delete(a.id);
+        for (const a of wave)
+            done.add(a.id);
+        waves.push(wave);
+    }
+    return { ok: waves };
+}
+/** Prompt to execute a single atom in the context of the overall plan. */
+export function atomPrompt(atom, plan, done) {
+    const priors = done.length ? `Already completed: ${done.map((a) => a.title).join("; ")}.\n` : "";
+    return (`You are executing ONE step of a larger plan — do only this step.\n` +
+        `Overall task: ${plan.task}\n` +
+        `${priors}` +
+        `This step (${atom.id}): ${atom.title}\n` +
+        (atom.detail ? `Details: ${atom.detail}\n` : "") +
+        `Done when: ${atom.verify ?? "the step is complete"}\n` +
+        `Use tools as needed. Finish with a one-line result.`);
+}
+/** Soft verification gate: ask the model whether the atom met its done-criteria. */
+export async function verify(provider, atom, transcriptTail) {
+    const r = await provider.turn({
+        system: "You verify whether a coding step met its done-criteria. " +
+            "Reply EXACTLY 'DONE' if met, or 'NEEDSWORK: <short reason>' if not. No other text.",
+        history: [
+            {
+                role: "user",
+                content: `Step: ${atom.title}\nDone-criteria: ${atom.verify ?? "step complete"}\n\nWhat the agent did:\n${transcriptTail.slice(0, 4000)}\n\nVerdict:`,
+            },
+        ],
+        tools: [],
+        onText: () => { },
+    });
+    const t = r.text.trim();
+    if (/^done\b/i.test(t))
+        return { ok: true, reason: "verified" };
+    return { ok: false, reason: t.replace(/^needswork:?\s*/i, "").slice(0, 200) || "did not meet criteria" };
+}
+/** Objective gate: run the atom's `check` shell command; exit 0 = pass. */
+export async function runCheck(cmd, cwd, sandbox) {
+    try {
+        const { stdout } = await runShell(cmd, cwd, sandbox, { timeout: 120_000, maxBuffer: 1_000_000 });
+        return { ok: true, reason: (stdout.trim().split("\n").pop() || "ok").slice(0, 200) };
+    }
+    catch (e) {
+        const out = (e?.stderr || e?.stdout || e?.message || "").toString().trim();
+        return { ok: false, reason: (out.split("\n").pop() || `exit ${e?.code ?? "?"}`).slice(0, 200) };
+    }
+}
+function planDir(cwd) {
+    const d = join(cwd, ".hara", "org");
+    mkdirSync(d, { recursive: true });
+    return d;
+}
+const planFile = (cwd) => join(planDir(cwd), "plan.json");
+/** SSOT: persist plan state so it's inspectable / resumable. */
+export function savePlan(cwd, plan) {
+    writeFileSync(planFile(cwd), JSON.stringify(plan, null, 2), "utf8");
+}
+export function loadPlan(cwd) {
+    const p = planFile(cwd);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/org/roles.js

@@ -0,0 +1,140 @@
+// Org roles — markdown agent definitions in <project>/.hara/roles/*.md.
+// Frontmatter: name, description, owns[], rejects[], model?, allowTools[], denyTools[]. Body = persona/system.
+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 { pluginRoleDirs } from "../plugins/plugins.js";
+export function rolesDir(cwd) {
+    return join(findProjectRoot(cwd), ".hara", "roles");
+}
+/** Global roles — reusable personas across all projects. */
+export function globalRolesDir() {
+    return join(homedir(), ".hara", "roles");
+}
+/** Claude-Code subagents (`.claude/agents/*.md`) — consumed for ecosystem interop (project scope). */
+export function claudeAgentsDir(cwd) {
+    return join(findProjectRoot(cwd), ".claude", "agents");
+}
+/** Accept Claude-Code `tools:` (comma string or list) as an alias for hara's allowTools. */
+function claudeTools(v) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === "string" && v.trim())
+        return v.split(",").map((s) => s.trim()).filter(Boolean);
+    return undefined;
+}
+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 line = raw.trim();
+        const kv = /^([A-Za-z0-9_]+)\s*:\s*(.*)$/.exec(line);
+        if (!kv)
+            continue;
+        const key = kv[1];
+        const val = kv[2].trim();
+        if (val.startsWith("[") && val.endsWith("]")) {
+            fm[key] = val
+                .slice(1, -1)
+                .split(",")
+                .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+                .filter(Boolean);
+        }
+        else {
+            fm[key] = val.replace(/^["']|["']$/g, "");
+        }
+    }
+    return { fm, body: m[2].trim() };
+}
+export function loadRoles(cwd) {
+    const byId = new Map();
+    // lowest→highest precedence: plugins < global < .claude/agents < .hara/roles (project wins, same as memory/config)
+    for (const dir of [...pluginRoleDirs(), globalRolesDir(), claudeAgentsDir(cwd), rolesDir(cwd)]) {
+        if (!existsSync(dir))
+            continue;
+        for (const f of readdirSync(dir)) {
+            if (!f.endsWith(".md") || f === "README.md")
+                continue;
+            try {
+                const { fm, body } = parseFrontmatter(readFileSync(join(dir, f), "utf8"));
+                const id = fm.name || f.replace(/\.md$/, "");
+                byId.set(id, {
+                    id,
+                    description: fm.description || "",
+                    owns: Array.isArray(fm.owns) ? fm.owns : [],
+                    rejects: Array.isArray(fm.rejects) ? fm.rejects : [],
+                    model: fm.model || undefined,
+                    allowTools: Array.isArray(fm.allowTools) ? fm.allowTools : claudeTools(fm.tools),
+                    denyTools: Array.isArray(fm.denyTools) ? fm.denyTools : undefined,
+                    system: body,
+                });
+            }
+            catch {
+                /* skip bad role file */
+            }
+        }
+    }
+    return [...byId.values()];
+}
+export function hasRoles(cwd) {
+    return loadRoles(cwd).length > 0;
+}
+const SCAFFOLD = {
+    "implementer.md": `---
+name: implementer
+description: Implements features, fixes bugs, and refactors code.
+owns: [implement, add, feature, fix, bug, refactor, build, create, write, change]
+model:
+---
+You are the **implementer** on an engineering team. You write and change code to satisfy the task.
+Make small, verifiable edits (prefer edit_file over rewriting). Run tests/build when relevant.
+End with a one-line summary of what changed.
+`,
+    "reviewer.md": `---
+name: reviewer
+description: Reviews code for bugs, correctness, security, and style. Does not modify code.
+owns: [review, audit, check, correctness, security, vulnerability, lint, quality]
+allowTools: [read_file, bash]
+---
+You are the **reviewer**. Read the relevant code and report concrete issues (bug / correctness /
+security / style) with file:line and a suggested fix. Do NOT edit files — you have read-only tools.
+Be specific; skip nitpicks unless asked.
+`,
+    "docs.md": `---
+name: docs
+description: Writes and updates documentation, READMEs, and code comments.
+owns: [doc, docs, document, readme, comment, explain, guide, changelog]
+---
+You are the **docs** writer. Produce clear, concise documentation grounded in the actual code.
+Update or create the relevant files with write_file/edit_file. Match the project's existing tone.
+`,
+    "README.md": `# Org roles
+
+Each \`*.md\` here is a role-agent. Frontmatter:
+
+- \`name\` — role id
+- \`description\` — what it owns (used by the dispatcher)
+- \`owns\` — keywords that route a task here (OWN)
+- \`rejects\` — keywords that exclude this role (REJECT)
+- \`model\` — optional model override
+- \`allowTools\` / \`denyTools\` — restrict the role's tools
+
+Run \`hara org "<task>"\` to dispatch a task to the owning role, or \`hara org --role <id> "<task>"\`.
+`,
+};
+export function scaffoldRoles(cwd) {
+    const dir = rolesDir(cwd);
+    mkdirSync(dir, { recursive: true });
+    const written = [];
+    for (const [name, content] of Object.entries(SCAFFOLD)) {
+        const p = join(dir, name);
+        if (!existsSync(p)) {
+            writeFileSync(p, content, "utf8");
+            written.push(name);
+        }
+    }
+    return written;
+}

package/dist/org/router.js

@@ -0,0 +1,39 @@
+/** Deterministic routing by `owns`/`rejects` keywords. null if no clear owner. */
+export function routeByKeywords(task, roles) {
+    const t = task.toLowerCase();
+    let best = null;
+    for (const r of roles) {
+        if (r.rejects.some((k) => k && t.includes(k.toLowerCase())))
+            continue;
+        const score = r.owns.filter((k) => k && t.includes(k.toLowerCase())).length;
+        if (score > 0 && (!best || score > best.score))
+            best = { role: r, score };
+    }
+    return best;
+}
+/** Prompt for the LLM dispatcher fallback. */
+export function buildDispatchPrompt(task, roles) {
+    const list = roles.map((r) => `- ${r.id}: ${r.description}`).join("\n");
+    return `You are the dispatcher in an engineering org. Pick the single best role to own this task.
+
+Roles:
+${list}
+
+Task: ${task}
+
+Reply with ONLY the role id, nothing else.`;
+}
+/** Resolve a role id from free-form dispatcher output. */
+export function parseRoleId(text, roles) {
+    const t = text.toLowerCase();
+    // prefer an exact whole-token id match, else substring
+    for (const r of roles) {
+        const re = new RegExp(`\\b${r.id.toLowerCase().replace(/[^a-z0-9]/g, "\\$&")}\\b`);
+        if (re.test(t))
+            return r;
+    }
+    for (const r of roles)
+        if (t.includes(r.id.toLowerCase()))
+            return r;
+    return null;
+}