@nanhara/hara 0.0.1 → 0.33.0

package/LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2026 Nanhara
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Nanhara
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -6,16 +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
 ```
 
-MIT © Nanhara
+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.
+
+**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
+
+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 });
+    }
+}