@nanhara/hara 0.125.1 → 0.126.0

package/CHANGELOG.md

@@ -5,6 +5,82 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.126.0 — 2026-07-19 — provider control plane, bounded tools, and honest execution time
+
+- **Desktop can configure providers through an authenticated, redacted Serve control plane.** The shared
+  catalog distinguishes cloud, local, OAuth, and managed routes; settings can list, test, and save a Personal
+  route without returning credentials to the UI. Switching provider or endpoint requires a matching new key
+  instead of replaying another vendor's credential, named/managed profiles remain explicit, and launch-time
+  environment overrides stay immutable from Desktop.
+- **Ollama and LM Studio are first-class local providers.** They require no fake API key, accept only
+  loopback HTTP endpoints, omit the Authorization header on the wire, and can discover installed models
+  through the same bounded connection-test path. Cloud custom endpoints continue to require HTTPS except
+  for an explicit loopback target.
+- **Tool execution has conservative runtime traits.** Tools without a complete declaration default to
+  side-effect-capable and serial; input-level classification can narrow a real read but cannot turn a
+  mutating call into an inherited read approval. Parallel calls share an aggregate result budget so one
+  round cannot flood the next model request.
+- **Long-tail tool schemas and large results are demand-loaded.** `tool_search` activates only matched,
+  role-allowed capabilities for the next model round. Oversized, redacted tool output is kept in a
+  quota/TTL-bounded private store and exposed only through opaque `tool_result_read` continuation IDs, never
+  arbitrary filesystem paths.
+
+- Human clarification and approval waits no longer consume `runTimeoutMs`. The non-renewable budget now
+  measures active model/tool execution, resumes with the exact remaining time after an answer, and still
+  stops genuinely stuck providers, tools, and loops. Esc, shutdown, and explicit cancellation continue to
+  dismiss a waiting prompt immediately.
+- The TUI distinguishes this state as `waiting for your answer · task timer paused`; five-minute and 80%
+  lifecycle notices no longer fire while Hara is waiting for a person.
+- `hara serve` now exposes authenticated `server.shutdown` so Desktop can gracefully release sessions and
+  locks before relaunching after an update.
+- Timed-out or interrupted provider/tool calls retain their Serve session lease until the underlying
+  operation physically settles. A second turn, session deletion, or updater shutdown receives `BUSY`
+  instead of overlapping a non-cooperative request or releasing its lock early.
+- Headless resumed sessions use the same physical-lifetime rule for dynamically nested sub-agents and
+  automatic compaction, so a late child request cannot escape a cleanup snapshot and release the
+  cross-process lock early.
+- The WeCom gateway now uses the bundled `ws` transport because Node 22's native WebSocket handshake is
+  rejected by WeCom's production endpoint before authentication. A late authentication frame can no longer
+  revive an already-aborted connection or install a heartbeat after cleanup.
+- Upgrade with `npm i -g @nanhara/hara@0.126.0`.
+
+## 0.125.3 — 2026-07-18 — conversation/task boundary and deliberate execution
+
+- **Chat delivery is now separate from task execution.** Slash controls such as `/model` no longer create a
+  fake steer target; input typed while a picker or other local control is busy is visibly queued as the next
+  turn. If a real turn ends between enqueue and delivery, Hara promotes the raced steer to a normal turn
+  instead of rejecting it with `there is no task to steer` or dropping the input. Queued controls execute
+  alone rather than absorbing the following task as command arguments, and paused/completed tasks are never
+  implicit steer targets—only explicit `/continue` may reopen one. User-invocable slash Skills remain real
+  Agent turns, so refinements typed while `/design`, `/video`, or another Skill is running steer that Skill
+  instead of becoming an unrelated task.
+- **Main tasks now establish an explicit understanding checkpoint before side effects.** The engine-owned
+  `task_intake` records intent, interpreted goal, constraints, acceptance checks, and short steps in the
+  durable task state. Reads and diagnosis may happen first, but edits, non-read-only commands, computer
+  actions, external agents, and MCP connections are blocked until the brief is accepted in a completed tool
+  round. Starting or stopping a background process is also treated as a state change even when its command or
+  job tool is otherwise read-only; malformed string-valued `background` flags are rejected. Read-only actions
+  inside mixed tools (`task list`, `cronjob list`) stay available for evidence gathering. Brief revisions
+  replace the old prompt copy and cannot share a round with a side effect. A later steer cannot be overwritten
+  by a concurrent or revised checkpoint.
+- **Alibaba Coding Plan discovery follows the current exact model contract.** `/model` prefers the endpoint's
+  live response and uses the documented ten-model list only for official Coding Plan hosts. Context guards now
+  use each model's published window, and `qwen3-coder-next` / `qwen3-coder-plus` no longer expose an unsupported
+  thinking control. Desktop/serve derives the reasoning dial from each session's pinned model rather than the
+  current global default.
+- **Configured MCP servers no longer execute or ask for permission when Hara starts.** Hara exposes a
+  zero-side-effect `mcp_connect` capability; the agent calls it only when the current task materially needs
+  one named server, receives the existing external-boundary approval, and discovers that server's tools for
+  the next model round. Other configured servers remain stopped.
+- Interactive calls to connected MCP tools still require confirmation every time, protected-file-shaped
+  inputs remain blocked, read-only roles cannot receive the launcher, and headless runs remain fail-closed
+  unless `HARA_ALLOW_TRUSTED_EXTENSIONS=1` was set before launch.
+- MCP stderr now drops only npm 11's repeated `Unknown user config "always-auth"` and `"home"` deprecation
+  lines. Other npm warnings and all actual server errors remain visible and redacted. Hara does not read,
+  rewrite, or weaken the user's `.npmrc`. Esc, interruption, and the active-execution deadline now also cancel a
+  lazy MCP startup/tool call and close an unresponsive child instead of leaving it behind.
+- Upgrade with `npm i -g @nanhara/hara@0.125.3`.
+
 ## 0.125.1 — 2026-07-18 — installed plugin commands inside agent tasks
 
 - **Commands contributed by an installed Hara plugin are now available to Hara's own tool subprocesses.**

package/README.md

@@ -109,8 +109,11 @@ hara config set model    qwen-plus   # or qwen-max, qwen3-coder-plus, …
 # 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)
+#   supported exact ids (2026-07-18):
+#     qwen3.7-plus, qwen3.6-plus, qwen3.5-plus, qwen3-max-2026-01-23,
+#     qwen3-coder-next, qwen3-coder-plus, kimi-k2.5, glm-5, glm-4.7,
+#     MiniMax-M2.5
+#   /model uses the endpoint's live list first and this official list only as a fallback.
 ```
 
 > Plan keys (Coding Plan / Token Plan) are licensed **only** for use inside AI coding agents /
@@ -266,7 +269,7 @@ Type-ahead Enter steers the exact live turn; `/next <message>` queues a separate
 clients use `session.steer` with `expectedTurnId` (durable before ACK) and may pass `newTask: true` to force a
 new execution. The `hara resume` launcher preserves terminal input in both npm/Node and standalone-binary
 installs.
-**MCP**: add an `mcpServers` map to global config (a reviewed project config additionally needs `HARA_TRUST_PROJECT_CONFIG=1` at launch); their tools appear to the agent as `mcp__<server>__<tool>`. Configured MCP servers, like `external_agent`, are trusted host extensions outside Hara's protected-file boundary. Every interactive tool call requires confirmation (even in `full-auto`), and non-interactive runs disable them by default; reviewed automation can explicitly opt in before launch with `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. hara can also **be** an MCP server — `hara mcp` exposes its read/search tools (esp. **`codebase_search`**) over stdio so other clients (Claude Desktop, Cursor, another hara) can use them; read-only by default (`HARA_MCP_TOOLS` to override).
+**MCP**: add an `mcpServers` map to global config (a reviewed project config additionally needs `HARA_TRUST_PROJECT_CONFIG=1` at launch). Hara starts with every configured server stopped and exposes only `mcp_connect`; when the current task first needs one server, the agent requests permission to connect that server and its tools appear on the next round as `mcp__<server>__<tool>`. Unrelated servers remain stopped. Configured MCP servers, like `external_agent`, are trusted host extensions outside Hara's protected-file boundary. Every interactive external-tool call requires confirmation (even in `full-auto`), and non-interactive runs disable them by default; reviewed automation can explicitly opt in before launch with `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. hara can also **be** an MCP server — `hara mcp` exposes its read/search tools (esp. **`codebase_search`**) over stdio so other clients (Claude Desktop, Cursor, another hara) can use them; read-only by default (`HARA_MCP_TOOLS` to override).
 **Vim mode**: `hara config set vimMode true` makes the prompt modal — Esc → normal, `i/a/A/I` insert, `h l 0 $ w b e` motions, `x D C dd cw p` edits. Off by default.
 **Scheduled tasks**: `hara cron add "0 9 * * 1-5" "<task>"` (or `"every 30m"`, `"in 2h"`) runs a task on a schedule — each run is a fresh hara session. `hara cron install` wires a per-minute tick into launchd/crontab (no daemon); `--org` routes through the role org. Manage with `hara cron list/run/enable/disable/remove/logs`. Every job has a 30-minute deadline and the whole sequential tick has a non-renewable 60-minute watchdog: a job timeout kills its process tree, records `timed out` + duration/error, then continues with the next due job; a tick timeout stops the remainder and releases the global lock. Add `--deliver feishu:<chatId>` (or Telegram/webhook) for outcomes and `--alert-after N` for the consecutive-failure 🚨 threshold (default 3). Delivery intent is durable before transport, uses a stable idempotency key, and retries with bounded backoff on later ticks until confirmed. A failed channel cannot grow `jobs.json` forever: each job keeps at most 64 pending effects, reserves outcome/alert room before launch, and disables itself with a visible backlog error when full; restore delivery, let the queue drain, then re-enable it. Tune milliseconds with `HARA_CRON_JOB_TIMEOUT_MS` (hard max 24h) and `HARA_CRON_TICK_TIMEOUT_MS` (hard max 5h); scheduled jobs are also capped by the tick. After upgrading from a version whose tick is already stuck, terminate that specific legacy `hara cron tick` process tree once (or reboot); the next scheduler minute marks over-age state interrupted/disabled and recovers the lock without replaying a possibly orphaned task.
 **Work coordination**: `todo_write` is the agent's short, session-scoped checklist; it persists with that
@@ -274,10 +277,21 @@ session and is isolated between simultaneous sub-agents and serve sessions. `tas
 for work that outlives a conversation: add/update/list/remove items with `pending|in_progress|done`, an optional
 owner, and `blockedBy` dependencies. The private, atomic store is shared by concurrent hara processes for the
 same project and rejects missing/self/cyclic dependencies.
+**Conversation and execution**: the composer first routes an input as a local control, a new task, a steer of
+the exact live task, or an explicit next task. User-invocable slash Skills are executable turns and accept
+live steering; local controls such as `/model` are serialized without pretending to own a task. A main task keeps the raw user request and a separate accepted
+brief (intent, interpreted goal, constraints, acceptance checks, and steps). Hara permits read-only
+investigation before that brief, but its engine blocks side effects until the understanding has been
+checkpointed in its own model/tool round. Mixed tools are classified by action (`task list` is a read), and
+a brief revision cannot share its round with a side effect. `/task` shows the current execution identity and brief. See
+[`docs/conversation-task-execution.md`](docs/conversation-task-execution.md).
 **Notifications**: `hara config set notify bell` (terminal bell) or `notify system` (OS notification) pings you when a turn finishes — handy for long runs you've stepped away from. Gated on elapsed time so quick turns stay quiet; off by default.
-**Run limits and loop alarms**: every agent turn has a non-renewable 30-minute total deadline and a 64-round
-model/tool cap. Hara warns after five minutes or at 75% of the round budget, stops the third identical failing
-tool call, and surfaces the final reason in CLI, Desktop, or gateway output. Tune intentional long work with
+**Run limits and loop alarms**: every agent turn has a non-renewable 30-minute active-execution budget and a
+64-round model/tool cap. Time spent waiting for an engine-owned question or approval does not consume that
+budget; the status row says the task timer is paused, while Esc, shutdown, and explicit cancellation still
+take effect immediately. Answering resumes the remaining budget rather than resetting it. Hara warns after
+five active minutes or at 75% of the round budget, stops the third identical failing tool call, and surfaces
+the final reason in CLI, Desktop, or gateway output. Tune intentional long work with
 `hara config set runTimeoutMs 45m` (1s..2h) and `hara config set maxAgentRounds 96` (1..256), or
 `HARA_RUN_TIMEOUT_MS` / `HARA_MAX_AGENT_ROUNDS`; neither boundary can be disabled. Sub-agents are capped at
 8 minutes/24 rounds and inherit the parent's cancellation. Auxiliary model work (planning, verification,
@@ -286,8 +300,8 @@ provider that ignores cancellation cannot strand the CLI outside the main loop.
 **Hooks**: run your own shell commands around tool calls via a `"hooks"` map in global config; hooks from a reviewed project config require the launch-time `HARA_TRUST_PROJECT_CONFIG=1` opt-in. A **`PreToolUse`** hook can **veto** a call (non-zero exit blocks it; its output becomes the reason the model sees) — gate `bash`, forbid edits outside a path, require a clean tree. A **`PostToolUse`** hook observes (format/lint a file the agent just wrote, log, notify). Each has a `matcher` (regex/literal on the tool name, `*` = all) and gets `{tool, payload}` on stdin + `HARA_TOOL_NAME` in env. Plugins can contribute hooks too.
 Reviewer/read-only/plan runs and parallel read-only sub-agents suppress both hook phases: PreToolUse and
 PostToolUse commands are arbitrary shell, so either could otherwise bypass their read-only contract indirectly.
-They also skip configured and plugin-provided MCP server processes, so starting an external tool server cannot
-bypass the same contract before the first model turn.
+They also omit the lazy connector for configured and plugin-provided MCP servers, so a read-only role cannot
+start an external tool server.
 **Profiles and live config**: select an identity with `--profile <name>`; use `overlays` in
 `~/.hara/config.json` for named config overlays. Project `.hara/config.json` files get the safe preference
 allowlist above; project-specific routing requires `HARA_TRUST_PROJECT_CONFIG=1` before launch.

package/SECURITY.md

@@ -70,11 +70,13 @@ local user (who already has your shell).
 - **MCP/external agents are trusted extensions.** They execute outside Hara's protected-file boundary. Every
   interactive tool call requires confirmation, including in `full-auto`; non-interactive runs disable them by
   default. Reviewed automation can explicitly enable them before launch with
-  `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. Their inherited environment is still scrubbed, but the extension may use
-  its own credentials or access anything its host process permits.
+  `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. Merely configuring an MCP server does not start it: `mcp_connect` requests
+  permission and starts one named server only when a task needs it. Their inherited environment is still
+  scrubbed, but the extension may use its own credentials or access anything its host process permits.
 - **Plugins are code you trust.** Installing a plugin (`hara plugin add`) grants its author code execution:
-  its MCP servers and hooks run shell commands on launch. `hara plugin add` **prints the exact commands** a
-  plugin will run so you can review them; disable with `hara plugin disable <name>`.
+  its MCP servers may run on first relevant use and its hooks may run around matching tool calls. `hara plugin
+  add` **prints the exact commands** a plugin can run so you can review them; disable with
+  `hara plugin disable <name>`.
 - **Coding-plan keys.** Provider keys you configure are used only to call the model endpoint you set.
 
 ## What is *not* a security boundary

package/dist/agent/limits.js

@@ -19,8 +19,8 @@ export function parseAgentRunTimeoutMs(value) {
     const parsed = amount * multiplier;
     return Number.isFinite(parsed) ? parsed : undefined;
 }
-/** Parse a total run deadline. Invalid/zero values cannot disable the safety boundary. Human values such
- * as `30m`, `90s`, and `1h` are accepted in config; HARA_RUN_TIMEOUT_MS also accepts plain milliseconds. */
+/** Parse the active execution deadline. Invalid/zero values cannot disable the safety boundary. Human values
+ * such as `30m`, `90s`, and `1h` are accepted in config; HARA_RUN_TIMEOUT_MS also accepts plain milliseconds. */
 export function agentRunTimeoutMs(value = process.env.HARA_RUN_TIMEOUT_MS) {
     const parsed = parseAgentRunTimeoutMs(value);
     if (parsed === undefined || parsed <= 0)