@nanhara/hara 0.70.0 → 0.89.0

package/CHANGELOG.md

@@ -5,6 +5,327 @@ 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.89.0 — unreleased (gateway: Slack · Mattermost · Matrix · DingTalk + docs)
+
+- **Four more platforms**, all zero-new-dep (native WebSocket / `fetch`), same `ChatAdapter` seam:
+  - **Slack** — Socket Mode (connects out, no public URL). `HARA_SLACK_APP_TOKEN` (xapp-) + `HARA_SLACK_BOT_TOKEN`
+    (xoxb-). Inbound text + image files (downloaded via the bot token); outbound text + file upload.
+  - **Mattermost** — v4 WebSocket + REST. `HARA_MATTERMOST_URL` + `HARA_MATTERMOST_TOKEN` (bot/PAT). Two-way images.
+  - **Matrix** — `/sync` long-poll. `HARA_MATRIX_HOMESERVER` + `HARA_MATRIX_TOKEN` + `HARA_MATRIX_USER_ID`.
+    Two-way images; **unencrypted rooms only in v1** (no E2EE).
+  - **DingTalk (钉钉)** — Stream Mode (connects out). `HARA_DINGTALK_CLIENT_ID` + `HARA_DINGTALK_CLIENT_SECRET`.
+    Text in/out via the per-message `sessionWebhook`; **v1: no file send, inbound images arrive as `[图片]`**.
+  - Each platform's wire parser (`parseSlackEvent` / `parseMattermostPost` / `parseMatrixEvent` / `parseMxc` /
+    `parseDingtalkMessage`) is pure + unit-tested.
+- **Docs** — new **[docs/gateway.md](docs/gateway.md)** documents all 8 platforms (Telegram · WeChat · Discord ·
+  Feishu/Lark · Slack · Mattermost · Matrix · DingTalk): a capabilities table, common config
+  (`HARA_GATEWAY_ALLOWED`, `--cwd`, slash commands, two-way images), and per-platform setup. Linked from README.
+- Ported by studying the openclaw + hermes adapter implementations; live-tested per platform as tokens become
+  available.
+
+## 0.88.0 — unreleased (gateway: Feishu/Lark adapter)
+
+- **Feishu/Lark** — `hara gateway --platform feishu` via the official `@larksuiteoapi/node-sdk` (the one new
+  dependency): a **WSClient long-connection** for inbound (no public webhook needed — fits the local daemon) and
+  the REST Client for outbound. Inbound text / rich-text post / image / file / audio (media downloaded to
+  `~/.hara/feishu/media` → the agent SEES images); outbound text + `sendFile` (image upload → image message,
+  else file upload → file message) so `send_file` / `/send` work. Creds via `HARA_FEISHU_APP_ID` /
+  `HARA_FEISHU_APP_SECRET` (+ `HARA_FEISHU_DOMAIN=lark` for larksuite.com), users via `HARA_GATEWAY_ALLOWED`
+  (open_id). v1 = p2p DMs; group support is a fast-follow. `parseFeishuContent` / `flattenPost` are pure + tested.
+
+## 0.87.0 — unreleased (gateway: Discord adapter)
+
+- **Discord** — `hara gateway --platform discord` connects to the Discord gateway over Node's native global
+  WebSocket (zero new dep on Node ≥ 22): HELLO→heartbeat→IDENTIFY, dispatches MESSAGE_CREATE, auto-reconnects.
+  Inbound text + image attachments (downloaded to `~/.hara/discord/media` → the agent SEES them); outbound text
+  (2000-char chunks) and `sendFile` (multipart) so `send_file` / `/send` work. Token via `HARA_DISCORD_TOKEN`,
+  users via `HARA_GATEWAY_ALLOWED` (Discord user ids). Needs the bot's privileged Message Content Intent.
+  Same `ChatAdapter` seam as Telegram/WeChat — all cross-platform gateway logic worked unchanged.
+
+## 0.86.1 — unreleased (gateway: Telegram reaches image parity with WeChat)
+
+- **Telegram two-way images** — `parseTelegramUpdate` now accepts photo messages (caption or a `[图片]` marker)
+  and the receive loop downloads the largest photo to `~/.hara/telegram/media` → `InboundMsg.images`, so the
+  agent sees it just like on WeChat. Added `sendFile` (sendPhoto for images, sendDocument otherwise) so `send_file`
+  and `/send` work on Telegram too. All the cross-platform gateway plumbing (send_file tool, in-chat system
+  context, stuck-guard, `-p` image attach/describe) was already platform-agnostic — only the adapter changed.
+
+## 0.86.0 — unreleased (gateway: the agent SEES inbound images)
+
+- **Inbound image understanding** — a photo you send in chat now reaches the model as a real image, not just a
+  `[图片: /path]` text breadcrumb. The WeChat adapter routes downloaded images into `InboundMsg.images`; the
+  gateway forwards their paths to the headless run (`HARA_GATEWAY_IMAGES`); the `-p` handler attaches them inline
+  for a vision-capable main model, or describes them via the configured `visionModel` sidecar and folds the
+  description into the message for a text-only model (e.g. glm-5 main + qwen3.7-plus vision). Together with 0.85's
+  `send_file`, the chat is now two-way for images. Verified live: glm-5 correctly described a sent picture via the
+  qwen3.7-plus sidecar.
+
+## 0.85.0 — unreleased (gateway: agent sends files in conversation + stuck-guard)
+
+- **`send_file` tool** — the agent can now deliver a file/image to the chat *conversationally* ("生成 X 发我"),
+  not just via the manual `/send` command. Self-gates on `HARA_GATEWAY`, so it appears only inside `hara gateway`.
+  It queues the path to a per-message outbox file; the daemon drains it after the headless run and delivers each
+  file via the platform adapter (`sendMediaFile` — images inline, others as attachments). This closes the gap
+  where hara, asked to "send an image", would generate it fine but then try to UI-automate the desktop WeChat
+  client with the `computer` tool (wrong surface, and blind without a vision model) and silently deliver nothing.
+- **In-chat system context** — when running under the gateway, the agent is told it's in a `${platform}` chat:
+  deliver files via `send_file` (the only channel that reaches the peer), do **not** drive the desktop client /
+  `computer` tool, and never claim a file was sent unless `send_file` succeeded.
+- **Stuck-guard (gateway only)** — once per run, if the agent keeps repeating one non-read tool (≥5×) or acts
+  blind (≥2 screenshots it can't read), a one-shot self-check nudge is injected so it steps back and picks a
+  working path instead of grinding forever (no human there to hit Esc). Off outside the gateway.
+
+## 0.84.0 — unreleased (gateway: file + image send/receive)
+
+- **Receive** — a file / image / (untranscribed) voice you send is now downloaded + AES-decrypted to a local
+  file under `~/.hara/weixin/media/`, and hara is handed a `[图片|文件 name|语音: /path]` reference so it can
+  read/process it (images → a vision-capable model). Ported iLink's inbound media path (CDN download →
+  AES-128-ECB decrypt) including the image `aeskey` hex-hack, the `encrypt_query_param` vs `encrypted_query_param`
+  naming, the conditional PKCS7 strip, the CDN-host SSRF allowlist, and a 128 MiB cap. Media-only messages
+  (no text) are now processed too.
+- **Send** — `sendMediaFile` sends any local file: images go **inline** (`image_item`), everything else
+  (zip / pdf / doc / audio / …) as a **file attachment** (`file_item`) carrying the filename. New `/send <path>`
+  command (absolute / `~` / relative to the chat's dir). Voice replies + `/say` now ride the same generic path.
+- `ChatAdapter.sendAudio?` → **`sendFile?`** (generic seam). Live-validated end-to-end: ZIP attachment + inline
+  image delivered. 265 tests.
+
+## 0.83.0 — unreleased (gateway: voice replies — pluggable TTS, /voice + /say)
+
+- The gateway can now **reply with voice** — a WeChat audio-file attachment (iLink's native voice bubble is
+  unreliable). `/voice` toggles spoken replies for a chat (each reply is also sent as audio); `/say <text>`
+  speaks one message. Ported iLink's media-upload path (getuploadurl → AES-128-ECB → CDN → `file_item`) into
+  `weixin.ts` byte-exact (incl. the dual AES-key encoding: hex in getuploadurl, base64-of-hex in sendmessage)
+  + live-validated end-to-end.
+- **Pluggable TTS** (`src/gateway/tts.ts`) — config-driven via env, nothing vendor-hardcoded, mirrors the video
+  project's provider design; both API and local:
+  - `say` (default) — local macOS, ~0.5s, Chinese voices (Tingting…), zero config → m4a.
+  - `openai` — any OpenAI-compatible `/audio/speech` endpoint (point `HARA_TTS_BASE_URL` at Aliyun DashScope or
+    a local TTS server); reuses the existing `openai` dep, no new dependency.
+  - `cmd` — a configurable local command (point `HARA_TTS_CMD` at VoxCPM or any local TTS; text on stdin).
+  - Select via `HARA_TTS_PROVIDER` (+ `HARA_TTS_VOICE`/`MODEL`/`BASE_URL`/`API_KEY`/`CMD`); a failed API
+    provider falls back to local `say`. New optional `ChatAdapter.sendAudio?` seam (weixin implements it).
+
+## 0.82.2 — unreleased (gateway: fix the voice tag that made hara disclaim)
+
+- 0.82.1's bare `[voice message]` prefix backfired — hara read it as raw audio to process and replied "I can't
+  handle voice," even though the message was already transcribed text (verified: the transcription reaches hara
+  correctly). Replaced with an explicit note ("…already transcribed to text below — just reply to it normally,
+  you don't have or need the audio") so hara answers the content instead of disclaiming.
+
+## 0.82.1 — unreleased (gateway: tag transcribed WeChat voice messages)
+
+- WeChat **voice input already works** — iLink transcribes voice server-side (`voice_item.text`) and the gateway
+  reads it. But the text reached hara unlabeled, so when the spoken words referenced "this voice," hara replied
+  as if it only got text. Now a transcribed voice message is tagged `[voice message] <text>`, so hara knows the
+  input came from voice. (Sending voice back is deferred — iLink's native voice bubble is unreliable per the
+  Hermes reference; only audio-file attachments are possible, and that needs the media-upload + TTS path.)
+
+## 0.82.0 — unreleased (gateway: roam projects + threads from chat — /cd, /pwd, project-scoped /sessions)
+
+- A chat can now **switch working directory at runtime**, and its session follows: `/cd <dir>` (absolute, `~`,
+  or relative to the current dir) moves the chat into that project and opens that project's own thread; `/pwd`
+  shows the current dir + thread; `/sessions` lists the **current dir's** threads; `/new` forks the current
+  dir's thread; `/resume <id>` jumps to a thread and adopts its dir so it runs in the right place. Each
+  (chat, dir) pair gets its own stable, resumable session id (`<platform>-<chatId>-<cwdTag>[-fork]`) — so one
+  gateway roams across projects while keeping per-project history, and switching back resumes. Foundation for
+  a future desktop client.
+- The chat-session store (`~/.hara/gateway/chats.json`) is now cwd-aware (`chatContext`/`chatCd`); old entries
+  migrate in place (keep their existing thread). Tested.
+
+## 0.81.6 — unreleased (headless `-p --resume`: auto-compact long sessions)
+
+- The `hara -p … --resume <id>` / `--continue` path (used by the chat gateway and cron) now runs
+  `maybeAutoCompact` before saving, so a long chat/cron thread **auto-compacts** (summarizes old turns)
+  instead of growing until it overflows the model's context window. Silent in headless mode (no notify) so
+  nothing leaks into a captured reply. Opt-out via `autoCompact: false` / `HARA_AUTO_COMPACT=0`. Previously
+  auto-compaction was wired only into the interactive/TUI loops, so gateway/cron sessions could overflow.
+
+## 0.81.5 — unreleased (gateway: default workspace = ~/.hara/workspace — dir-free, Hermes-style)
+
+- `hara gateway` (no `--cwd`) now operates in a dedicated **`~/.hara/workspace`** (created + seeded on first
+  run) instead of the launch directory — so the chat bot is dir-free + safe-by-default (like Hermes' own
+  `~/.hermes`), never landing full-auto on whatever repo you happened to launch from. `--cwd <dir>` still
+  targets a real project.
+- This only sets where *files* are created. hara's **global memory (`~/.hara/memory`) and roles
+  (`~/.hara/roles` + B-end `~/.hara/org-roles`) are cwd-independent and always loaded**, so a chat session
+  shares the same global brain as the terminal CLI regardless of workspace. `~/.hara/` is hara's home:
+  memory · roles · sessions · skills · checkpoints · config · per-platform gateway state.
+
+## 0.81.4 — unreleased (gateway: clean chat replies — strip MCP logs + token footer)
+
+- The chat gateway scraped the `hara -p` subprocess output and sent it verbatim, so WeChat/Telegram replies
+  were wrapped in CLI chrome — `mcp: … → N tool(s)`, `mcp: … failed …`, and the `model · ↑N ↓N tok` footer.
+  New `cleanReply()` strips those, leaving just the assistant's answer. (Tool/diff streaming for multi-step
+  tasks is untouched; this only removes the always-present MCP-startup + token-footer noise.) Tested.
+
+## 0.81.3 — unreleased (fix: gateway/cron subprocess spawn when hara runs via the `hara` bin symlink)
+
+- `selfArgv()` (used by the chat gateway and the cron tick to spawn a fresh `hara` per task) **dropped the
+  script path** when hara was invoked via the installed `hara` bin symlink: that path has no `.js` extension,
+  so the old extension-based heuristic returned just `[node]`, making the spawn `node -p <text> --approval …`
+  — which node rejected with `bad option: --approval` (the gateway replied with that error instead of running).
+  Now keyed on whether `execPath` is node (the real compiled-binary discriminator): it re-invokes the entry
+  (`dist/index.js` **or** the bin symlink) under node, and only re-invokes `execPath` directly for a true
+  single-binary build. Test covers all three cases.
+
+## 0.81.2 — unreleased (gateway: `--cwd` flag to point at a workspace without `cd`)
+
+- `hara gateway [--platform …] --cwd <dir>` sets the directory hara operates in for each incoming message,
+  so you can launch the daemon against a chosen workspace without `cd`-ing first (resolved to an absolute
+  path). Defaults to the current dir as before. Recommended pattern: a dedicated safe scratch dir (e.g.
+  `~/work/projects/tools/hara`) rather than a sensitive repo, since each message runs `--approval full-auto`.
+
+## 0.81.1 — unreleased (WeChat gateway: auto-allowlist the bot owner)
+
+- `hara gateway --platform weixin` now **auto-allows the bot owner** (the iLink `user_id` from login — i.e.
+  whoever scanned the QR), since on a personal-WeChat bot that id equals the `from_user_id` on your own
+  messages. Removes the "run once with an empty allowlist to discover your wxid, then re-run" dance — just
+  log in and run the daemon. Additional ids can still be added via `HARA_GATEWAY_ALLOWED`. (Validated the full
+  receive→reply round-trip against the live iLink server.)
+
+## 0.81.0 — unreleased (WeChat (iLink) gateway adapter — drive your local hara from personal WeChat)
+
+- **`hara gateway --platform weixin`** adds **WeChat (personal)** as a second chat channel, via Tencent's
+  official iLink bot API (`ilinkai.weixin.qq.com`, no ban risk) — the same `ChatAdapter` seam as Telegram,
+  so per-chat resumable sessions / allowlist / `/new` `/sessions` `/resume` all carry over. Text DMs (v1):
+  the bot reads & edits files and runs bash in the gateway's cwd, and replies in WeChat.
+- **`hara gateway --platform weixin --login`** — interactive QR login (scan with WeChat); saves
+  `{account_id, token, base_url}` to `~/.hara/weixin/creds.json`. The per-peer `context_token` and the
+  long-poll cursor are persisted, so replies route correctly and a restart resumes mid-stream. Handles
+  iLink's `-14` / stale-`-2` session-expiry (tokenless retry on send; re-login prompt on poll). Built-in
+  fetch; the login QR renders via the **optional** `qrcode-terminal` dep (falls back to printing the URL).
+  No crypto needed on the text path.
+- The allowlist now logs the sender id of unauthorized messages, so you can discover your WeChat id to add
+  to `HARA_GATEWAY_ALLOWED`. 256 tests.
+
+## 0.80.0 — unreleased (chat gateway — drive your local hara from Telegram; + headless session continuity)
+
+- **`hara gateway`** (opt-in daemon, hara's first long-running process) lets you drive your **local** hara from
+  a chat app — **Telegram** first ("message your bot → hara reads/edits files, runs bash, replies"). Each chat
+  is a **continuous, resumable session**: `/new` forks a fresh thread · `/sessions` lists · `/resume <id>`
+  jumps to one — backed by the stored sessions. Access is **allowlist-gated** (`HARA_GATEWAY_ALLOWED` user ids;
+  empty = nobody, never wide-open); token from `HARA_TELEGRAM_TOKEN`. Generic `ChatAdapter` shape → WeChat-iLink
+  / Feishu are same-interface fast-follows. **Zero new dep** (built-in `fetch` long-poll). `src/gateway/` + tests.
+- **`hara -p "<task>" --resume <id>` / `--continue`** now does **headless session continuity** — loads the
+  session, appends the prompt, runs, saves it back (a `--resume <id>` with no match is created with that id);
+  plain `hara -p` stays stateless. Useful for cron, scripts, and the gateway's per-chat threads.
+- This is the chat layer of the multi-terminal plan; the ACP server (for a custom App / editors) is deferred
+  until that App exists. 249 tests.
+
+## 0.79.0 — unreleased (app-level failover — retry an errored turn on a fallback model)
+
+- **`fallbackModel`** (opt-in): when a turn ends in a *recoverable* provider error — overload (529/503),
+  rate-limit (429), timeout, transient 5xx, or context-overflow — hara retries it **once on the fallback
+  model** instead of dying (a different model may not be overloaded / may have a larger window). `auth` errors
+  and user interrupts are never auto-retried. The SDK's transient `maxRetries:4` still handles the first line;
+  this is the app layer for what's left. `fallbackBaseURL`/`fallbackApiKey` default to the primary's.
+- Errors now also carry a short **actionable hint** by kind (auth → check key · overloaded → set fallbackModel
+  · context-overflow → /compact). Classification handles DashScope/GLM/Qwen **Chinese** error strings too. New
+  `src/agent/failover.ts` (pure classify + decide, fully tested); runAgent just executes the decision, guarded
+  to one retry. Tests (244 total). Completes the Sprint-2 spine (⑤ rewind + ⑥ failover).
+
+## 0.78.0 — unreleased (file-state checkpoints — shadow-git "undo the agent's edits")
+
+- **Durable file checkpoints** complete the rewind story (beyond the edit-only in-memory undo, which missed
+  `bash`-made changes). Before each turn, hara snapshots the whole working tree into a **shadow git repo** kept
+  OUTSIDE the project (`~/.hara/checkpoints/<hash>`, `GIT_DIR` there + `GIT_WORK_TREE` = project root) — so it
+  captures everything (incl. `bash`), **never touches your real `.git`/index**, and the model never sees it.
+  **`/checkpoint`** lists them; **`/checkpoint restore <n>`** reverts files to one.
+- **Safe by construction**: restore snapshots the current state first (so it's undoable) and only reverts
+  changed/deleted files — it **never deletes files created since** the checkpoint. Heavy/derived dirs
+  (`node_modules`, `.git`, `dist`, …) are excluded; only the first snapshot is a full scan (git's index makes
+  the rest incremental). Default on; opt out with `fileCheckpoints:false` / `HARA_CHECKPOINTS=0`.
+  `src/checkpoints.ts` + tests (241 total).
+
+## 0.77.0 — unreleased (/rewind — fork the conversation back to an earlier turn)
+
+- New **`/rewind`** — `/rewind` lists recent user turns; `/rewind <n>` forks the conversation back to before
+  one, so when the agent goes down a wrong path you can snip back to a good turn and re-steer, instead of
+  `/clear` (lose everything) or living with a poisoned context (codex's backtrack). **Conversation only —
+  file edits are NOT reverted** (durable file-state checkpoints via shadow-git are the planned heavier
+  follow-up). Both UIs; pure in-memory + session store. `src/agent/rewind.ts` + tests (239 total).
+
+## 0.76.0 — unreleased (/context — see what's filling the context window)
+
+- New **`/context`** command: a token-spend breakdown of the conversation — which tool's output, assistant
+  text, and your messages are using the window (biggest first, with the share of the model's window) — so on a
+  long session you can see *why* you're near the limit, not just the `ctx%` number. Pairs with auto-compaction.
+  chars/4 estimate, zero-dep, both UIs. `src/agent/context-report.ts` + tests (237 total).
+
+## 0.75.0 — unreleased (lazy subdirectory AGENTS.md / CLAUDE.md — monorepo-local conventions reach the model)
+
+- When a tool touches a directory not seen yet this session, hara loads that directory's **`AGENTS.md` /
+  `CLAUDE.md`** (the local conventions for that package) and appends it to the tool result — so in a monorepo,
+  `packages/api/AGENTS.md` or `growth/CLAUDE.md` reaches the model exactly when work moves there, not just the
+  root doc loaded at startup. Each directory loads once per session; only dirs **under cwd** (startup already
+  covers cwd→root); paths are taken from a tool's `path` or path-like tokens in a `bash` command. Zero-dep,
+  additive (never removes context). `src/context/subdir-hints.ts` + tests (235 total).
+
+## 0.74.1 — unreleased (bash output keeps head + tail, not just head)
+
+- Long command output (build / test logs) is now truncated **keeping both the head and the tail** instead of
+  only the first 100k chars — so the model still sees the **end**, where the error/result usually is (plain
+  head-truncation cut exactly the part that matters). `read_file` truncation is unchanged. New `capHeadTail`
+  used on `bash` success + failure output; + test (233 total).
+
+## 0.74.0 — unreleased (auto-compaction — summarize before the context overflows, like Claude Code)
+
+- **Auto-compaction**: when a turn fills the model's context past ~85%, hara now **summarizes the conversation
+  and continues automatically** (a "✻ Auto-compacting conversation…" notice) instead of only warning — so a
+  long session no longer dead-ends at the context limit. Opt out with `autoCompact: false` (or
+  `HARA_AUTO_COMPACT=0`); below the threshold the ≥80% warning still shows. Works in the TUI **and** the classic
+  REPL.
+- The summarize-and-replace logic is now a single shared `compactConversation` (manual `/compact` and auto both
+  use it — no drift); it keeps the working-memory notes that survive the wipe and resets the context gauge off
+  the (small) summary. New `src/agent/compact.ts` (`shouldAutoCompact` trigger) + test (232 total).
+- The two distinct controls (unchanged, just clarified): **`/compact`** summarizes → replaces history to free
+  tokens while keeping the thread; **`/clear`** (= `/reset`) wipes the conversation for a fresh start.
+
+## 0.73.0 — unreleased (Sprint 2: background shell jobs — run dev servers / watchers without blocking)
+
+- **`bash {background: true}`** starts a long-lived command (dev server, `tsc --watch`, a long build) as a
+  background job and returns a job id immediately — the agent keeps working instead of blocking on a command
+  that never exits. New **`job` tool** (`list` / `tail` / `kill`) manages them; output is captured to a capped
+  tail buffer. Background jobs reuse `bash`'s exact **sandbox write-confinement** (shared `shellCommand`) and
+  pass the same permission gate when started; they're the agent's own children and are **terminated when hara
+  exits** (no orphaned dev servers). `src/exec/jobs.ts` + tests (231 total). First slice of the exec-subsystem
+  gap from the 4-expert analysis — persistent/interactive PTY + docker/ssh backends come next.
+
+## 0.72.0 — unreleased (per-turn model routing: strong model for code, cheap/general for trivial turns)
+
+- **Opt-in per-turn model routing** — the answer to "use a coding model for real work, a cheap/general model
+  for trivial chat" *without* splitting hara into two tools. Set `routeModel` (+ optional `routeBaseURL` /
+  `routeApiKey`, which default to the primary's) and each turn routes by its latest user message: trivial,
+  non-coding turns (short · single-line · no code / URL · no action keyword) go to `routeModel`; anything with
+  a coding/action signal stays on the primary `model`. **Conservative by design** — a coding tool errs toward
+  the strong model, so routing only fires on clear Q&A / chit-chat.
+- Implemented as a transparent provider wrapper at the single main-chat entry (`withRouting`), so every
+  interactive / `-p` / TUI turn gets it while role / review / sub-agent providers stay untouched. The decision
+  reads the last `role:"user"` message (tool results are `role:"tool"`), so it's stable across a turn's tool
+  rounds. New `src/agent/route.ts` + tests. Env: `HARA_ROUTE_MODEL` / `HARA_ROUTE_BASE_URL` / `HARA_ROUTE_API_KEY`.
+
+## 0.71.0 — unreleased (Sprint 1: governance + safety — command permissions · untrusted-content wrapping · structured compaction)
+
+Three zero-dep items distilled from a 4-expert (codex/cc-haha/hermes/openclaw) C-end gap analysis; all reinforce hara's governance moat.
+
+- **Command-level permission rules for `bash`** (`~/.hara/permissions.json` + project `.hara/permissions.json`):
+  an `allow` / `deny` + read-only-autorun policy that **composes with** approval modes. A **deny** rule blocks a
+  command even in `--full-auto`; an **allow** rule (or a recognized **read-only** command — `ls`/`grep`/`git
+  status`…) auto-runs even in `suggest` mode — ending the "confirm every command vs. unguarded full-auto" false
+  choice. Commands are canonicalized (unwrap `bash -lc`, strip `NODE_ENV=…`/`timeout` wrappers) so approving
+  `npm test` once sticks across phrasings; a compound command (`&&`/`||`/`;`/`|`) takes its **strictest** part's
+  decision; anything unparseable (`$()`/backticks/unbalanced quotes) fails **closed** to a prompt. New
+  `hara permissions` (list · `--init [--project]`). `src/security/permissions.ts` + tests.
+- **Untrusted-content wrapping** for `web_fetch` / `web_search`: external page/search text is wrapped in a
+  "treat as DATA, not instructions" notice with a **random per-call boundary id**, and homoglyph / zero-width
+  tricks (fullwidth/CJK/math angle brackets, ZWSP/BOM/soft-hyphen) are defanged so a hostile page can't forge
+  the boundary or smuggle hidden instructions — closing the realistic indirect-prompt-injection vector for an
+  agent that holds `bash`. `src/security/external-content.ts` + tests.
+- **Structured `/compact` template**: replaces the one-line summary with a 6-section brief (goal · key decisions
+  · files & code · errors & fixes · current state · next step) that **quotes the user's most recent request
+  verbatim** and drafts in an `<analysis>` scratchpad first — so resuming after a compaction doesn't drift or
+  drop the error→fix history.
+
 ## 0.70.0 — unreleased (B-end: devices pull their governed org-role bundle)
 
 - An enrolled device now **syncs its digital-employee roles from hara-control** — `GET {gateway}/v1/roles`

package/README.md

@@ -6,10 +6,11 @@
 > with routing boundaries, a dispatcher, a single source-of-truth data layer, human-in-the-loop
 > approvals, and cron autonomy.
 
-🚧 **v0.33** · TypeScript · local-first · Apache-2.0
+🚧 **v0.89** · TypeScript · local-first · Apache-2.0
 
 **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**), and `hara plan --parallel` runs independent atoms concurrently.
+- **Drive it from chat** — `hara gateway` runs your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk** (8 platforms), with **two-way images** (send a photo → it sees it; ask for a file → it sends one), per-chat resumable sessions, and project roaming. Connects out — no public webhook. See **[docs/gateway.md](docs/gateway.md)**.
 - **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). Inspect/consolidate it with **`hara memory show`** and **`hara memory distill`** (promote recent daily logs → durable memory). Lexical-first by design — semantic search is opt-in, never required.
 - **Multi-provider, all streamed** — Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) with live Markdown + visible reasoning.
@@ -240,10 +241,11 @@ turn, or **`/undo`** to revert the last edit. In-session **`/diff`**, **`/review
 - **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**.
+- **Chat gateway**: drive your local hara from a chat app — **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk**. The daemon connects out (no public webhook), with per-chat sessions, project roaming (`/cd`), and **two-way images** (send a photo → it sees it; ask for a file → it sends one). Setup per platform: **[docs/gateway.md](docs/gateway.md)**.
 
 ### Roadmap
 
-**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **single-binary distribution** · **Docker image** · `/compact` context management.
+**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **chat gateway (8 platforms, two-way images)** · **single-binary distribution** · **Docker image** · `/compact` context management.
 **Next:** SSOT data authority · an enterprise control-plane (fleet + central token management).
 
 ## Security

package/dist/agent/compact.js

@@ -0,0 +1,10 @@
+// Auto-compaction trigger — the small, testable decision behind "compact the conversation before it overflows"
+// (à la Claude Code's auto-compact). The actual summarize-and-replace I/O lives in index.ts (compactConversation),
+// which reuses the manual /compact path; this just decides *when* to fire.
+/** Auto-compact once the last turn used ≥ this % of the model's context window. */
+export const AUTO_COMPACT_PCT = 85;
+/** Whether to auto-compact now: enabled, the history is substantial enough to be worth summarizing, and the
+ *  last turn filled the context past the threshold (so the NEXT turn would risk overflow). */
+export function shouldAutoCompact(ctxPct, historyLen, autoCompact, threshold = AUTO_COMPACT_PCT) {
+    return autoCompact && historyLen >= 4 && ctxPct >= threshold;
+}

package/dist/agent/context-report.js

@@ -0,0 +1,33 @@
+import { contextWindow } from "../statusbar.js";
+const est = (s) => Math.ceil((s?.length ?? 0) / 4);
+/** Estimate token spend by category (your messages / assistant / each tool's output) across the history. */
+export function analyzeContext(history) {
+    const by = new Map();
+    const add = (k, n) => {
+        by.set(k, (by.get(k) ?? 0) + n);
+    };
+    for (const m of history) {
+        if (m.role === "user")
+            add("your messages", est(m.content));
+        else if (m.role === "assistant")
+            add("assistant", est(m.text));
+        else if (m.role === "tool")
+            for (const r of m.results)
+                add(`tool: ${r.name}`, est(r.content));
+    }
+    const total = [...by.values()].reduce((a, b) => a + b, 0);
+    const rows = [...by.entries()]
+        .map(([label, tokens]) => ({ label, tokens, pct: Math.round((tokens / (total || 1)) * 100) }))
+        .sort((a, b) => b.tokens - a.tokens);
+    return { total, rows };
+}
+/** Human-readable breakdown, biggest first, with the share of the model's window used + a trim hint. */
+export function formatContextReport(history, model) {
+    const { total, rows } = analyzeContext(history);
+    if (!rows.length)
+        return "Context is empty.";
+    const pctWin = Math.min(99, Math.round((total / contextWindow(model)) * 100));
+    const lines = rows.slice(0, 8).map((r) => `  ${String(r.pct).padStart(3)}%  ${r.label} (~${r.tokens.toLocaleString()} tok)`);
+    const tip = pctWin >= 80 ? "\n  → near the limit; /compact to summarize or /clear to reset." : "";
+    return `Context ~${total.toLocaleString()} tok (~${pctWin}% of ${model}'s window):\n${lines.join("\n")}${tip}`;
+}

package/dist/agent/failover.js

@@ -0,0 +1,53 @@
+// App-level failover — what to do when a provider turn ENDS in an error (the SDK already retried transient
+// 429/5xx via maxRetries; this handles what's left). Two recoveries: a context-overflow → compact + retry,
+// and a persistent/overloaded error → retry once on a configured FALLBACK model. The decision is pure +
+// tested here; runAgent just executes it (and guards each recovery to once, so no retry loops).
+/** Classify a provider error from its message (+ HTTP status if known). Message patterns include the
+ *  Chinese strings DashScope/GLM/Qwen return, since hara targets those endpoints. */
+export function classifyError(msg, status) {
+    const m = (msg || "").toLowerCase();
+    if (m === "interrupted")
+        return "interrupted";
+    if (status === 401 || status === 403 || /unauthor|invalid api key|invalid.*key|forbidden|permission denied|无效|鉴权/.test(m))
+        return "auth";
+    if (status === 429 || /rate.?limit|too many requests|\b429\b|请求过于频繁|限流/.test(m))
+        return "rate_limit";
+    if (status === 529 || status === 503 || /overload|capacity|service unavailable|temporarily unavailable|\b503\b|\b529\b|繁忙|过载/.test(m))
+        return "overloaded";
+    if (/context length|context window|maximum context|maximum.*token|too long|reduce the length|超过最大长度|上下文长度|输入过长/.test(m))
+        return "context_overflow";
+    if (/timeout|timed out|etimedout|econnreset|socket hang up|network/.test(m))
+        return "timeout";
+    if (typeof status === "number" && status >= 500)
+        return "transient";
+    return "unknown";
+}
+// Error kinds where retrying on a DIFFERENT model can plausibly help (it may not be overloaded / may differ).
+const FALLBACKABLE = new Set(["overloaded", "rate_limit", "timeout", "transient", "context_overflow", "unknown"]);
+/** Decide the recovery for an errored turn: retry once on the fallback model, or fail. Never auto-recovers
+ *  `auth` (a config problem) or `interrupted` (the user). Context-overflow IS fallback-able — a
+ *  larger-context fallback model may fit (and preemptive auto-compaction already prevents most overflows). */
+export function failoverAction(kind, s) {
+    if (kind === "interrupted" || kind === "auth")
+        return "fail";
+    if (s.hasFallback && !s.triedFallback && FALLBACKABLE.has(kind))
+        return "fallback";
+    return "fail";
+}
+/** A short actionable hint appended to the surfaced error message. */
+export function errorHint(kind) {
+    switch (kind) {
+        case "auth":
+            return " — check your API key / auth (try `hara setup`)";
+        case "rate_limit":
+            return " — rate-limited; wait a moment, or set `fallbackModel` to auto-switch";
+        case "overloaded":
+            return " — provider overloaded; set `fallbackModel` to auto-switch on errors";
+        case "context_overflow":
+            return " — context too long; `/compact` (or enable `autoCompact`)";
+        case "timeout":
+            return " — network timeout; check connectivity";
+        default:
+            return "";
+    }
+}

package/dist/agent/loop.js

@@ -6,6 +6,9 @@ import { makeRenderer } from "../md.js";
 import { skillsDigest } from "../skills/skills.js";
 import { runHooks } from "../hooks.js";
 import { mapLimit, maxParallel } from "../concurrency.js";
+import { decideCommand, loadPermissionRules } from "../security/permissions.js";
+import { subdirHint } from "../context/subdir-hints.js";
+import { classifyError, failoverAction, errorHint } from "./failover.js";
 /** Whether a tool call needs user confirmation under the given approval mode. */
 export function needsConfirm(kind, mode) {
     if (kind === "read")
@@ -30,10 +33,24 @@ When a task matches one of the Skills listed below, call the \`skill\` tool to l
 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.`;
+/** When running inside `hara gateway`, tell the agent it's in a chat — so it delivers files via send_file
+ *  (the only channel that reaches the peer) and never reaches for the desktop client / computer tool. */
+function gatewayNote() {
+    const plat = process.env.HARA_GATEWAY;
+    if (!plat)
+        return "";
+    return (`\n\n# You are in a chat gateway (${plat})\n` +
+        `You are talking to the user through the ${plat} chat — not a terminal, and NOT the desktop ${plat} app. ` +
+        `To send a file or image to them, call the \`send_file\` tool with an absolute path; that is the ONLY channel ` +
+        `that reaches this chat. Do NOT use the \`computer\` tool, AppleScript, or any desktop/${plat}-client automation ` +
+        `to deliver files — that drives a different window and silently fails to reach the user. Never tell the user a ` +
+        `file was sent unless \`send_file\` returned success. Keep replies short and chat-friendly.`);
+}
 function composeSystem(cwd, projectContext, override, memory) {
     const head = override ? `${override}\n\nWorking directory: ${cwd}` : HARA_SYSTEM(cwd);
     const skills = skillsDigest(cwd);
     return (head +
+        gatewayNote() +
         (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}` : ""));
@@ -41,6 +58,16 @@ function composeSystem(cwd, projectContext, override, memory) {
 /** Provider-agnostic agentic loop. Mutates `history` in place. */
 export async function runAgent(history, opts) {
     const { provider, ctx } = opts;
+    const permRules = loadPermissionRules(ctx.cwd); // command-level allow/ask/deny policy for the bash tool
+    let activeProvider = provider; // may switch to a fallback model on a recoverable error (app-failover)
+    let triedFallback = false;
+    // Stuck/loop guard — only in headless chat (`hara gateway`), where a wrong approach can grind forever with
+    // nobody to hit Esc (e.g. screenshots it can't read). Once per run, when the agent keeps repeating one
+    // non-read tool or acting blind, we inject a reflection nudge so it steps back instead of spinning.
+    const guard = !!process.env.HARA_GATEWAY;
+    const toolCounts = new Map();
+    let blindShots = 0;
+    let nudged = false;
     for (;;) {
         // Type-ahead steering: fold in anything the user submitted while the previous step ran, so it
         // reaches the model on this next call (drained after the last tool round; empty on the 1st pass).
@@ -68,7 +95,7 @@ export async function runAgent(history, opts) {
             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({
+        const r = await activeProvider.turn({
             system: composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory),
             history,
             tools: specs,
@@ -115,12 +142,26 @@ export async function runAgent(history, opts) {
         }
         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"}`;
+            const kind = classifyError(r.errorMsg ?? "");
+            if (failoverAction(kind, { hasFallback: !!opts.fallback?.provider, triedFallback }) === "fallback") {
+                triedFallback = true;
+                history.pop(); // drop the errored (partial/empty) assistant turn before retrying
+                activeProvider = opts.fallback.provider;
+                if (!opts.quiet) {
+                    const note = `✻ ${kind} → falling back to ${activeProvider.model}…`;
+                    if (sink)
+                        sink.notice(note);
+                    else
+                        out(c.dim(`${note}\n`));
+                }
+                continue; // retry once on the fallback model (guarded by triedFallback)
+            }
+            const msg = kind === "interrupted" ? "(interrupted)" : `[${activeProvider.id} error] ${r.errorMsg ?? "unknown"}${errorHint(kind)}`;
             if (!opts.quiet) {
                 if (sink)
                     sink.notice(msg);
                 else
-                    out(r.errorMsg === "interrupted" ? c.dim(`\n${msg}\n`) : c.red(`${msg}\n`));
+                    out(kind === "interrupted" ? c.dim(`\n${msg}\n`) : c.red(`${msg}\n`));
             }
             return;
         }
@@ -139,7 +180,14 @@ export async function runAgent(history, opts) {
                 .trim();
             // Screen control is gated on EVERY action — a prior "don't ask again" must never satisfy it.
             const alwaysGate = tool.kind === "computer";
-            if (needsConfirm(tool.kind, opts.approval) && (alwaysGate || !opts.autoApprove?.has(tu.name))) {
+            // Command-level policy for shell commands: a deny rule blocks even in full-auto; an allow rule (or a
+            // read-only command) auto-runs even in suggest mode. Composes with, doesn't replace, the approval mode.
+            const cmdDecision = tool.kind === "exec" && typeof input.command === "string" ? decideCommand(input.command, permRules) : null;
+            if (cmdDecision === "deny") {
+                plans.push({ tu, tool, denied: "Denied by a permission rule (~/.hara/permissions.json). Loosen the rule or run it yourself." });
+                continue;
+            }
+            if (cmdDecision !== "allow" && needsConfirm(tool.kind, opts.approval) && (alwaysGate || !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." });
@@ -172,7 +220,8 @@ export async function runAgent(history, opts) {
                     return;
                 }
                 const res = await p.tool.run(p.tu.input, ctx);
-                results[idx] = { id: p.tu.id, name: p.tu.name, content: res };
+                // append any not-yet-seen subdirectory AGENTS.md/CLAUDE.md this call touched (monorepo-local conventions)
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: res + subdirHint(p.tu.input, ctx.cwd) };
                 runHooks("PostToolUse", p.tu.name, { input: p.tu.input, result: res }, ctx.cwd); // observe-only
             }
             catch (e) {
@@ -202,5 +251,26 @@ export async function runAgent(history, opts) {
         }
         await flush();
         history.push({ role: "tool", results });
+        if (guard && !nudged) {
+            for (const p of plans)
+                if (p.tool && p.tool.kind !== "read")
+                    toolCounts.set(p.tu.name, (toolCounts.get(p.tu.name) ?? 0) + 1);
+            for (const res of results)
+                if (typeof res.content === "string" && /Configure a vision model/.test(res.content))
+                    blindShots++;
+            const maxRepeat = Math.max(0, ...toolCounts.values());
+            const blind = blindShots >= 2;
+            if (blind || maxRepeat >= 5) {
+                nudged = true;
+                history.push({
+                    role: "user",
+                    content: blind
+                        ? "⚠ Self-check: your screenshots come back unreadable (no vision model) — you are acting blind, so this approach cannot work. Stop using the computer tool. Reach the user through a non-visual path instead (a CLI, an API, or the send_file tool). State the new plan in one line, then do it."
+                        : "⚠ Self-check: you've repeated the same action several times without resolving the task. Stop and reconsider — is there a more direct tool or channel (e.g. send_file to deliver a file)? Don't keep retrying the same thing. State your revised plan in one line, then act.",
+                });
+                if (!opts.quiet && !ctx.ui)
+                    out(c.dim("  ⟲ stuck-guard: nudging a rethink\n"));
+            }
+        }
     }
 }

package/dist/agent/rewind.js

@@ -0,0 +1,20 @@
+/** Recent user turns, newest first (n=1 = most recent), each with a short preview — for `/rewind` to list. */
+export function userTurnPreviews(history, max = 10) {
+    const idxs = [];
+    history.forEach((m, i) => m.role === "user" && idxs.push(i));
+    const out = [];
+    for (let k = idxs.length - 1, n = 1; k >= 0 && n <= max; k--, n++) {
+        const m = history[idxs[k]];
+        out.push({ n, preview: (m.role === "user" ? m.content : "").replace(/\s+/g, " ").slice(0, 70) });
+    }
+    return out;
+}
+/** Truncate history to just BEFORE the n-th-most-recent user turn (n=1 drops the last exchange), forking the
+ *  conversation from that point. Returns the new history array, or null if n is out of range. */
+export function rewindTo(history, n) {
+    const idxs = [];
+    history.forEach((m, i) => m.role === "user" && idxs.push(i));
+    if (!Number.isInteger(n) || n < 1 || n > idxs.length)
+        return null;
+    return history.slice(0, idxs[idxs.length - n]); // cut at the n-th-from-last user message
+}