@nanhara/hara 0.0.2 → 0.33.0

package/README.md

@@ -6,23 +6,212 @@
 > with routing boundaries, a dispatcher, a single source-of-truth data layer, human-in-the-loop
 > approvals, and cron autonomy.
 
-🚧 **Early placeholder.** The real CLI is under active development. This package reserves
-`@nanhara/hara` on npm. Follow along:
+🚧 **v0.33** · TypeScript · local-first · Apache-2.0
 
-- Repo: https://github.com/hara-cli/hara
-- Site: https://hara.run
+**Highlights**
+- **An org, not just an agent** — `hara org "<task>"` routes work to the role that *owns* it; `hara plan "<task>"` decomposes a task into a verified DAG of atoms (frame → atomize → sequence → execute → **verify gate**).
+- **Real terminal UX** — an **ink TUI**: bottom-pinned input box, **plan mode** (read-only → propose a plan → approve → execute), selectable approvals with "don't ask again", windowed reasoning, **paste images** (Ctrl+V) for vision models, light/dark theme.
+- **Persistent memory + self-evolution** — `memory_*` tools over global/project `MEMORY.md`; the agent recalls before acting, **proactively saves** durable facts, and grows its own playbooks (a lexical guard screens what it writes).
+- **Multi-provider, all streamed** — Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) with live Markdown + visible reasoning.
+- **Solid coding core** — `edit_file` / `apply_patch` (atomic multi-file) with colored diffs · `grep`/`glob`/`ls`/`codebase_search` (lexical + optional semantic search over the repo) /`web_fetch` · fuzzy `@file` · `/undo` · `/compact` · **Esc-to-interrupt** · parallel sub-agents · MCP client · macOS sandbox.
+
+Track it: https://github.com/hara-cli/hara · https://hara.run
+
+## Install
 
 ```bash
 npm i -g @nanhara/hara
-hara            # prints status
-hara --version
 ```
 
-## License
+Or from source:
+
+```bash
+git clone https://github.com/hara-cli/hara && cd hara
+npm install        # builds via the prepare script
+npm install -g .   # or: npm link
+```
+
+## Quickstart
+
+```bash
+npm i -g @nanhara/hara
+hara login qwen          # free Qwen OAuth  (or: export ANTHROPIC_API_KEY=…)
+cd your-project
+hara                     # offers to write AGENTS.md, then drops you into the TUI
+```
+
+Then just type a task — e.g. `fix the null check in @src/login.ts and run the tests`.
+**shift+tab** cycles approvals (incl. **plan mode**) · **Esc** interrupts · `@`+Tab attaches a file · `/exit` quits.
+
+One-shot, no REPL:
+
+```bash
+hara -p "summarize @README.md and list any TODOs"
+```
+
+## Setup
+
+hara is **multi-provider** — pick a provider + key.
+
+**Anthropic (default)**
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**Qwen — free OAuth** ("Qwen Code" tier, no API key — same flow as OpenClaw)
+```bash
+hara login qwen      # device login: open the printed URL, approve — token auto-refreshes
+```
+
+**Qwen — DashScope API key** (Alibaba Model Studio, OpenAI-compatible)
+```bash
+hara config set provider qwen
+hara config set apiKey   sk-...      # your DashScope model-studio key
+hara config set model    qwen-plus   # or qwen-max, qwen3-coder-plus, …
+# endpoint defaults to dashscope compatible-mode/v1
+#
+# coding-plan keys (sk-sp-…) use the coding endpoint instead:
+#   hara config set baseURL https://coding.dashscope.aliyuncs.com/v1
+#   hara config set model   qwen3.7-plus
+#   plan models: qwen3.7-plus, qwen3.6-plus, qwen3-coder-plus, qwen3-coder-next,
+#                qwen3-max-2026-01-23, glm-5, glm-4.7  (switch with -m or /model)
+```
+
+> Plan keys (Coding Plan / Token Plan) are licensed **only** for use inside AI coding agents /
+> OpenClaw-type tools like hara — not Dify/n8n, API-testing tools, or direct script/backend calls.
 
-Licensed under either of **MIT** ([LICENSE-MIT](LICENSE-MIT)) or **Apache-2.0**
-([LICENSE-APACHE](LICENSE-APACHE)) at your option.
+**Any OpenAI-compatible endpoint** (GLM, Kimi, OpenAI, local servers)
+```bash
+hara config set provider openai
+hara config set baseURL  https://your-endpoint/v1
+hara config set apiKey   ...
+hara config set model    ...
+```
+
+**Vision** — hara **auto-detects** whether your main model can see images. A vision model (Claude, gpt-4o,
+qwen-vl, glm-4v…) gets pasted images **inline**. For a **text-only** model (DeepSeek, coding models), set a
+describer — the "eyes" — and hara OCRs/describes each pasted image into text first:
+```bash
+hara config set visionModel qwen-vl-max   # a vision model on the same plan/key
+# point it elsewhere if your endpoint doesn't serve vision:
+#   hara config set visionBaseURL https://dashscope.aliyuncs.com/compatible-mode/v1
+#   hara config set visionApiKey  sk-...
+```
+If a model's capability is unknown, hara **asks once and remembers**. In the TUI, `/vision <model>` sets the
+describer and `/vision main yes|no|auto` corrects a model's detected capability.
+
+Config lives in `~/.hara/config.json`. Env vars override it: `HARA_PROVIDER`, `HARA_MODEL`,
+`HARA_BASE_URL`, `HARA_API_KEY`, or the provider key (`ANTHROPIC_API_KEY` / `DASHSCOPE_API_KEY`).
+
+## Use
+
+```bash
+hara                       # interactive REPL (offers to create AGENTS.md on first run)
+hara init                  # analyze the project & (re)generate AGENTS.md
+hara doctor                # check your setup (auth / model / node / assets / roles)
+hara roles init            # scaffold role-agents (implementer / reviewer / docs)
+hara org "review src/ for bugs"   # dispatch a task to the role that owns it (or --role <id>)
+hara plan "add a /health endpoint with a test"   # decompose → sequence (DAG) → run each step + verify
+hara -p "summarize @README.md and fix the lint errors in src/"   # one-shot; @path attaches a file
+hara --approval auto-edit  # suggest (default) | auto-edit | full-auto   (-y = full-auto)
+hara --sandbox workspace-write   # confine shell writes to the project (macOS Seatbelt)
+hara -c                    # resume the most recent session in this directory
+hara --profile work        # use a named profile from ~/.hara/config.json
+hara -m glm-5              # pick a model
+```
+
+Inside the REPL: `/help` `/init` `/tools` `/model` `/approval` `/org` `/plan` `/roles` `/usage` `/doctor` `/sessions` `/undo` `/compact` `/recall` `/reset` `/exit` (type `/`+Tab to complete). Type `@` + Tab to attach a file (fuzzy, walks subdirectories).
+
+The interactive REPL is an **ink TUI**: a bordered **input box pinned at the bottom** — session name in
+the top-right corner, approval modes + token usage + concurrency in the bottom border — with the
+conversation scrolling above it. Streaming text, reasoning, tool calls, and colored diffs render as live
+blocks; a spinner runs during a turn. **shift+tab** cycles the approval mode, **Esc** interrupts a running
+turn, and tool approvals appear inline (y/N). **Ctrl+V** pastes an image from your clipboard (a screenshot,
+or a copied image) — or drag an image file into the terminal — and it appears as a highlighted `[Image #N]`
+token inline where your cursor is (backspace over it to remove it). hara auto-detects the model's capability —
+a vision model sees the image directly; a text-only model routes it through a `visionModel` describer (see
+Setup), shown in the header at startup. Set `HARA_TUI=0` for the classic readline REPL.
+
+Each session gets a **UUID** and an **auto-summarized name** from your first message (kept verbatim, CJK
+included); `hara sessions` lists them by short id, and `--resume <prefix>` accepts the short id.
+
+Assistant output is **rendered as Markdown** (headers, bold, inline code, lists; code fences verbatim),
+and a model's **reasoning** shows dimmed before the answer when available. Both are interactive-terminal
+only; `HARA_MD=0` disables Markdown rendering.
+
+**Skills** — reusable capabilities on the **agentskills.io standard** (`SKILL.md`, interoperable with Claude
+Code / codex / openclaw). Drop a `~/.hara/skills/<name>/SKILL.md` (or project `.hara/skills/`) with `name` +
+`description` frontmatter and Markdown instructions; the agent sees the list and calls the `skill` tool to load
+a skill's full body only when it's relevant (progressive disclosure). `hara skills init` scaffolds one, `hara
+skills` lists them, `/skill <id>` loads one into your next message, and the agent saves its own with
+`skill_create` (`scope: project|personal`). Optional frontmatter: `when_to_use`, `allowed-tools`, `context: fork` (run as a sub-agent), `paths`.
+When the agent saves a skill, secrets are **redacted** and local paths/emails **generalized** (`<project>` / `~` / `<email>`),
+and a near-duplicate is flagged so it updates instead of piling up. `assetCapture: off|ask|auto` controls proactive end-of-session capture.
+
+**Plugins** — bundle skills + roles + MCP servers in one installable unit (Claude-Code-compatible
+`plugin.json` / `.claude-plugin/`). `hara plugin add file:<path> | github:<owner/repo> | git:<url>` installs it;
+`hara plugin` lists; `enable`/`disable`/`remove`. A plugin's skills/roles/MCP auto-contribute (your project &
+global override them). `.claude/agents/*.md` subagents load as roles too.
+
+**Recall** — `hara recall --init` creates a personal `~/.hara/code-assets` library (snippets as `*.md`);
+`hara recall "<query>"` searches it **plus your skills** (one corpus), and `/recall <query>` pulls the best
+matches into your next message. A git-versionable library of code/patterns you want to reuse (`HARA_ASSETS` overrides the path).
+
+**Semantic search** (opt-in) — `codebase_search`, `recall`, and `memory_search` can find things by *meaning*,
+not just keywords. By default they're lexical (zero setup). Configure an embedding provider, then build an index:
+`hara config set embedProvider ollama` (local & offline, e.g. `bge-m3`/`nomic-embed-text`) or `qwen` (DashScope),
+then `hara index` (repo, for `codebase_search`) / `hara index --assets` (code-assets, skills & memory) / `hara
+index --all`. A query like "read an image pasted from the clipboard" then surfaces `src/images.ts` even with no
+shared words. Indexes are rebuildable `.hara/index/` artifacts (self-`.gitignore`d, never committed); no native
+vector DB needed, and lexical still works when there's no index.
+
+**Approval modes**: `suggest` confirms edits & shell · `auto-edit` auto-applies file edits but confirms shell · `full-auto` runs everything.
+**Sandbox** (macOS): `--sandbox workspace-write|read-only` runs the `bash` tool under Seatbelt (writes confined to the project / blocked).
+**Screen control** (opt-in): the `computer` tool drives desktop software (screenshot → click/type), native per OS
+(mac `screencapture`+`cliclick` · Windows PowerShell · Linux `scrot`+`xdotool`). Off by default — enable a tier with
+`hara config set computerUse read|click|full` and allowlist apps with `hara config set computerApps "App, …"`. Guarded
+by the tier, the frontmost-app allowlist, a dangerous-key blocklist, and a once-per-session grant; screenshots are read via your vision model.
+**Sessions**: conversations are saved automatically — `-c` / `--resume <id>` to continue, `hara sessions` to list.
+**MCP**: add an `mcpServers` map to config (global or project `.hara/config.json`); their tools appear to the agent as `mcp__<server>__<tool>`.
+**Profiles**: add a `profiles` map to `~/.hara/config.json` (`--profile <name>`), or drop a project-level `.hara/config.json` that overrides the global config.
+
+### The org — what makes hara different
+
+Define role-agents in `.hara/roles/*.md` — each is a persona (the file body) plus frontmatter: `owns`
+(keywords that route a task here), optional `rejects`, `model`, and `allowTools`/`denyTools`. `hara org
+"<task>"` routes the task to the role that **owns** it (keyword match, LLM fallback) and runs that role's
+agent — e.g. a read-only `reviewer` that reports issues vs an `implementer` that edits code. `hara roles`
+lists them, `hara roles init` scaffolds a starter set, and `--role <id>` forces a specific role. The
+**`agent`** tool spawns **parallel read-only sub-agents** for fan-out — analyze / review / search
+several things at once (each can take a `role`).
+
+Beyond routing, **`hara plan "<task>"`** makes the org *plan*: it decomposes the task into atoms,
+sequences them as a DAG, and executes each step (optionally routed to a role) behind a per-step
+**verify gate** — frame → atomize → sequence → execute → verify. Each atom may carry a `check` shell
+command, so verification is **objective** (e.g. `npm test`, `tsc --noEmit`) rather than a
+self-assessment. Plan state is the SSOT at `.hara/org/plan.json` (inspectable; execution stops on the
+first failed verification).
+
+### What it can do
+
+A streaming agentic loop with built-in tools — `read_file`, `write_file`, **`edit_file`** /
+**`apply_patch`** (surgical edits — single file, or **atomic multi-file** changes), `bash`, and
+read-only **`grep`** / **`glob`** / **`ls`** / **`web_fetch`** — behind a human-in-the-loop confirmation gate on the
+dangerous ones unless `-y`. Read-only tools run in parallel within a turn, and edits print a
+**colored diff** of what changed. Shell output streams live; press **Esc** to interrupt a running
+turn, or **`/undo`** to revert the last edit.
+- **Project context**: auto-loads `AGENTS.md` (the cross-tool standard) walking up to the repo root; `hara init` writes one by analyzing the repo.
+- **`@file` mentions**: attach file contents to a message (`@path`); Tab-completes with a **fuzzy** matcher over the project (subdirs, git-tracked + untracked) — `@idx` → `src/index.ts`. `@<dir>` loads a directory listing, `@src/`+Tab drills into a folder, and mistyped tool/file paths get a "did you mean" suggestion.
+- **Multi-provider**: Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) — **all streamed live**.
+
+### Roadmap
+
+**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel sub-agents · `/compact` context management.
+**Next:** parallel plan atoms · multi-role review chains · cron autonomy for the org · single-binary distribution · an enterprise control-plane (fleet + central token management).
+
+## License
 
-Contributions are accepted under these terms; see [CLA.md](CLA.md).
+Licensed under the **Apache License 2.0** ([LICENSE](LICENSE)) — a permissive license with an
+explicit patent grant. Contributions per [CLA.md](CLA.md).
 
 © 2026 Nanhara

package/dist/activity.js

@@ -0,0 +1,30 @@
+// Live concurrency signal — how many tool/subagent operations are in flight right now.
+// The status bar subscribes to render the "⛁ N" indicator; the agent loop inc/dec around
+// parallel tool execution (and, later, spawned subagents).
+let running = 0;
+let peak = 0;
+let listener = null;
+export const activity = {
+    get running() {
+        return running;
+    },
+    get peak() {
+        return peak;
+    },
+    inc() {
+        running++;
+        if (running > peak)
+            peak = running;
+        listener?.();
+    },
+    dec() {
+        running = Math.max(0, running - 1);
+        listener?.();
+    },
+    resetPeak() {
+        peak = running;
+    },
+    onChange(fn) {
+        listener = fn;
+    },
+};

package/dist/agent/loop.js

@@ -0,0 +1,184 @@
+import { getTool, toolSpecs } from "../tools/registry.js";
+import { stdout } from "node:process";
+import { c, out } from "../ui.js";
+import { activity } from "../activity.js";
+import { makeRenderer } from "../md.js";
+import { skillsDigest } from "../skills/skills.js";
+/** Whether a tool call needs user confirmation under the given approval mode. */
+export function needsConfirm(kind, mode) {
+    if (kind === "read")
+        return false;
+    if (kind === "computer")
+        return true; // screen control always needs a session grant (even full-auto)
+    if (mode === "full-auto")
+        return false;
+    if (mode === "auto-edit")
+        return kind === "exec";
+    return true; // suggest: confirm edits and exec
+}
+const HARA_SYSTEM = (cwd) => `You are hara, a coding agent running in the user's terminal.
+Working directory: ${cwd}
+Be concise and direct. Use the provided tools to read files, edit/write files, and run shell
+commands. Prefer small, verifiable steps; edit existing files with edit_file rather than rewriting
+them whole. You have a persistent memory: use memory_search before answering about prior decisions,
+conventions, or the user's preferences, and memory_write to proactively save durable facts you learn.
+When a task matches one of the Skills listed below, call the \`skill\` tool to load its full instructions
+before acting; save a reusable how-to as a new skill with skill_create. If you discover a durable project
+convention, you may propose an edit to AGENTS.md via edit_file (the user reviews the diff). After completing
+a task, give a one-line summary.`;
+function composeSystem(cwd, projectContext, override, memory) {
+    const head = override ? `${override}\n\nWorking directory: ${cwd}` : HARA_SYSTEM(cwd);
+    const skills = skillsDigest(cwd);
+    return (head +
+        (projectContext ? `\n\n# Project context (AGENTS.md)\n${projectContext}` : "") +
+        (memory ? `\n\n# Memory (durable — facts/decisions/prefs you've saved; use memory_search/get for more)\n${memory}` : "") +
+        (skills ? `\n\n# Skills (capabilities you can load — call the \`skill\` tool with the id for full instructions before using one)\n${skills}` : ""));
+}
+/** Provider-agnostic agentic loop. Mutates `history` in place. */
+export async function runAgent(history, opts) {
+    const { provider, ctx } = opts;
+    for (;;) {
+        const specs = opts.toolFilter ? toolSpecs().filter((t) => opts.toolFilter(t.name)) : toolSpecs();
+        const sink = ctx.ui; // TUI mode: route output to ink instead of stdout
+        const tty = stdout.isTTY && !opts.quiet && !sink;
+        const md = tty && process.env.HARA_MD !== "0" ? makeRenderer(out) : null;
+        let sawReasoning = false;
+        // "working Ns" spinner until the first output arrives (cleared on text/reasoning or turn end)
+        let spin = null;
+        const stopSpin = () => {
+            if (spin) {
+                clearInterval(spin);
+                spin = null;
+                out("\r\x1b[K");
+            }
+        };
+        if (tty) {
+            const frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏";
+            const t0 = Date.now();
+            let fi = 0;
+            spin = setInterval(() => out(`\r${c.dim(`${frames[fi++ % frames.length]} working ${Math.floor((Date.now() - t0) / 1000)}s`)}`), 100);
+        }
+        const r = await provider.turn({
+            system: composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory),
+            history,
+            tools: specs,
+            onText: (d) => {
+                if (opts.quiet)
+                    return;
+                if (sink) {
+                    sink.text(d);
+                    return;
+                }
+                stopSpin();
+                if (sawReasoning) {
+                    out("\n");
+                    sawReasoning = false;
+                }
+                if (md)
+                    md.push(d);
+                else
+                    out(d);
+            },
+            onReasoning: sink || tty
+                ? (d) => {
+                    if (opts.quiet)
+                        return;
+                    if (sink) {
+                        sink.reasoning(d);
+                        return;
+                    }
+                    stopSpin();
+                    sawReasoning = true;
+                    out(c.dim(d));
+                }
+                : undefined,
+            signal: opts.signal,
+        });
+        stopSpin();
+        md?.end();
+        if (!opts.quiet && !sink)
+            out("\n");
+        if (r.usage && opts.stats) {
+            opts.stats.input += r.usage.input;
+            opts.stats.output += r.usage.output;
+            opts.stats.lastInput = r.usage.input;
+        }
+        history.push({ role: "assistant", text: r.text, toolUses: r.toolUses });
+        if (r.stop === "error") {
+            const msg = r.errorMsg === "interrupted" ? "(interrupted)" : `[${provider.id} error] ${r.errorMsg ?? "unknown"}`;
+            if (!opts.quiet) {
+                if (sink)
+                    sink.notice(msg);
+                else
+                    out(r.errorMsg === "interrupted" ? c.dim(`\n${msg}\n`) : c.red(`${msg}\n`));
+            }
+            return;
+        }
+        if (r.stop !== "tool_use")
+            return;
+        const plans = [];
+        for (const tu of r.toolUses) {
+            const tool = getTool(tu.name);
+            if (!tool) {
+                plans.push({ tu, tool: undefined, denied: `Unknown tool: ${tu.name}` });
+                continue;
+            }
+            const input = tu.input;
+            const preview = String(input.path ?? input.command ?? input.pattern ?? input.url ?? input.task ?? "")
+                .replace(/\s+/g, " ")
+                .trim();
+            if (needsConfirm(tool.kind, opts.approval) && !opts.autoApprove?.has(tu.name)) {
+                const reply = await opts.confirm(`${c.yellow("⚠")}  ${c.bold(tu.name)} ${c.dim(preview)} — run?`);
+                if (reply === false) {
+                    plans.push({ tu, tool, denied: "User denied this action." });
+                    continue;
+                }
+                if (reply === "always")
+                    opts.autoApprove?.add(tu.name);
+            }
+            plans.push({ tu, tool });
+            if (!opts.quiet) {
+                const pv = preview ? preview.slice(0, 80) : "";
+                if (sink)
+                    sink.tool(tu.name, pv);
+                else
+                    out(c.dim(`  ↳ ${tu.name}${pv ? " " + pv : ""}\n`));
+            }
+        }
+        // Execute: read-only tools run concurrently; edit/exec run alone, in order.
+        const results = new Array(plans.length);
+        const runOne = async (idx, p) => {
+            if (p.denied !== undefined) {
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: p.denied, isError: true };
+                return;
+            }
+            activity.inc();
+            try {
+                const res = await p.tool.run(p.tu.input, ctx);
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: res };
+            }
+            catch (e) {
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: `Error: ${e.message}`, isError: true };
+            }
+            finally {
+                activity.dec();
+            }
+        };
+        let batch = [];
+        for (let i = 0; i < plans.length; i++) {
+            const p = plans[i];
+            if (p.denied === undefined && p.tool?.kind === "read") {
+                batch.push(runOne(i, p)); // safe → accumulate to run concurrently
+            }
+            else {
+                if (batch.length) {
+                    await Promise.all(batch); // flush pending reads before an edit/exec
+                    batch = [];
+                }
+                await runOne(i, p);
+            }
+        }
+        await Promise.all(batch);
+        history.push({ role: "tool", results });
+    }
+}

package/dist/config.js

@@ -0,0 +1,114 @@
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+const PROVIDER_DEFAULTS = {
+    anthropic: { model: "claude-opus-4-8", envKey: "ANTHROPIC_API_KEY" },
+    qwen: {
+        model: "qwen-plus",
+        baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        envKey: "DASHSCOPE_API_KEY",
+    },
+    "qwen-oauth": { model: "coder-model", envKey: "QWEN_OAUTH_TOKEN" },
+    openai: { model: "gpt-4o-mini", envKey: "OPENAI_API_KEY" },
+};
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey"];
+export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
+export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
+const PROJECT_ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
+export function configPath() {
+    return join(homedir(), ".hara", "config.json");
+}
+export function readRawConfig() {
+    const p = configPath();
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Nearest project override `.hara/config.json`, searching cwd up to the repo root. */
+function readProjectConfig(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const p = join(dir, ".hara", "config.json");
+        if (existsSync(p)) {
+            try {
+                return JSON.parse(readFileSync(p, "utf8"));
+            }
+            catch {
+                return {};
+            }
+        }
+        if (PROJECT_ROOT_MARKERS.some((m) => existsSync(join(dir, m))))
+            break; // stop at repo root
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return {};
+}
+export function writeConfigValue(key, value) {
+    const p = configPath();
+    const cfg = readRawConfig();
+    cfg[key] = value;
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+/** Record (or clear, with cap=null) a confirmed per-model vision capability in `modelVision`. */
+export function setModelVisionOverride(model, cap) {
+    const p = configPath();
+    const cfg = readRawConfig();
+    const map = cfg.modelVision && typeof cfg.modelVision === "object" ? cfg.modelVision : {};
+    if (cap === null)
+        delete map[model];
+    else
+        map[model] = cap;
+    cfg.modelVision = map;
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+/**
+ * Effective config. Precedence (high→low): env vars > selected profile >
+ * project `.hara/config.json` > global `~/.hara/config.json` > provider defaults.
+ */
+export function loadConfig(opts = {}) {
+    const global = readRawConfig();
+    const { profiles, ...globalBase } = global;
+    const project = readProjectConfig(process.cwd());
+    const profileName = process.env.HARA_PROFILE ?? opts.profile;
+    const profile = profileName && profiles && profiles[profileName] ? profiles[profileName] : {};
+    const merged = { ...globalBase, ...project, ...profile };
+    const provider = (process.env.HARA_PROVIDER ?? merged.provider ?? "anthropic");
+    const d = PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic;
+    const model = process.env.HARA_MODEL ?? merged.model ?? d.model;
+    const baseURL = process.env.HARA_BASE_URL ?? merged.baseURL ?? d.baseURL;
+    const apiKey = process.env.HARA_API_KEY ?? process.env[d.envKey] ?? merged.apiKey;
+    const approval = (process.env.HARA_APPROVAL ?? merged.approval ?? "suggest");
+    const sandbox = (process.env.HARA_SANDBOX ?? merged.sandbox ?? "off");
+    const theme = (process.env.HARA_THEME ?? merged.theme ?? "dark");
+    const evolve = (process.env.HARA_EVOLVE ?? merged.evolve ?? "proactive");
+    const assetCapture = (process.env.HARA_ASSET_CAPTURE ?? merged.assetCapture ?? "ask");
+    const computerUse = (process.env.HARA_COMPUTER_USE ?? merged.computerUse ?? "off");
+    const computerApps = String(process.env.HARA_COMPUTER_APPS ?? merged.computerApps ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const visionModel = process.env.HARA_VISION_MODEL ?? merged.visionModel;
+    const visionBaseURL = process.env.HARA_VISION_BASE_URL ?? merged.visionBaseURL;
+    const visionApiKey = process.env.HARA_VISION_API_KEY ?? merged.visionApiKey;
+    const modelVision = merged.modelVision && typeof merged.modelVision === "object" ? merged.modelVision : {};
+    const embedProvider = (process.env.HARA_EMBED_PROVIDER ?? merged.embedProvider ?? "off");
+    const embedModel = process.env.HARA_EMBED_MODEL ?? merged.embedModel;
+    const embedBaseURL = process.env.HARA_EMBED_BASE_URL ?? merged.embedBaseURL;
+    const embedApiKey = process.env.HARA_EMBED_API_KEY ?? merged.embedApiKey;
+    const mcpServers = {
+        ...(globalBase.mcpServers ?? {}),
+        ...(project.mcpServers ?? {}),
+        ...(profile.mcpServers ?? {}),
+    };
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, mcpServers, cwd: process.cwd() };
+}
+export function providerEnvKey(provider) {
+    return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;
+}

package/dist/context/agents-md.js

@@ -0,0 +1,64 @@
+// Project-context loading (AGENTS.md) — the cross-tool standard read by Codex/Claude Code/OpenClaw.
+// Walks up from cwd to the project root, concatenates AGENTS.md files, caps total size.
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+const FILENAMES = ["AGENTS.override.md", "AGENTS.md"];
+const ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
+const MAX_BYTES = 32 * 1024;
+export function findProjectRoot(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        if (ROOT_MARKERS.some((m) => existsSync(join(dir, m))))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return resolve(cwd); // no marker found → treat cwd as root
+        dir = parent;
+    }
+}
+/** Concatenate AGENTS.md files from project root down to cwd (root first), capped at 32 KiB. */
+export function loadAgentsMd(cwd) {
+    const root = findProjectRoot(cwd);
+    const chain = [];
+    let dir = resolve(cwd);
+    for (;;) {
+        chain.unshift(dir);
+        if (dir === root)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const parts = [];
+    for (const d of chain) {
+        for (const name of FILENAMES) {
+            const p = join(d, name);
+            if (existsSync(p)) {
+                try {
+                    const txt = readFileSync(p, "utf8").trim();
+                    if (txt)
+                        parts.push(`<!-- ${name} @ ${d} -->\n${txt}`);
+                }
+                catch {
+                    /* ignore unreadable */
+                }
+            }
+        }
+    }
+    let combined = parts.join("\n\n--- project-doc ---\n\n");
+    if (Buffer.byteLength(combined, "utf8") > MAX_BYTES) {
+        combined = Buffer.from(combined, "utf8").subarray(0, MAX_BYTES).toString("utf8") + "\n…[truncated]";
+    }
+    return combined;
+}
+export function hasAgentsMd(cwd) {
+    const root = findProjectRoot(cwd);
+    return FILENAMES.some((n) => existsSync(join(root, n)));
+}
+/** Prompt hara runs against itself to analyze the repo and write AGENTS.md. */
+export const INIT_PROMPT = "Explore this repository to understand it, then write a concise AGENTS.md at the project root.\n" +
+    "Use read_file, bash (e.g. `ls`, `git ls-files`, `cat`), and write_file.\n" +
+    "AGENTS.md should cover: what the project is (1-2 sentences), the directory structure, key commands " +
+    "(build / test / run / lint), and important conventions. Keep it under ~150 lines.\n" +
+    "Create it with write_file at path 'AGENTS.md', then reply with a one-line confirmation.";