@pentoshi/clai 4.19.0 → 5.1.0

package/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+## v5.1.0 — 2026-10-23
+
+This release adds the Hinoki provider and a bundled, on-demand security skill, improves skill recovery after compaction, and fixes tool progress and terminal rendering. It covers all changes since **v5.0.0**.
+
+### Hinoki provider
+
+- Add `hinoki` with the default `hinoki-offensive` model, authenticated model discovery, streaming answers and reasoning, function calls, and image support. Configure it with `clai set hinoki` and `clai use hinoki`, or `HINOKI_API_KEY`; `HINOKI_BASE_URL` and saved endpoints can override the default URL.
+- Use published model metadata for context/output limits, tools, vision, and reasoning controls. Retain learned limits between sessions, coalesce concurrent catalog requests, and isolate caches by credential and endpoint. Temporary catalog failures retain the last successful result with a retry cooldown; authentication errors remain visible for key rotation.
+- Preserve complete conversation and tool-result replay, per-session cache affinity, shared key failover, and measured cached-input, cache-write, and reasoning-token usage when the API reports it. Cache hits and workspace credit balances are not inferred.
+
+### Bundled skills and compaction recovery
+
+- Ship `clai-superman-skill`, an on-demand security investigation library covering web/API, identity, cloud, mobile, native systems, wireless/OT, AI agents, supply chains, and related research workflows. Include its usage guide and evaluation scenarios in the npm package.
+- Discover bundled skill metadata without eagerly loading reference content. Embed the library in standalone binaries and materialize its files only when loaded. Project, user, and custom-root skills with the same name continue to override the bundle.
+- Preserve a bounded index of loaded skills and previously read references through both summarized and mechanical compaction. Tell the agent to reload still-relevant instructions when their full content has left live context, rather than treating a historical load marker as sufficient.
+- Allow necessary skill reloads after compaction without authorizing replay of side-effecting tool sequences. Keep stable prompt/tool prefixes and cache affinity intact when loading or recovering guidance.
+
+### Tool progress and file reads
+
+- Show a pending tool card as soon as the provider identifies a streamed call, before its arguments finish. Animate argument preparation in both interfaces, stop the thinking timer at the tool boundary, and update the same card when complete arguments arrive and execution begins.
+- Reconcile parallel calls by wire ID or stream order, deduplicate legacy progress signals, and settle incomplete previews on cancellation, errors, or retry. Partial argument bytes are not displayed, and an unfinished preview is never recorded as a successful tool execution.
+- Use one `fs.read` input parser across execution, tool schemas, argument display, outcome handling, and read-only subagents. Normalize unambiguous single-file and multi-file inputs while rejecting conflicting paths, ranges, and ambiguous filter placement with actionable errors.
+
+### Terminal rendering and responsiveness
+
+- Make wheel scrolling in Classic and OpenTUI follow current input instead of replaying a long frame-by-frame backlog. Preserve single-notch precision, catch up after delayed frames, and cancel remaining motion on reversal, boundaries, and explicit jumps.
+- Keep clipped artifact paths and other one-row text stable while the transcript scrolls. Middle-clip long whole-text links to preserve both ends without losing their target.
+- Pin the OpenTUI status line to the terminal bottom across viewport resizes, and restore the trailing gap after turn summaries.
+- Restore a dedicated version row on startup cards in both interfaces, including the compact `ver` label at narrow widths.
+- Keep bold reasoning titles on their own rows in both interfaces without changing ordinary assistant emphasis or losing streamed markdown consistency.
+- Color Responder-owned plan rows by task state, matching their glyphs and phase chips. Adjust split and overlay pane widths to retain a clean gutter.
+
+### Validation and packaging
+
+- Check generated bundled-skill content for drift during CI and normal builds, and include it in native compilation.
+- Expand regressions for Hinoki routing/catalogs/streaming, skill discovery and packaging, cache continuity through compaction, pending tool lifecycles, file-read parsing, real terminal geometry, scrolling, and plan rendering.
+- Repair catalog, updater, snapshot, and loaded-machine timing regressions so the release remains gated on the complete cross-platform CI suite.
+
+### Upgrade notes
+
+- No configuration or session migration is required for this release. Existing providers and user/project skills remain supported.
+- Hinoki requires its own API key; generation is charged against the provider's workspace credits. See [PROVIDERS.md](https://github.com/pentoshi007/clai/blob/v5.1.0/PROVIDERS.md#hinoki) for setup and capability details.
+- The bundled security skill loads on demand and does not grant extra tool permissions or change engagement scope. Override it through a normal project/user/custom skill, not by editing its generated cache. See the [security skill guide](https://github.com/pentoshi007/clai/blob/v5.1.0/guides/security-skill.md).
+
+[Full comparison since v5.0.0](https://github.com/pentoshi007/clai/compare/v5.0.0...v5.1.0)
+
+## v5.0.0 — 2026-10-22
+
+This release covers all changes since **v4.19.0**, including the REA integration, session and interface improvements, provider fixes, and the reliability work below.
+
+### Accurate completion statistics
+
+- Show output tokens per second alongside elapsed time, file changes, and `/changes` in Classic and OpenTUI, including narrow layouts and restored transcripts.
+- Calculate TPS from reported output tokens and model-active generation time across foreground calls. Tool execution, user waits, auxiliary calls, and compaction do not inflate the rate; reasoning tokens are not counted twice.
+- Preserve earlier valid measurements when a later generation is interrupted. Aborted turns retain measured TPS, and exact partial usage is included when the provider reports it. Missing usage is never replaced with guessed token counts.
+
+### Live output and durable queued prompts
+
+- Keep tool-output and job pagers live in both interfaces, following streamed output, spool replacement, final artifacts, externally appended job logs, and log rotation.
+- Preserve paused scrolling when output completes, with explicit follow controls, bounded reads, redacted output, and cleanup of subscriptions and file watchers.
+- Stream the OpenTUI compaction pager through progress, replacement, final summaries, and failures instead of opening a frozen snapshot.
+- Persist unsent queued prompts per session with validated, redacted, atomic storage. Recover them after crashes, normal shutdown, session switches, and composer editing.
+- Remove a queued prompt only after foreground model submission is acknowledged. Pre-submission failures retain and pause the prompt rather than silently losing it or retrying indefinitely. Private/no-history sessions do not persist the queue.
+
+### On-demand reverse engineering with REA
+
+- Add managed REA installation, updates, connection controls, and status, with `@rea`, `/rea <task>`, and an in-app `/rea guide` in both interfaces.
+- Attach a version-matched, grouped tool index and workflow only when needed, preserving the stable system prompt and native tool catalog. Indicate tools that need an open target, an analysis engine, or unavailable prerequisites.
+- Add explicit user-run `/rea engines` status, install, use, and remove workflows for Ghidra, Java, and configured external engines. The agent cannot install analysis engines on its own.
+- Harden downloads with trusted HTTPS hosts, redirect validation, published SHA-256 checks, streamed size limits, stall detection, and disk-space checks. Reject unsafe archive entries and corrupted extraction.
+- Improve macOS, Linux x64/ARM64, and Windows installation behavior, including native decompiler builds where required, Windows path and rename handling, stale staging cleanup, selected-engine environment precedence, and clear unsupported-platform guidance.
+- Improve cancellation, reconnect sequencing, staged-update version reporting, installation contention messages, strict argument hints, exact tool lookup, and lazy archive loading.
+
+### Sessions, compaction, and terminal interfaces
+
+- Store sessions in individual append-only delta logs, automatically importing legacy `history.jsonl` while preserving the original file. Keep rejected frames separately and avoid unnecessary history reloads.
+- Rebuild compaction memory around the active goal, scoped instructions, gathered context, completed work, next steps, relevant files, genuine issues, and the latest user prompts. Preserve inherited instruction scope and stable replay prefixes.
+- Reduce per-frame transcript work and smooth wheel scrolling in both interfaces. Fix OpenTUI wheel stalls, duplicate acceleration, window-update races, and final-tool-card reachability without discarding saved history.
+- Refresh startup cards with clearer mode and permission badges, responsive labels, a consolidated version/welcome row, and correct provider/model pairing in Classic.
+- Improve whole-cell mouse selection, padding-origin drags, selectable startup and plan content, and plain-click behavior. Remove the transcript scrollbar.
+- Render markdown in completed and streaming reasoning, including emphasis and fenced code, with incremental caches. Improve status spacing, context chips, and tool durations.
+- Print large piped `history --show` output completely under Bun and regenerate the README preview from the real OpenTUI renderer.
+
+### Providers and agent reliability
+
+- Cache model lists for two minutes instead of up to thirty; never cache empty or fallback lists. Add `/model refresh` and `/models refresh [filter]`, bypass stale/in-flight results, and identify unavailable live catalogs accurately.
+- Size reasoning output budgets from learned, live, remembered, or documented model limits, up to 131,072 tokens where supported. Preserve context fit and learn actual output caps from provider rejections with a bounded retry.
+- Send a stable per-session River `prompt_cache_key`, preserve DeepSeek reasoning on tool-bearing requests, and derive Free/Zen context limits from the live catalog.
+- Recover from malformed DSML tool calls rather than terminating the turn.
+- Allow `http.fetch` to reach private, loopback, CGNAT, and metadata addresses while retaining engagement-scope enforcement.
+- Recover from asynchronous shell artifact open, write, and flush failures without crashing Bun or discarding bounded output. Surface actionable storage warnings and fatal-shutdown diagnostics.
+- Clean recognized session scratch folders after ten days of inactivity, checking at most daily across processes. Protect active sessions, recently modified files, and symlink targets; leave saved conversations and global/custom artifact retention unchanged. Compare expiry conservatively at millisecond precision so filesystem timestamp rounding cannot delete a folder at the exact ten-day boundary.
+
+### Safer tools and agent guidance
+
+- Allow `fs.edit` replacements of `""` to delete exact matching text. Keep empty search text invalid with actionable guidance rather than a generic argument error.
+- Clarify exact current `oldText`, whitespace and line endings, safe creation/insertion alternatives, stale-preview risks, and the requirement to re-read after a no-match result.
+- Require Responder delegation for finite work expected to exceed four to five minutes, including long suites, builds, scans, and CI watches. Keep interactive sessions in terminal tools and persistent servers/watchers in named normal background jobs.
+- Preserve useful prompt safeguards and raise the native prompt-overhead guard to 23,000 estimated tokens.
+- Keep deliverables out of scratch directories and avoid adopting unrelated same-named projects. Scope persistent instructions to the actual project while preserving cross-turn prompt-cache prefixes.
+- Prevent MCP fuzzy matching from overriding built-in tool names or wire spellings, preserving built-in confirmation and parallel-safety rules.
+
+### Validation and distribution
+
+- Expand regressions for provider cancellation and exact TPS, both terminal interfaces, live pagers, queue submission/restart/shutdown behavior, atomic storage, tool edits, prompt variants, cache stability, and platform-specific REA behavior.
+- Isolate test home directories and disable the real keychain during tests so placeholder provider keys cannot overwrite developer credentials.
+- Harden CI checkout credentials and require SHA-256 evidence in the REA smoke test.
+- Synchronize the v5 version across runtime metadata, npm lockfile, Homebrew and Scoop templates, and include this changelog in the npm package.
+
+### Upgrade notes
+
+- Existing configuration remains supported; legacy session history is imported automatically and retained.
+- Queued-prompt persistence does not promise distributed exactly-once delivery across a crash between remote acceptance and local acknowledgement.
+- TPS is omitted when exact provider usage is unavailable rather than displaying a fabricated rate.
+- REA engine setup remains an explicit user action; platform prerequisites and limitations are documented in [REA.md](REA.md).
+
+[Full comparison since v4.19.0](https://github.com/pentoshi007/clai/compare/v4.19.0...v5.0.0)

package/PROVIDERS.md

@@ -110,6 +110,7 @@ An environment credential is also used directly when no stored credentials take
 | ExpLabs | `explabs` | `EXPLABS_API_KEY` |
 | Fireworks | `fireworks` | `FIREWORKS_API_KEY` |
 | Hetzner | `hetzner` | `HETZNER_API_KEY` |
+| Hinoki | `hinoki` | `HINOKI_API_KEY` |
 | Lightning AI | `lightning` | `LIGHTNING_API_KEY` |
 | Merge Gateway | `merge-gateway` | `MERGE_GATEWAY_API_KEY` |
 | Meta Model API | `meta` | `MODEL_API_KEY` |
@@ -125,14 +126,26 @@ For model choice, use `/model` or `clai model <name>`. Use the `/provider` picke
 
 The `free` integration discovers free models from two gateways: `free-1/<model>` uses [OpenCode Zen](https://opencode.ai/docs/zen/), and `free-2/<model>` uses [Kilo](https://kilo.ai/docs/gateway/api-reference). Model availability can change independently at each gateway. Zen's Jev decision models use the separate System One API and are omitted from the chat model picker.
 
-Kilo's model catalog supplies context and output limits directly. Zen's model list currently omits those limits, so clai fills missing values from the exact model entry in the OpenCode provider catalog on [Models.dev](https://github.com/anomalyco/models.dev#api). Discovery follows live model IDs, including newly added models, without a clai update or a hardcoded limit entry. Values reported by the gateway take precedence. The two sources keep separate limits even when model names match; older unprefixed Zen model selections also use the discovered limits.
+Kilo's model catalog supplies context and output limits directly. Zen models are discovered from the live [OpenCode provider catalog](https://models.opencode.ai/api.json): non-deprecated, zero-cost entries determine the list, including models omitted from Zen's `/models` response. Missing gateway limits come from each exact catalog entry, without per-model allowlists, context pins, or upstream model-name guesses. Values reported by the gateway take precedence. The two sources keep separate limits even when model names match; older unprefixed Zen model selections also use the discovered limits.
 
-Discovered limits are cached for 30 minutes and retained locally for later sessions. A newly discovered Zen model ID can trigger an earlier metadata refresh; retries for unpublished limits or failed lookups have a one-minute cooldown. When discovery is unavailable, clai keeps previously learned limits, then uses its model table or the 200,000-token default if no limit is known. A 200k context can also be an actual gateway limit, rather than a fallback. Use `/context` to inspect the selected session's context budget.
+Discovered limits are cached for 30 minutes and retained locally for later sessions. A newly discovered Zen model ID can trigger an earlier metadata refresh; retries for unpublished limits or failed lookups have a one-minute cooldown. For Zen only, a published 200,000-token context is configured as 250,000 tokens in clai; every other published limit is used unchanged. This is a clai policy, not a guarantee that the gateway accepts more than its published limit. When discovery is unavailable, clai keeps previously learned limits; unknown Zen limits use the conservative 200,000-token default, not the upstream model table. Explicit session context overrides remain available. Use `/context` to inspect the selected session's context budget.
 
 Agent turns retry temporary HTTP 429 failures up to four times, with visible waits of 5, 8, 10, and 15 seconds. This includes gateway responses that report an unavailable upstream endpoint. Shorter provider retry hints can shorten a wait. Standalone requests allow three retries by default.
 
 Retries preserve the conversation and tool definitions; cancelling the turn cancels the wait. Explicit billing or insufficient account quota errors require an account or provider change. If the gateway remains unavailable after the retry budget, select another model with `/model` or provider with `/provider`. Cross-provider fallback follows `/fallback` and `/freeonly` settings.
 
+### Hinoki
+
+Configure `clai set hinoki` and `clai use hinoki`, or set `HINOKI_API_KEY`. Existing `hinoki` credentials in `~/.clai/keys.json`, including multiple key slots, use the same selection, disabled-key handling, cooldowns, and failover as other providers. The default endpoint is `https://inference.hinoki.security/v1`, and the default model is `hinoki-offensive`. `HINOKI_BASE_URL` or a saved endpoint can override the URL.
+
+`/model` discovers the authenticated `/models` catalog. Published context/output limits, vision, tools, and reasoning metadata take precedence over fallback capabilities. Context limits are retained locally for later sessions. Generation reuses the catalog for five minutes; explicit model discovery refreshes it. Concurrent reads are coalesced and caches are isolated by key and endpoint. Temporary failures keep the last successful route catalog with a one-minute retry cooldown; authentication failures remain visible for shared key rotation.
+
+`/effort` uses advertised or runtime-learned settings; when metadata is absent, the endpoint's verified effort vocabulary is `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. These are accepted API controls, not a guarantee of visible reasoning at every level. Returned reasoning streams separately from the answer. Hidden reasoning-token counts still appear in session usage. Images and function calls are supported by `hinoki-offensive`; future models follow their catalog metadata and shared runtime capability handling.
+
+The integration uses Chat Completions for streaming and sends the full conversation, function calls, and tool results on every request. It never relies on saved responses or `previous_response_id`. Stable conversation/tool prefixes and a hashed per-session `prompt_cache_key` preserve cache affinity; cache hits depend on Hinoki's upstream infrastructure and cannot be guaranteed. Subagents and auxiliary requests retain their separate shared affinity.
+
+`/usage` reports measured session input, output, total, cached-input, cache-write, and reasoning tokens when returned by the API, including trailing usage-only stream events. Unknown counters are not fabricated. Workspace credit balances are not available through this integration; use Hinoki's workspace settings for those. API usage is charged against workspace credits.
+
 ### Constellation Gate
 
 Create a `sk-gw-…` key in the [Gate dashboard](https://app.constellationgate.ai/), then run `clai set constellation` and `clai use constellation`, or set `GATE_API_KEY`. Aliases include `gate`, `constellationgate`, and `constellation-gate`. The integration uses [pay-through-Gate authentication](https://docs.constellationgate.ai/getting-started/authentication/), not BYOK upstream headers; prepaid balance and model access rules apply. Key verification sends a one-token request because the catalog is public and does not validate credentials.

package/REA.md

@@ -0,0 +1,96 @@
+# REA: Reverse Engineer Anything
+
+clai integrates the official [morluto/rea](https://github.com/morluto/rea) project as an on-demand capability. Use `/rea` in either terminal interface to open its picker.
+
+| Command | Effect |
+| --- | --- |
+| `/rea install` | Install the latest official `rea-agents` package privately for clai. |
+| `/rea setup` | Install if needed and connect clai's managed REA server. |
+| `/rea update` | Verify and stage the latest release without interrupting an existing analysis. |
+| `/rea use` | Connect if necessary and insert an editable `@rea` token in your draft. |
+| `/rea on` | Enable REA for the session without editing the draft. |
+| `/rea off` | Stop only clai's managed REA server. |
+| `/rea status` | Check installation, connection and maintenance state without starting a server. |
+| `/rea reconnect` | Reconnect or adopt an update when it is safe to discard the current analysis connection. |
+| `/rea guide` | Open the usage guide in a markdown pager: commands, how the agent uses REA, supported targets and prerequisites for your OS, permissions, resource use and troubleshooting. |
+| `/rea engines` | Show which analysis engines (Ghidra, Hopper, IDA, Kuna) are ready on this machine and the exact command that fixes each one that is not. |
+| `/rea engines install ghidra` | After a confirmation, download the official Ghidra release and make it usable by REA. |
+| `/rea engines install java` | After a confirmation, install a private JDK 21 for REA's server when Java is what is missing. |
+| `/rea engines use <engine> <location>` | Use an installation you already have: a Ghidra folder, a JDK home, the Hopper launcher, an IDA MCP registration file or a Kuna executable. |
+| `/rea engines remove <engine>` | Forget an engine; clai asks before deleting anything it installed. |
+| `/rea <task>` | Submit `@rea <task>`, for example `/rea inspect this Electron app`. |
+
+`/rea` is the command that opens these options; `@rea` is the token that attaches REA to a prompt. Type `@rea` anywhere in a normal prompt. The token is highlighted in both composers, like `@mcp:` and skill mentions, and is never treated as a file (attach a file that is really named `rea` as `@./rea`). When a turn contains `@rea`, clai connects an installed REA before the model is called and gives the model the workflow and the tool index described below; if REA is not installed, the model is told to run `rea.manage action=setup`. The agent can also choose REA through `rea.manage` when the task warrants it; no manual activation is required. Installation and agent-initiated state changes use the normal permission policy. Ask/plan mode can inspect status and guidance but cannot install or change REA state.
+
+## Installation without npm or npx
+
+The installer uses clai's existing JavaScript runtime and HTTPS APIs; it does not invoke a shell, Homebrew, curl, PowerShell, tar, unzip, npm or npx from PATH. A compatible existing Node installation with its npm CLI is reused, looked up in this order: `CLAI_REA_NODE`, the Node that is running clai, then `node` on PATH. Otherwise clai downloads an official Node 24 LTS runtime with npm into its private installation. The native compiled clai binary therefore does not require a preinstalled Node toolchain.
+
+A compatible Node is 22.19+, 24.15+ or 26+ (upstream REA also accepts 24.11 to 24.14, but SQLite inspection needs 24.15+ or 26+). `CLAI_REA_NODE` must point at the `node` executable and is read when REA is installed; to move an existing installation to a different Node, remove `current.json` and run `/rea setup`. Installation is cancellable with Esc from either interface, and a download is abandoned after 60 seconds without data rather than after a fixed total time, so slow links can finish.
+
+Supported portable targets are macOS, Linux and Windows on x64/ARM64, subject to the official Node release's OS/libc support. nodejs.org does not publish Linux musl builds (Alpine), so install Node with the system package manager there. Unavailable architectures/builds produce an error that names the required Node versions and `CLAI_REA_NODE`, not an incompatible executable. Native engine support is a separate upstream constraint.
+
+Files live under `~/.clai/tools/rea` (or `$CLAI_DATA_DIR/tools/rea`). Node archives are checked against the official SHA-256 manifest; REA/npm tarballs use registry SHA-512 integrity. npm verifies dependency integrity, lifecycle scripts are disabled, and the install uses isolated registry/config/cache settings. Package acquisition requires access to `nodejs.org` and `registry.npmjs.org` as applicable. TLS/registry checksum verification is not an independent publisher-signature guarantee.
+
+A staged release is published only after its launcher reports the expected version, and the pointer file is replaced atomically (retrying briefly on Windows when another process holds it). Failures leave the previous release intact. Concurrent maintenance is serialized across processes and deduplicated within a process; a second clai session that waits too long is told that another session is installing. The current and previous releases are always kept so running MCP processes are not broken by an update; reconnect explicitly when ready. Releases older than that, including leftovers from interrupted installs, are removed once they are seven days old. An install takes about 250 MB with an existing Node and about 450 MB when clai also downloads one (the npm cache is shared across releases). Setup never changes Claude Code, Codex, other clients' registrations, skills, or the project's MCP configuration.
+
+## Efficient agent use
+
+REA is for shipped artifacts, decompilation, JavaScript/Electron applications, managed assemblies, Android, firmware, saved captures and requested runtime evidence—not ordinary source-repository reading.
+
+Only one small `rea.manage` tool is permanently advertised. Installing does not start a server. Enabling registers `clai-rea` for the current runtime, preserves other selected MCP servers, and connects once. Repeated enables reuse the analysis. REA's tools are not added to the provider's native tool catalog; the agent calls them through `mcp.call`.
+
+On `@rea`, on enable and on a `guide` request the model receives, once per conversation, a workflow of about 4,200 characters, an `ENGINE:` line and a version-matched index generated from the live catalog: every tool name, grouped by verb, with its required arguments, `~` where the tool accepts `detail` and `!` where it changes state or the target (about 8,300 characters for REA 6.7.0's 207 tools, bounded at 10,000). The index lets the agent call tools directly; `mcp.tools` with an exact tool name returns just that tool's full schema for optional fields and structured arguments. REA schemas are strict, so an argument a tool does not list is rejected and clai appends the accepted argument names to the error. The context is sent once per conversation: later turns that repeat `@rea` reuse it, and it is sent again, once, only if it changed (for example after you install an engine and reconnect).
+
+So that the agent does not call tools that cannot work, clai asks REA once per connection (one `binary_session` call, about 2 seconds and 50 KB, not repeated) which tools need an open target, an analysis engine or a missing prerequisite, and marks the index: `#` acts on the binary opened by `open_binary` and takes no path, `^` also needs an analysis engine, `%` is unavailable on this machine. The `ENGINE:` line says which engines are ready. When a call still fails, clai replaces REA's long machine-readable error with a short instruction: pass no `path` to a `#` tool and call `open_binary` first; thin a universal Mach-O to one slice with `lipo` before Ghidra or Kuna can read it; or, when no engine is ready, do not retry and tell the user to run `/rea engines`. If the availability report cannot be read, the plain index is used. Repeating `enable` on a live connection returns it again on request, without restarting anything. The always-advertised `rea.manage` description is kept to about 450 characters because it is sent with every request. The long human-oriented usage guide is shown only by `/rea guide` and is never sent to the model. Version-matched detailed workflow references remain on disk for focused reading. Prefer summaries, retained Evidence IDs, selected fields and bounded pages instead of repeating analysis or requesting full results. A host timeout does not establish that server work stopped: inspect state/Evidence before retrying. Inspect the actual current schema or returned remediation rather than guessing arguments or reinstalling.
+
+REA activation never rewrites the stable system prompt, native tool schemas, or prior messages. State and workflow changes enter the append-only conversation context. Cache-prefix regression tests cover installation, activation, discovery, calls, update, reconnect, disable and subsequent composer selection in both native/text tool modes and multiple provider wire formats. Provider cache eviction, compaction and switching providers/models remain independent of this guarantee.
+
+## Analysis engines
+
+Static JavaScript and Electron inspection, managed (.NET) assemblies, archives, Mach-O headers, plists, signatures and metadata need no engine. Native decompilation (procedures, pseudocode, strings, cross-references, assembly) needs one of Ghidra, Hopper, IDA or Kuna, and REA does not ship any of them.
+
+Engines are installed by you, never by the agent. `/rea engines` shows what is ready and what to run, and `/rea setup` points at it when it connects REA with no engine ready. `install` shows what it will download and where it will write (press `ctrl+o` for the full plan), asks for confirmation, shows progress and can be cancelled with Esc; `remove` asks before deleting anything clai installed, reconnects REA first so nothing is still using the files, refuses while a turn is running with REA connected, and says so if a folder could not be deleted (on Windows a folder that REA's Ghidra has open can be neither moved nor removed). The agent's workflow tells it not to install or configure an engine and to send you to `/rea engines` instead, and `rea.manage` has no engine action. Only one engine operation runs at a time. If REA is connected and idle when an install finishes, clai reconnects it so the new engine is used straight away; the engine is verified with REA before the install is reported as done.
+
+| System | `install ghidra` | `install java` |
+| --- | --- | --- |
+| macOS arm64 and x64 | Yes. Ghidra does not ship a macOS decompiler, so clai builds it once (one to three minutes; needs the Xcode Command Line Tools). | Yes |
+| Linux x64 | Yes; the decompiler is in the download. | Yes (glibc) |
+| Linux arm64 | Yes; builds the decompiler once (needs make, g++ and bison). | Yes (glibc) |
+| Windows x64 | Yes; the decompiler is in the download. REA's Windows Ghidra support is experimental upstream. | Yes |
+| Anything else (Windows arm64, Alpine and other musl Linux, 32-bit) | Not offered; `/rea engines` says so and why. Use `/rea engines use ghidra <folder>` with your own installation. | Not offered for musl; use `/rea engines use java <JDK home>` |
+
+Hopper is a commercial macOS and Linux application and Kuna is not available on Windows; clai does not install either. IDA needs your own installation and an MCP registration file. These are connected with `/rea engines use`. Android, firmware, capture and similar tools (JADX, apktool, binwalk, tshark and others) have their own prerequisites; `/rea engines` lists the ones that block tools on your machine with the fix REA reports, and clai does not install them.
+
+What `install ghidra` does:
+
+- Resolves the newest Ghidra 12.1.x release on GitHub (the series REA 6.7.0 needs) and refuses to continue unless GitHub publishes a SHA-256 for the download. Downloads are HTTPS only, limited to `github.com`, `*.githubusercontent.com`, `api.github.com` and `api.adoptium.net`, with every redirect re-checked, a size limit and a 60-second stall guard.
+- Checks free disk space first (about 570 MB to download, 1.6 GB while installing and 900 MB afterwards), extracts the archive itself (no `unzip`), and rejects absolute paths, `..`, symlinks, encrypted or ZIP64 entries and checksum mismatches.
+- Builds the native decompiler where needed with `make` using at most four jobs, with a 30-minute limit. It checks for the build tools before downloading anything and tells you what to install.
+- Stages everything in a temporary folder, moves it into `~/.clai/tools/ghidra/<version>` only when it is complete, then asks REA whether Ghidra is usable. A failed or cancelled install leaves nothing behind and keeps the previous version; after a successful one, older versions that clai installed are removed.
+
+Ghidra also needs a JDK 21 or newer. `install ghidra` does not change your system Java: if REA reports that Java is missing or too old, clai offers `install java`, which puts Eclipse Temurin 21 (about 200 MB, SHA-256 verified) in `~/.clai/tools/jdk/` and uses it for REA's server only.
+
+Settings live in `~/.clai/tools/rea/engines.json` (mode 0600; `$CLAI_DATA_DIR/tools/rea` if set). They are passed to REA's server as `GHIDRA_INSTALL_DIR`, `JAVA_HOME`, `HOPPER_LAUNCHER_PATH`, `REA_IDA_MCP_CONFIG` and `REA_KUNA_COMMAND`; a choice made with `/rea engines` takes precedence over the same variable in your own environment, for REA's server only (your shell is untouched), and `/rea engines remove` hands control back to your environment. Variables you have not set through `/rea engines` are passed through unchanged. Reconnect REA (`/rea reconnect`) after changing them yourself.
+
+Ghidra and Kuna cannot open universal (fat) Mach-O files such as most system binaries on macOS. The agent is told to thin one slice into the session scratch directory with `lipo <file> -thin <arch> -output <scratch>/<name>-<arch>` (`llvm-lipo` when `lipo` is missing) and open that. Hopper opens universal files directly.
+
+## Limits
+
+clai does not execute the target. On Linux, owned-process analysis needs a procps-compatible `ps`. The agent follows the selected tool's actual prerequisite or remediation and continues with supported work.
+
+Portable archives and failure cases have deterministic cross-platform fixtures. The implementation was live-tested on Linux ARM64 with REA 6.7.0 and portable Node/npm, including a standalone compiled integration smoke with no system executables on PATH. That smoke bootstrapped Node 24.22.0, discovered 207 tools, performed a digest-bound static analysis and disabled the server without removing the installation.
+
+The engine installers were run for real on freshly provisioned GitHub-hosted machines: Linux x64 and arm64, Windows x64, macOS arm64 and macOS Intel. Each one already exported its own Java (17 on Linux and Windows, 21 on macOS) and had no engine. On each, the shipped code installed Temurin 21 and Ghidra 12.1.4, REA reported Ghidra ready, and `open_binary`, `list_procedures`, `search_procedures` and `procedure_pseudo_code` returned decompiled code for a real system binary (an ELF `ls`, Windows' `whoami.exe`, a thinned Mach-O `ls`). Timings on GitHub's network, where the 543 MB download is quick; on a home connection the download dominates:
+
+| Machine | JDK | Ghidra | Decompiler |
+| --- | --- | --- | --- |
+| Linux x64 | 4 s | 11 s | in the download |
+| Linux arm64 | 3 s | 53 s | built (make, g++ and bison were present) |
+| macOS arm64 | 5 s | 73 s | built |
+| macOS Intel | 10 s | 184 s | built |
+| Windows x64 | 5 s | 18 s | in the download |
+
+The JDK takes 310 to 345 MB on disk and Ghidra 864 to 877 MB. The whole check on each machine, REA's own installation included, stayed under 500 MB of memory in clai's process; measured on its own on macOS arm64, the Ghidra install peaked at about 260 MB and used about 33 seconds of CPU. An Alpine container and a Windows 11 ARM machine report themselves as unsupported with the reason; nothing is downloaded there.
+
+Not exercised live: Hopper, IDA and Kuna, the interactive install dialogs on Windows terminals (they run the same code as the macOS ones, which were driven through a pseudo-terminal), and the unauthenticated GitHub API limit (60 requests per hour per address, which clai explains when it is hit).

package/README.md

@@ -151,7 +151,7 @@ Run `clai set <provider>` to add a key (`--from-env <variable>` imports one from
 </details>
 
 <details>
-<summary><b>API, keyless and local providers</b>: 30 providers including Free, Ollama, Anthropic, OpenAI, Gemini, DeepSeek, OpenRouter</summary>
+<summary><b>API, keyless and local providers</b>: 31 providers including Free, Ollama, Anthropic, OpenAI, Gemini, DeepSeek, OpenRouter, Hinoki</summary>
 
 | Provider | Provider ID | Credential or endpoint variable |
 | --- | --- | --- |
@@ -165,6 +165,7 @@ Run `clai set <provider>` to add a key (`--from-env <variable>` imports one from
 | MiniMax | `minimax` | `MINIMAX_API_KEY` |
 | Mistral | `mistral` | `MISTRAL_API_KEY`; optional `MISTRAL_BASE_URL` for regional endpoints. |
 | River | `river` | `RIVER_API_KEY`; optional `RIVER_BASE_URL`. |
+| Hinoki | `hinoki` | `HINOKI_API_KEY`; optional `HINOKI_BASE_URL`. |
 | Xiaomi MiMo | `mimo` | `MIMO_API_KEY` |
 | NVIDIA NIM | `nvidia` | `NVIDIA_API_KEY` |
 | OpenAI | `openai` | `OPENAI_API_KEY` |
@@ -202,6 +203,7 @@ Run `clai set <provider>` to add a key (`--from-env <variable>` imports one from
 | `/jobs`, `/output` | Background jobs and retained tool output |
 | `/subagents`, `/orchestrator` | Delegate work to subagents |
 | `/mcp`, `/skills` | MCP servers and Agent Skills |
+| `/rea` | Install, update and use Reverse Engineer Anything and its analysis engines; `@rea` attaches it to a prompt |
 | `/minimise` | Detach and keep the agent running |
 
 Type `/` for suggestions and `@` to mention files. `/help` lists everything and `/shortcuts` shows key bindings. See the [command reference](guides/commands.md).
@@ -212,12 +214,14 @@ Type `/` for suggestions and `@` to mention files. `/help` lists everything and
 | --- | --- |
 | [Persistent sessions](guides/sessions.md) | Detach and resume, SSH and multiple terminals, sudo, history and compaction |
 | [Working with clai](guides/usage.md) | Modes and permissions, subagents, background jobs, interactive terminals, security testing, models and key rotation, project context, skills and MCP |
+| [Security investigation skill](guides/security-skill.md) | Bundled on-demand security methodology, cross-domain research, evidence and coverage, packaging and behavioral evaluation |
 | [Terminal interface](guides/interface.md) | OpenTUI and Classic, terminals, keyboard shortcuts, paste and transcript controls |
 | [Commands](guides/commands.md) | Every slash command and CLI flag |
 | [Configuration and privacy](guides/configuration.md) | Config file, private mode, retention, credential storage and the encrypted `/creds` vault |
 | [Updating](guides/updating.md) | How `clai update` handles each installation method |
 | [Providers](PROVIDERS.md) | Account flows, API keys, endpoints and provider-specific behavior |
 | [MCP](MCP.md) | Adding, authenticating and troubleshooting MCP servers |
+| [REA](REA.md) | On-demand reverse engineering, portable installation and cache-safe agent workflows |
 
 ## Privacy and security
 

package/dist/agent/compaction/compaction-prompt.d.ts

@@ -0,0 +1,49 @@
+import type { ChatMessage } from "../../types.js";
+export type CompactionPurpose = "default" | "plan-implement";
+export interface CompactionSituation {
+    readonly turnInProgress: boolean;
+    readonly hasPriorMemory: boolean;
+    readonly promptAnchors: string;
+    readonly instructionAnchors: string;
+}
+export type CompactionSource = {
+    readonly kind: "conversation";
+} | {
+    readonly kind: "transcript";
+    readonly text: string;
+} | {
+    readonly kind: "regions";
+    readonly regions: readonly string[];
+};
+export interface CompactionPromptInput {
+    readonly source: CompactionSource;
+    readonly situation?: CompactionSituation | undefined;
+    readonly durableState?: string | undefined;
+    readonly purpose?: CompactionPurpose | undefined;
+    readonly partialSource?: boolean | undefined;
+}
+export declare const COMPACTION_SYSTEM_PROMPT: string;
+export declare function compactionSituation(messages: readonly ChatMessage[], options?: {
+    readonly turnInProgress?: boolean | undefined;
+}): CompactionSituation;
+export declare function buildCompactionUserPrompt(input: CompactionPromptInput): string;
+export declare function buildDirectCompactionPrompt(input: {
+    readonly messages: readonly ChatMessage[];
+    readonly durableState?: string | undefined;
+    readonly purpose?: CompactionPurpose | undefined;
+    readonly turnInProgress?: boolean | undefined;
+}): string;
+export declare function buildCompactionChunkPrompt(input: {
+    readonly chunk: string;
+    readonly index: number;
+    readonly total: number;
+    readonly purpose?: CompactionPurpose | undefined;
+}): string;
+export declare function buildCompactionReducePrompt(input: {
+    readonly partials: readonly string[];
+    readonly situation?: CompactionSituation | undefined;
+    readonly durableState?: string | undefined;
+    readonly purpose?: CompactionPurpose | undefined;
+}): string;
+export type CompactionRetryReason = "truncated" | "incomplete" | "reasoning-only" | "replayed";
+export declare function buildCompactionRetryPrompt(prompt: string, reason: CompactionRetryReason): string;

package/dist/agent/compaction/compaction-prompt.js

@@ -0,0 +1,164 @@
+import { compactionPromptAnchors, hasCompletedConversationTurn } from "../context/compaction-recent-history.js";
+import { inheritedInstructionAnchors } from "../context/compaction-user-instructions.js";
+import { ACTIVE_GOAL_HEADING, CONTEXT_GATHERED_HEADING, CURRENT_STATE_HEADING, isCompactionMemoryMessage, ISSUES_HEADING, PAST_WORK_HEADING, RECENT_PROMPTS_HEADING, RELEVANT_FILES_HEADING, USER_INSTRUCTIONS_HEADING, WORK_DONE_HEADING, } from "./memory-sections.js";
+export const COMPACTION_SYSTEM_PROMPT = [
+    "You write continuation memory for an autonomous coding and security agent whose conversation is being compacted.",
+    "Follow the format in the user message exactly. You are summarizing the session, not continuing it: never answer the user, call tools, continue the task, or invent findings, file contents, receipts, exit codes or completions.",
+].join("\n");
+export function compactionSituation(messages, options = {}) {
+    return {
+        turnInProgress: options.turnInProgress ?? !hasCompletedConversationTurn(messages),
+        hasPriorMemory: messages.some((message) => message.compaction !== undefined || isCompactionMemoryMessage(message)),
+        promptAnchors: compactionPromptAnchors(messages),
+        instructionAnchors: inheritedInstructionAnchors(messages),
+    };
+}
+const ROLE = [
+    "CONTEXT COMPACTION",
+    "",
+    "Pause the task for this one response. The conversation has reached its context limit and is about to be replaced by the continuation memory you write now. Afterwards the agent continues with only the system prompt, this memory, re-injected session state (active plan, durable envelope, project instructions, skills) and the most recent messages. Anything you leave out is gone, so the memory must let the agent resume exactly where it stopped, without repeating finished work, drifting from the user's intent, or forgetting a rule.",
+    "",
+    "Write the memory only. Do not answer the user, call tools, continue the work, or invent results, file contents, receipts, exit codes or completions. Use your own words.",
+];
+const PLAN_HANDOFF = [
+    "",
+    "PURPOSE: the user accepted the plan built in plan mode and the agent now implements it. The active goal is to execute that accepted plan; the plan itself is re-injected separately, so reference its tasks instead of copying them. Context gathered carries the plan-mode research evidence (for security work: targets, scope, confirmed findings, negative results and untested areas). Plan-mode restrictions such as gather-only or wait-for-approval are historical now, while engagement scope and safety rules still apply.",
+];
+function situationLines(input) {
+    const { situation, source } = input;
+    if (!situation)
+        return [];
+    const lines = ["", "SITUATION"];
+    if (input.partialSource) {
+        lines.push("- The source covers only the older part of the session; the newer turns stay in the live history right after this memory. Summarize the source completely and do not guess about the newer turns.");
+    }
+    lines.push(situation.turnInProgress
+        ? "- The agent was in the middle of the latest user request when the limit was hit. The latest user message is kept verbatim after the memory; the memory must say precisely what was in progress and what comes next."
+        : "- The latest turn ended with a final answer. Unless the conversation shows unfinished commitments, the latest task is complete.");
+    if (situation.hasPriorMemory) {
+        lines.push("- An earlier compaction memory appears in the source. It is the only record of everything before it: carry every still-relevant fact forward, merged with the newer turns and rewritten into the sections below. Move tasks that have since finished into Past completed work; never drop earlier completed work.");
+    }
+    if (source.kind === "regions") {
+        lines.push("- The source is a set of chronological region notes of one session; merge them into one memory and let later regions override earlier ones.");
+    }
+    if (situation.promptAnchors)
+        lines.push("", situation.promptAnchors);
+    if (situation.instructionAnchors)
+        lines.push("", situation.instructionAnchors);
+    return lines;
+}
+const FORMAT = [
+    "",
+    "FORMAT: write these sections in this exact order with these exact headings. Every section is required except Issues and risks, which you omit entirely when there is no genuine issue.",
+    "",
+    ACTIVE_GOAL_HEADING,
+    "The one goal the agent pursues next, as a precise, self-contained brief. Build it from the latest unfinished user task combined with every later follow-up, correction and piece of feedback; when the user changed direction mid-task, state the new direction and what it replaces. Include the definition of done (acceptance criteria and required verification such as tests, build, commit or push) and any scope limits or non-goals the user or the work established. If every task is finished, write \"No active task.\", name what was completed last, and say the agent should wait for the next request. Older finished tasks do not belong here.",
+    "",
+    USER_INSTRUCTIONS_HEADING,
+    "Rules the user gave about how to work, rewritten concisely in your own words while keeping exact values (limits, names, versions, paths, required wording). One bullet each:",
+    "- [S1] (session) a rule for all work in this session or project, such as code style, \"write like a senior developer\", \"no file over 300 lines\", git and commit rules, tools to use or avoid.",
+    "- [T1] (task: short task name) a rule that applies only within one task, such as \"while changing the UI, do not increase the composer width\".",
+    "Requests to do something (\"fix this UI\", \"change the color\", \"add /creds\") are tasks, not instructions; they belong in Active goal, Work done or Past completed work. Reuse carried IDs and give new rules the next free S or T number. Session rules last for the whole session. Keep a task rule only while its task is active or unfinished, and drop it once that task is done or abandoned. When the user changes or revokes a session rule, write \"- [S1] (retired) user: \\\"exact newer user quote\\\"\" and add the replacement as a new bullet. Rules from project instruction files (AGENTS.md, .clai/INSTRUCTIONS.md and similar) are re-injected separately, so do not copy them here, and never persist session or task rules into those files. Write \"None\" when there are no rules. Never write secret values.",
+    "",
+    CONTEXT_GATHERED_HEADING,
+    "Everything learned that the active goal depends on, so the agent never has to rediscover it: what exists and where (paths with line numbers, symbols, functions, components, config keys, endpoints, data shapes), how the relevant code or system works, why the problem happens (root cause and evidence), environment facts (stack, package manager, working commands, versions), constraints, decisions the user made or the work applied with their reasons (an approach nobody has chosen or applied yet is not a decision: put it in next steps as a proposal), and findings from tools, web research and subagents. For non-coding work, record each relevant command or tool finding with its key result. Quote code only where the exact text matters, such as a signature or an error message.",
+    "",
+    WORK_DONE_HEADING,
+    "Everything already done toward the active goal: each change as `path:line` or symbol, what changed (before → after) and why; files created or deleted; commands run with a short result (test counts, build status, commit hashes, pushes). Mark clearly what was applied and verified versus attempted, failed, reverted or only partly applied. Write \"Nothing yet.\" when no work has started.",
+    "",
+    CURRENT_STATE_HEADING,
+    "The most important section: it decides whether the agent resumes correctly. State exactly where the work stopped: what was in progress at the moment of compaction (the step, file or command, and what had and had not been applied), the workspace state (uncommitted changes, branch, running processes, background jobs, subagents and whether their results were read) and the latest user follow-up the agent must honor. Then give a numbered list of concrete next actions, starting with the very next one, each with how to verify it. Never list completed work as a next step, never re-plan finished steps, and never invent new tasks. When nothing remains, say so.",
+    "",
+    PAST_WORK_HEADING,
+    "Every earlier task in this session that is finished and is not the active goal, oldest first, one bullet per task: what the user asked, what was done (key files and symbols), the outcome and its verification, and its delivery state (uncommitted, committed with hash, pushed, PR open, merged, or unknown). Merge the entries from any earlier memory and rewrite them as tasks finish. Say when a past task relates to the active goal. Write \"None.\" when the active goal is the first task.",
+    "",
+    RELEVANT_FILES_HEADING,
+    "Files the agent needs for the active goal, most important first, as `path:line-range` — symbol and why it matters. At most about 20 entries; never list every file that was read.",
+    "",
+    ISSUES_HEADING,
+    "Only genuine open problems: failing tests, unresolved errors, blockers, risky partial edits, conflicting requirements, decisions the user must make. Omit the whole section when there are none.",
+    "",
+    `Do not write a "${RECENT_PROMPTS_HEADING.replace(/^## /, "")}" section; the application appends the verbatim prompts.`,
+];
+const QUALITY = [
+    "",
+    "QUALITY",
+    "- Be concrete and complete. Prefer exact identifiers, paths, line numbers, commands, values and error text over paraphrase; vague phrases such as \"updated the logic\" are useless to the next agent.",
+    "- Read the source to the very end: the latest tool call, result and user message define the current state. Decisions that were replaced or reverted are superseded; record only the final choice and why.",
+    "- Separate fact from intent: a decision, scope limit or design counts as made only when the user stated it or the work applied it. Your own suggestions for how to proceed belong in Current state and next steps, phrased as proposed steps.",
+    "- State each fact once, in the section where the next agent will look for it.",
+    "- Delegated workers are subagents: record each one's id and attempt, task, status, whether its result was read, and the conclusions of results already read; retained reports stay recoverable by id and attempt. Keep background jobs and Responder tasks separate from subagents. The RESPONDER RESULT LEDGER is authoritative: never describe a consumed=true result as unread, and keep unread results pending.",
+    "- Approval and mode gates: plan-mode gather-only or wait-for-approval limits end only when the user accepts the plan; research-only or no-implementation limits the user set for the current topic stay in force. Compaction never grants approval, and an answered question never authorizes new work.",
+    "- Record names and exact paths of still-relevant skills and references, not copies of their instructions. A prior load is historical, not proof that its full body survives compaction; never tell the next agent not to reload content that was lost. The application appends authoritative skill-recovery guidance.",
+    "- Refer to credentials and secrets by purpose only; their values are carried separately.",
+    "- Length: as long as needed to lose nothing that matters and no longer, usually 1,500 to 4,000 tokens and up to about 6,000 for long sessions with several tasks. Plain Markdown with bullets, no code fences around the whole memory. Finish every section and end on a complete sentence.",
+];
+function sourceLines(source) {
+    switch (source.kind) {
+        case "conversation":
+            return ["", "SOURCE: the entire conversation above this message, up to and including the most recent turn. This message itself is not part of the session."];
+        case "transcript":
+            return ["", "SOURCE (session transcript, oldest first):", "", source.text];
+        case "regions":
+            return ["", "SOURCE (region notes, oldest first):", "", source.regions.map((region, index) => `REGION ${index + 1}:\n${region}`).join("\n\n")];
+    }
+}
+export function buildCompactionUserPrompt(input) {
+    const durable = input.durableState?.trim();
+    return [
+        ...ROLE,
+        ...(input.purpose === "plan-implement" ? PLAN_HANDOFF : []),
+        ...situationLines(input),
+        ...(durable ? ["", "DURABLE STATE (authoritative for plan, task, job and result statuses):", durable] : []),
+        ...FORMAT,
+        ...QUALITY,
+        ...sourceLines(input.source),
+    ].join("\n");
+}
+export function buildDirectCompactionPrompt(input) {
+    return buildCompactionUserPrompt({
+        source: { kind: "conversation" },
+        situation: compactionSituation(input.messages, { turnInProgress: input.turnInProgress }),
+        durableState: input.durableState,
+        purpose: input.purpose,
+    });
+}
+export function buildCompactionChunkPrompt(input) {
+    return [
+        `REGION NOTES ${input.index + 1} OF ${input.total}`,
+        "",
+        "This is one chronological region of a long session that is being compacted. Write dense notes that a later pass will merge into the final memory. Summarize only what this region shows; do not answer the user, call tools, continue the work or guess about other regions.",
+        ...(input.purpose === "plan-implement" ? ["The session is a plan-mode research phase whose accepted plan will be implemented next; keep research evidence, findings, negative results and open areas."] : []),
+        "",
+        "Use these headings and keep every consequential detail:",
+        "### Tasks requested — each user request in order, with every later follow-up or correction, and whether it finished in this region.",
+        "### User instructions — each rule about how to work, quoted exactly, marked session-wide or tied to one task; prompts that ask for work are tasks, not instructions.",
+        "### Context gathered — paths with line numbers, symbols, mechanisms, root causes, environment facts, decisions with reasons, tool, web and subagent findings.",
+        "### Work done — each change as path:line or symbol (before → after), commands with short results, commits and pushes, failed or reverted attempts.",
+        "### State at the end of the region — what was in progress, pending next steps, open problems.",
+        "",
+        "Use exact identifiers. Never copy transcript lines, tool-call syntax or long output, and never write secret values.",
+        "",
+        "SOURCE (region):",
+        "",
+        input.chunk,
+    ].join("\n");
+}
+export function buildCompactionReducePrompt(input) {
+    return buildCompactionUserPrompt({
+        source: { kind: "regions", regions: input.partials },
+        situation: input.situation,
+        durableState: input.durableState,
+        purpose: input.purpose,
+    });
+}
+const RETRY_ISSUES = {
+    truncated: "The previous draft hit its output limit.",
+    "reasoning-only": "The previous draft contained no visible memory.",
+    replayed: "The previous draft copied transcript lines or tool-call syntax.",
+    incomplete: "The previous draft ended abruptly or missed required sections.",
+};
+export function buildCompactionRetryPrompt(prompt, reason) {
+    return `${prompt}\n\nQUALITY RETRY: ${RETRY_ISSUES[reason]} Write the complete memory again from the source, not as a continuation of the failed draft. Use every required section, keep every consequential fact once, and end on a complete sentence.`;
+}
+//# sourceMappingURL=compaction-prompt.js.map

package/dist/agent/compaction/compaction-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction-prompt.js","sourceRoot":"","sources":["../../../src/agent/compaction/compaction-prompt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,yCAAyC,CAAC;AAChH,OAAO,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AACzF,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACtB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAwB9B,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,kHAAkH;IAClH,kOAAkO;CACnO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,UAAU,mBAAmB,CACjC,QAAgC,EAChC,UAA6D,EAAE;IAE/D,OAAO;QACL,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,CAAC,4BAA4B,CAAC,QAAQ,CAAC;QACjF,cAAc,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,yBAAyB,CAAC,OAAO,CAAC,CAAC;QAClH,aAAa,EAAE,uBAAuB,CAAC,QAAQ,CAAC;QAChD,kBAAkB,EAAE,2BAA2B,CAAC,QAAQ,CAAC;KAC1D,CAAC;AACJ,CAAC;AAED,MAAM,IAAI,GAAG;IACX,oBAAoB;IACpB,EAAE;IACF,qhBAAqhB;IACrhB,EAAE;IACF,0KAA0K;CAC3K,CAAC;AAEF,MAAM,YAAY,GAAG;IACnB,EAAE;IACF,sgBAAsgB;CACvgB,CAAC;AAEF,SAAS,cAAc,CAAC,KAA4B;IAClD,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACpC,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAG,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,mMAAmM,CAAC,CAAC;IAClN,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,cAAc;QACjC,CAAC,CAAC,qNAAqN;QACvN,CAAC,CAAC,iIAAiI,CAAC,CAAC;IACvI,IAAI,SAAS,CAAC,cAAc,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,mTAAmT,CAAC,CAAC;IAClU,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,6IAA6I,CAAC,CAAC;IAC5J,CAAC;IACD,IAAI,SAAS,CAAC,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IACrE,IAAI,SAAS,CAAC,kBAAkB;QAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,kBAAkB,CAAC,CAAC;IAC/E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,MAAM,GAAG;IACb,EAAE;IACF,wLAAwL;IACxL,EAAE;IACF,mBAAmB;IACnB,goBAAgoB;IAChoB,EAAE;IACF,yBAAyB;IACzB,8KAA8K;IAC9K,kMAAkM;IAClM,iJAAiJ;IACjJ,yyBAAyyB;IACzyB,EAAE;IACF,wBAAwB;IACxB,2wBAA2wB;IAC3wB,EAAE;IACF,iBAAiB;IACjB,oYAAoY;IACpY,EAAE;IACF,qBAAqB;IACrB,opBAAopB;IACppB,EAAE;IACF,iBAAiB;IACjB,ueAAue;IACve,EAAE;IACF,sBAAsB;IACtB,mLAAmL;IACnL,EAAE;IACF,cAAc;IACd,kMAAkM;IAClM,EAAE;IACF,mBAAmB,sBAAsB,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,0DAA0D;CACxH,CAAC;AAEF,MAAM,OAAO,GAAG;IACd,EAAE;IACF,SAAS;IACT,wMAAwM;IACxM,2MAA2M;IAC3M,+OAA+O;IAC/O,+EAA+E;IAC/E,qZAAqZ;IACrZ,ySAAyS;IACzS,uTAAuT;IACvT,0FAA0F;IAC1F,6RAA6R;CAC9R,CAAC;AAEF,SAAS,WAAW,CAAC,MAAwB;IAC3C,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,cAAc;YACjB,OAAO,CAAC,EAAE,EAAE,+IAA+I,CAAC,CAAC;QAC/J,KAAK,YAAY;YACf,OAAO,CAAC,EAAE,EAAE,4CAA4C,EAAE,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7E,KAAK,SAAS;YACZ,OAAO,CAAC,EAAE,EAAE,sCAAsC,EAAE,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,UAAU,KAAK,GAAG,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACnJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAA4B;IACpE,MAAM,OAAO,GAAG,KAAK,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;IAC3C,OAAO;QACL,GAAG,IAAI;QACP,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,gBAAgB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,GAAG,cAAc,CAAC,KAAK,CAAC;QACxB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,wEAAwE,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3G,GAAG,MAAM;QACT,GAAG,OAAO;QACV,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC;KAC7B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,KAK3C;IACC,OAAO,yBAAyB,CAAC;QAC/B,MAAM,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE;QAChC,SAAS,EAAE,mBAAmB,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;QACxF,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,KAK1C;IACC,OAAO;QACL,gBAAgB,KAAK,CAAC,KAAK,GAAG,CAAC,OAAO,KAAK,CAAC,KAAK,EAAE;QACnD,EAAE;QACF,8QAA8Q;QAC9Q,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAC,4JAA4J,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7M,EAAE;QACF,yDAAyD;QACzD,qIAAqI;QACrI,sKAAsK;QACtK,+JAA+J;QAC/J,oJAAoJ;QACpJ,+FAA+F;QAC/F,EAAE;QACF,qHAAqH;QACrH,EAAE;QACF,kBAAkB;QAClB,EAAE;QACF,KAAK,CAAC,KAAK;KACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,KAK3C;IACC,OAAO,yBAAyB,CAAC;QAC/B,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE;QACpD,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC,CAAC;AACL,CAAC;AAID,MAAM,YAAY,GAA0C;IAC1D,SAAS,EAAE,0CAA0C;IACrD,gBAAgB,EAAE,iDAAiD;IACnE,QAAQ,EAAE,iEAAiE;IAC3E,UAAU,EAAE,gEAAgE;CAC7E,CAAC;AAEF,MAAM,UAAU,0BAA0B,CAAC,MAAc,EAAE,MAA6B;IACtF,OAAO,GAAG,MAAM,sBAAsB,YAAY,CAAC,MAAM,CAAC,8LAA8L,CAAC;AAC3P,CAAC"}

package/dist/agent/compaction/memory-sections.d.ts

@@ -0,0 +1,27 @@
+import type { ChatMessage } from "../../types.js";
+export declare const COMPACTION_MEMORY_PREFIX = "Session memory from compacted earlier turns:";
+export declare const PLAN_IMPLEMENT_MEMORY_PREFIX = "PLAN MODE HANDOFF: research memory for the accepted implementation phase. Gather-only/await-approval gates are historical; ACTIVE PLAN and SESSION STATE are authoritative:";
+export declare const LEGACY_PLAN_IMPLEMENT_MEMORY_PREFIX = "Session memory from PLAN MODE research that was used to build the comprehensive detailed plan and tasks you are seeing now (handoff to agent implement \u2014 gather-only phase is over; execute approved tasks):";
+export declare const MECHANICAL_MEMORY_PREFIX = "Earlier turns in this session, summarized";
+export declare function isCompactionMemoryMessage(message: ChatMessage): boolean;
+export declare const ACTIVE_GOAL_HEADING = "## Active goal";
+export declare const USER_INSTRUCTIONS_HEADING = "## User instructions";
+export declare const CONTEXT_GATHERED_HEADING = "## Context gathered";
+export declare const WORK_DONE_HEADING = "## Work done";
+export declare const CURRENT_STATE_HEADING = "## Current state and next steps";
+export declare const PAST_WORK_HEADING = "## Past completed work";
+export declare const RELEVANT_FILES_HEADING = "## Relevant files";
+export declare const ISSUES_HEADING = "## Issues and risks";
+export declare const RECENT_PROMPTS_HEADING = "## Last 3 user prompts (latest first)";
+export declare const MODEL_MEMORY_HEADINGS: readonly ["## Active goal", "## User instructions", "## Context gathered", "## Work done", "## Current state and next steps", "## Past completed work", "## Relevant files", "## Issues and risks"];
+export interface SectionRange {
+    readonly start: number;
+    readonly end: number;
+    readonly body: string;
+}
+export declare function sectionRanges(text: string, heading: string): SectionRange[];
+export declare function sectionBody(text: string, heading: string): string | undefined;
+export declare function replaceSections(text: string, heading: string, replacement: string): string;
+export declare function withoutSection(text: string, heading: string): string;
+export declare function insertSectionAfter(text: string, previous: readonly string[], section: string): string;
+export declare function canonicalMemoryLayout(text: string): string;