ai-runtime-engine 1.3.0 → 2.7.0

package/CHANGELOG.md

@@ -5,6 +5,567 @@ All notable changes to `ai-runtime` are documented here. The format follows
 Versioning](https://semver.org/). Development history and rationale live in
 [docs/DECISIONS.md](docs/DECISIONS.md) and [docs/PROGRESS.md](docs/PROGRESS.md).
 
+## [2.7.0] — 2026-09-04
+
+Multi-agent core. A plan step can now **delegate to an agent** — a bounded sub-task with its own plan,
+its own narrowed catalog and permissions, its own budget, and a structured report of what it found.
+Additive: with `runtime.agents` absent every prompt, key, observation, and rendered line is
+byte-identical to 2.6.0.
+
+### Added
+
+- **Agent execution as a THIRD step kind** (`skill` | `tool` | `agent`), reusing the orchestrator that
+  already exists: waves, skip-on-failed-dependency, the concurrency semaphore, and the budget gate are
+  all kind-agnostic. There is no second orchestration engine.
+- **`runtime.agents`** — `enabled`, per-task defaults (`maxToolCalls` 25, `maxDurationMs` 120s,
+  `maxInnerCalls` 3), and operator-authored `definitions`. A definition is a **ceiling**: it can remove
+  a tool but never add one, lower a cap but never raise it, drop a permission but never grant one, and
+  add a routing exclusion but never re-admit an excluded provider. `Runtime.registerAgent` does the same
+  for a library host.
+- **Findings** — an agent reports `{ type, claim, subject?, verdict? }` with two numbers that are never
+  conflated: `executionCoverage` (deterministic — how much of its plan ran) and `confidence`
+  (evidence-based belief). Conflict resolution weighs only `confidence`; coverage filters and breaks
+  ties. Evidence entries carry the validation checks that back them.
+- **Budget reservations** — an agent step reserves model calls in the pre-flight estimate and in the
+  executor's wave gate, through one shared per-step cost rule. A plan whose agents cannot fit refuses to
+  start with a truthful estimate instead of overrunning mid-run.
+- **Envelope disclosure at the approval gate** — an agent step's plan line now shows what it may spend,
+  what it may touch, and what it is allowed to do, because approving a delegation blind is approving a
+  blank cheque.
+- **Lifecycle events** `agent.task.started` / `agent.task.completed`, carrying ids and counts only.
+
+### Guarantees
+
+- **One router.** The worker never constructs an `AI`. Inner model calls go through a
+  prototype-delegating metered facade over the parent's — which is also what lets it be handed to a
+  skill as `SkillContext.ai`, so it counts the calls a skill makes on its own that the parent budget
+  cannot see today. An agent's routing may only narrow the parent's.
+- **Bounded, at depth 1, structurally.** The inner plan is generated with an empty agent list, so a
+  nested agent step is a validation error rather than a runtime check a refactor can bypass.
+- **One enforcement point.** `narrowEnvelope` derives the inner catalog, the permission clamp, the caps,
+  and the reservation, and it has exactly one caller. A skill whose declared tools escape the envelope is
+  excluded there, because a skill's own `callTool` resolves off the Runtime registry with no allowlist.
+- **Arbitrary agent output never becomes a Finding.** Candidates pass extract → output-contract validate
+  → Finding validate → persist, each with one rejection reason; a rejected candidate is an auditable
+  diagnostic and is never threaded into a prompt, an observation, or a result. A finding with no
+  evidence cannot claim belief, even with a skill-authored override.
+- **Both prompt boundaries are fenced.** A model-authored step input reaches the inner planner inside an
+  untrusted-data fence; every definition- and source-controlled string is flattened and clamped.
+- **No new status anywhere.** Every agent-task state projects onto the existing step and execution
+  vocabularies, and the table is encoded in code so it cannot drift from the docs. An interruption is
+  metadata on the record, not a state. There is no inner approval wait: a headless denial becomes a
+  first-class finding plus a fail-branch.
+- **A cancelled branch is distinguishable from a skipped one**, and `pauseExecution`/`cancelExecution`
+  now abort agent work that is actually in flight rather than only flipping a stored status.
+
+### Fixed
+
+- The resume-continue path built its own step runners with no agent runner, so a persisted plan
+  containing an agent step would have failed every one of those steps. There is now one runner source.
+- `execStatus` is exhaustive: an unrecognized orchestration status was silently persisted as
+  `waiting_for_clarification` — resumable, answerable with a text answer, and wrong.
+- The three copies of "a model call is a skill step" (estimate, wave gate, resume recomputation) are one
+  primitive. A third step kind with a non-unit cost made three copies untenable.
+
+### Notes
+
+- 796 tests pass (was 742); the runtime dependency count is unchanged (4).
+- Persistence, resume, and cancellation of agent tasks are Phase 3.5. 3.4's shapes are chosen so that
+  phase needs no breaking change: the task record is already self-identifying and JSON-serializable, and
+  the waiting/paused projections are declared but unreachable.
+
+## [2.6.0] — 2026-09-03
+
+Capability-first planning and the MCP UX. The runtime can now answer **"what does this goal need, and
+what is missing?"** before it plans — offline, for free — and tell you exactly what to grant. Additive:
+with `runtime.capabilities.planning` off (the default) the planner prompt and every result field are
+byte-identical to 2.5.1.
+
+### Added
+
+- **`runtime.capabilities.planning`** (default off) — derives the capabilities a goal needs BEFORE
+  planning, resolves them against that run's permissions, and reports the gaps. Two rungs: an **offline
+  BM25 pass over the live registry** runs first (free, deterministic, and the common path), and a single
+  model call sits under it, consulted only when the offline pass finds nothing. The model's reply is
+  filtered against the closed candidate set, so no model-authored string can reach resolution, a prompt,
+  or your terminal.
+- **A post-plan capability check** — maps each plan step's real provider to what it actually does and
+  resolves that. Zero model calls, and the only path that surfaces a genuine `permission` gap with a
+  concrete config key to grant.
+- **The gap UX.** `RuntimeResult.capabilityGaps` has been populated since 2.4.0 but was rendered
+  nowhere. `ai-runtime run`, the REPL, and both `capabilities` surfaces now print one shared block:
+  ```
+  Capabilities this goal needs:
+    ✗ commit_changes                 permission   the runtime is not allowed to do this
+    ✓ read_file                      available    tool:filesystem
+  To fix:
+    • grant permissions.gitCommit in .ai-runtime/config.yaml
+  ```
+- **`ai-runtime capabilities --actions "<goal>"`** and **`/capabilities <goal>`** — a free, offline
+  "can you do this?" pre-flight. No model call and no provider needed: it answers correctly with
+  `providers: []` and no network.
+- **REPL `/mcp` and `/mcp/<id>`** — the MCP surface inside the interactive session, reusing the exact
+  formatters the `mcp` command prints (and never opening a second Runtime).
+- **A `doctor` MCP section** — servers, state, tool counts, and grants, with any ungranted server named
+  explicitly. Read-only: `doctor` never connects, so states are as last recorded.
+
+### Guarantees
+
+- **Advisory, never authorization.** Capability planning never blocks a run, adds no orchestration
+  status, and grants nothing — the tool's own permission check remains the authority. A gap is metadata
+  plus a line in the planner prompt telling the model not to plan around it.
+- **No budget can be exceeded to answer a question about capabilities.** The model rung is skipped
+  entirely whenever a call budget is set, and on a dry run; `maxCalls` counts plan steps and cannot
+  express a pre-plan call, so declining is the fail-closed reading. Nothing rewrites a resolved policy.
+- **One router.** The model rung goes through the same `AI.run` facade as everything else, on the
+  existing `chat` task — the task registry is identical whether the flag is on or off.
+- **The goal is fenced as untrusted** in the derive prompt, and every candidate label is flattened and
+  clamped — so an MCP server's description cannot forge a row in it.
+- **Resolution and execution read the same permissions.** A run's gaps are resolved against that run's
+  merged permissions (config + per-run override, with `mcp` merged by per-server minimum), through one
+  extracted helper, so what gets reported and what the executor will allow can never disagree.
+- `MissingCapabilityReport` now has exactly **one** builder, shared by the public reporter and the run
+  path, so the two can no longer drift.
+
+### Review outcomes
+
+The phase's adversarial review pass produced 24 findings. Two were refuted by measurement (a claimed
+IDF collapse — a 306-capability registry still derives correctly, because the slate is relevance-ranked
+first; and a claimed flag-off report difference — the divergence needs duplicate suggestions, which plan
+validation cannot produce). The rest are fixed:
+
+- **No over-grant advice.** A plan step's provider can do more than the step will (`tool:filesystem`
+  provides both `read_file` and `write_file`), and lexical derivation can match a sibling. A
+  `permission` gap now survives only when the goal actually derived that capability — telling an
+  operator to grant write access for a read is worse than saying nothing. Other gap reasons (unknown /
+  unavailable / disabled) are always reported, because those block the step whatever it intends.
+- **The relevance cut is tuned by measurement against the real registry** (0.45 → 0.6): zero false
+  positives and zero misses across the goal suite, where 0.45 derived `write_file` for "read a
+  workspace file" and 0.65 lost `commit_changes` for "commit the fix and run the tests".
+- **Every budget declines the model rung**, not just a call ceiling: a cost ceiling counts, and so does a
+  ceiling set in the config file (which deliberately does not flow into `policy.maxCalls`, because
+  threading it there would newly gate orchestration for every existing config).
+- **An idempotent retry pays nothing.** Derivation now happens after the `requestId` dedup, so a retry
+  that returns the existing execution no longer spends a model call whose result is discarded.
+- A capability id from an operator `aliases` key is clamped before it reaches the derive prompt (it is
+  the one id with no charset or length guarantee); `capabilitiesOf` refuses a sanitization-colliding raw
+  id rather than answering with the incumbent provider's capabilities; the MCP grant lookup is
+  own-property checked everywhere (a server legally named `constructor` could otherwise inherit a
+  grant); `capabilities --actions --json` stays JSON on every path; a goal passed without `--actions` is
+  honored rather than discarded; `/mcp <id>` and `/capabilities <goal>` accept both the slash and space
+  forms; and `doctor` reports whether servers are live instead of a hardcoded `false`.
+
+### Notes
+
+- 741 tests pass (was 692); the runtime dependency count is unchanged (4).
+- A latent test-double defect is fixed: the MCP `hang` fixture settled only via the caller's abort
+  signal, and `AbortSignal.timeout` is unref'd — so a process whose only pending work was that promise
+  could exit with an awaiting test unresolved, cancelling it and every test after it in the file. Seen
+  once on a CI runner, nine milliseconds after the previous test passed; the mechanism is reproducible in
+  four lines of Node. The hang path now carries a ref'd backstop and the behavior is pinned.
+
+## [2.5.1] — 2026-09-03
+
+Fixes a leak that could hang a test run or a CLI invocation, found by Windows CI. No API changes.
+
+### Fixed
+
+- **A stdio child is released even when the code that owns it fails.** An MCP stdio child holds the event
+  loop open, so a manager that was not closed — because an assertion or an error unwound past the close —
+  left the process unable to exit. This is what stalled Windows CI: a platform-specific assertion failed,
+  its manager was never closed, and the run reported nothing until it was cancelled. Every spawn-owning
+  path now releases in a `finally`.
+- **A dying child's pipes can no longer raise an uncaught exception.** `stdin`/`stdout`/`stderr` each get
+  an error handler, because an EPIPE while writing into a process that just exited (or an ECONNRESET on a
+  Windows named pipe) is expected during teardown — unhandled, a stream `error` takes down the host.
+- **Pipe handles are destroyed after the child exits**, so no lingering handle can keep the event loop
+  alive on a platform where a terminated process's stdio outlives it.
+- **A flaky crypto test is deterministic** (present since 1.10.0, ~1.75% failure rate): it inspected
+  `body[10]` but substituted `body[0]`, so whenever that character already held the replacement it
+  tampered nothing and AES-GCM correctly did not throw. It now substitutes at the index it inspects,
+  asserts the ciphertext actually changed, and a companion test sweeps **every** position in the
+  envelope body.
+
+### Changed
+
+- `npm test` (and each battery) now passes `--test-timeout=120000`, and the CI job carries
+  `timeout-minutes: 15`. A future hang fails fast with the offending test's name instead of consuming a
+  runner's whole time budget.
+- The MCP stdio tests that inspect the process table now **skip on platforms that cannot be probed**
+  (the same shape as the existing symlink skip) — they assert POSIX process semantics that
+  `StdioTransport` deliberately does not use on Windows. Windows keeps three real spawn tests plus the
+  entire protocol, client, HTTP-transport, permission, and fencing suite.
+  `AI_RUNTIME_TEST_NO_PROCESS_PROBE=1` exercises the skipping path on a POSIX host.
+
+## [2.5.0] — 2026-09-03
+
+MCP connectivity — tools from external **MCP servers** become ordinary Runtime tools. There is no second
+execution path: a discovered MCP tool goes through the same `runTool` permission, approval, cancellation,
+and redaction machinery as `filesystem` or `shell`. Additive: with no `mcp:` config the subsystem is
+entirely inert.
+
+### Added
+
+- **Zero-dependency MCP client** (`src/mcp/`) — JSON-RPC 2.0 over **stdio** (newline-framed, own process
+  group) or **streamable HTTP** (JSON or SSE bodies, `Mcp-Session-Id` carried, 404 ⇒ re-initialize), with
+  version negotiation, per-call timeouts, cooperative cancellation, and concurrent request multiplexing.
+  The runtime dependency count is unchanged (4).
+- **`mcp:` config** — declare servers by transport with `command`/`args` or `url`, an optional
+  `tokenEnv` (an env-var **NAME**; a key-like value is rejected by the same guard `apiKeyEnv` uses), and
+  per-server `timeoutMs`.
+- **`permissions.mcp.servers.<id>`** — `off` | `read` | `full` (`true` ≡ full, `false` ≡ off).
+  Deny-by-default: adding or connecting a server grants **nothing**. `read` admits only tools the server
+  declares read-only; anything else needs `full`.
+- **`ai-runtime mcp`** — list servers with state, tool count, and grant; `mcp <id>` for detail and
+  redacted diagnostics; `mcp add|remove|enable|disable|test`. `mcp add` persists to the local **store**,
+  never to your config file.
+- **Action capabilities for MCP tools** — each discovered tool provides `mcp:<server>.<tool>`, with
+  availability driven by the server's lifecycle (connected ⇒ available, cache-only ⇒ unknown,
+  unreachable ⇒ unavailable, disabled ⇒ disabled).
+- **`Runtime.close()`** — releases MCP child processes. Wired into the one-shot CLI, `run`, and REPL exit,
+  with a synchronous process-exit net so a crash cannot orphan a server.
+
+### Guarantees
+
+- **MCP metadata is untrusted at every rendering point, not just call output.** Tool names, descriptions,
+  and error text pass a discovery-time normalization gate (name charset validated, control characters
+  stripped, length clamped) — a server cannot forge a catalog row or smuggle instructions. An unsafe
+  declaration is rejected and never registered; call output is `wrapUntrusted`-fenced and redacted; a
+  tool error yields a fixed taxonomy with the server's text only as a fenced diagnostic.
+- **Effects come from the live handshake, never a cache.** A cached `readOnlyHint` cannot lower the
+  permission gate; a cache-seeded tool is write-like until a live handshake re-registers it.
+- **Permissions only narrow.** `mcp` is the first nested permission dimension: it merges by per-server
+  minimum, so a per-run override can revoke a grant but never widen one.
+- **A `destructiveHint` tool always confirms**, even when its server is granted `full`.
+- **An MCP tool never shadows an existing tool** — the collision is skipped and reported.
+- Credentials are named, never valued: no token, URL, or spawn command reaches an error message, status,
+  diagnostic, warning, or the persisted store. Status reports the env-var **name** and whether it resolves.
+- All persisted MCP state (servers, enable-state, tool caches) is schema-validated on read; invalid ⇒
+  discarded and reported, never trusted.
+- Bounded by construction: 20 `tools/list` pages, 500 tools per server, a 30s default per-call timeout,
+  and a capped reconnect backoff. One server failing never affects another.
+- A failed handshake releases its connection, so a stdio child whose `initialize` times out is closed
+  rather than left running; and removing one server never strips a sibling whose id shares its prefix.
+- **A server's JSON Schema is prompt text too**, so it is deep-sanitized: every string inside it is
+  flattened and clamped, and its depth, node count, and key count are bounded — an unbounded schema
+  would otherwise inflate every planning call that declares the tool.
+- **Deny-by-default holds for every key, not just configured ones.** The grant map is prototype-free, so
+  a lookup of `constructor` (or any unconfigured server) can only answer "no grant", and a value that is
+  not exactly `off`/`read`/`full` collapses to `off`.
+- **A cached annotation can never relax a gate in either direction.** A stale `readOnlyHint` cannot lower
+  the permission gate and a stale `destructiveHint: false` cannot remove the confirmation; with no live
+  connection both gates fail closed. The adapter reads live annotations at call time, not a snapshot.
+- **Capability resolution honors the MCP grant**, so an ungranted server's tools are a `permission` gap
+  instead of being planned against and then refused by the executor.
+- The model-facing declaration path (`AI.run({ mcp: true })`) honors the same read/full split, emits
+  already-namespaced names, and is revoked when a server is disabled or removed.
+- A live discovery is authoritative: a tool the server no longer offers is unregistered rather than
+  lingering as available. Re-enabling a server restores its tools.
+- Correlation is response-only, so a server-initiated request can no longer resolve a pending call; an
+  already-aborted call never reaches the wire; abort listeners are released on completion.
+- A dynamic server id is validated exactly like a config one, `--token-env` refuses a token value, and
+  the persisted `servers` file is validated against the same schema as the config file.
+- Every Runtime-based CLI command releases its Runtime on every path (`withRuntime`), so no command can
+  leave a live child holding the process open. A missing stdio command fails immediately instead of
+  waiting out the request timeout.
+
+### Notes
+
+- MCP connects **lazily**: a one-shot CLI command that cannot execute tools pays nothing. The REPL
+  connects eagerly, once, at session start.
+- `mcp:` is a Runtime-config key. `AI.load()` (the plain router loader) still rejects it.
+- Public surface: the config/status types, `mcpToolId`, `MCP_PROTOCOL_VERSION`, and
+  `clampMcpPermissions`. The client, transports, and manager internals stay private so the wire
+  implementation can change without a breaking release.
+
+## [2.4.0] — 2026-09-03
+
+Action capabilities — the Runtime now reasons about **what it can do** (`read_file`, `run_tests`,
+`read_repository`), independent of which tool or skill provides it. Additive: with no `capabilities`
+config, planning and every existing surface behave exactly as 2.3.0.
+
+### Added
+
+- **Action-capability layer** (`src/capabilities/`) — a first-class capability model distinct from the
+  router's model-capability system: a shipped curated vocabulary, per-provider availability + evidence,
+  and a fully deterministic 8-step resolution (availability → operator pin → evidence → source → id).
+- **Declarations** — tools, skills, and skill manifests may declare `provides: [{ id, effects }]`;
+  anything undeclared still surfaces under its own namespace, so nothing is ever invisible.
+- **`runtime.capabilities`** config — `catalog` (enrich the planner prompt with capabilities and an
+  explicit "unavailable, do not use" section), `aliases` (an operator claims a curated id for a
+  provider), and `pins` (an operator selects among eligible providers).
+- **Structured capability gaps** — an unknown plan reference now also produces a machine-readable gap
+  (`RuntimeResult.capabilityGaps`) with actionable suggestions, instead of only a raw error string.
+- **`ai-runtime capabilities --actions`** and the REPL **`/capabilities`** — see every action capability,
+  its providers, effects, availability, and evidence.
+
+### Guarantees
+
+- **`effects` is advisory metadata, never authorization.** Actual operation permission is always enforced
+  by the selected Tool/Skill execution path.
+- **Capability resolution never grants permission**, and a bare curated id can be claimed only by an
+  in-tree builtin or an operator config alias — third-party code is always namespaced to its own source.
+- Source-controlled text is clamped before it reaches a model prompt.
+
+## [2.3.0] — 2026-09-01
+
+Release automation — push a tag, and CI publishes. Repo tooling only; nothing in the published package
+changes.
+
+### Added
+
+- **`.github/workflows/release.yml`** — push `v<version>` to publish `ai-runtime-engine`, or `pack-v<version>`
+  to publish `ai-runtime-developer-skills`. Each release runs typecheck + tests + build and a **version-sync
+  guard** (the tag must equal `package.json`, `cli.ts`, and the CHANGELOG — it fails fast otherwise) before
+  `npm publish`. A `409 "previously staged"` is treated as done, not a failure. A manual `workflow_dispatch`
+  run performs a `--dry-run` to prove the pipeline without releasing.
+
+### Notes
+
+- **One-time setup:** add an npm granular access token (publish permission, 2FA-bypass) as the repo secret
+  `NPM_TOKEN`. The manual publish flow documented in `docs/handbook/09-npm.md` remains a supported fallback.
+
+## [2.2.0] — 2026-09-01
+
+A richer interactive terminal — color, tab-completion, history, and a live spinner. Zero new dependencies,
+and all of it is gated on an interactive TTY, so piped/CI output is unchanged.
+
+### Added
+
+- **Colored** banner and prompt (disabled automatically when not a TTY, when `NO_COLOR` is set, or on a
+  `dumb` terminal).
+- **Slash-command tab-completion** — press Tab after `/` to complete a command (only bare commands, never
+  your natural-language input or command arguments).
+- **Persistent command history** across REPL sessions (best-effort, stored under the project cache dir).
+- An in-place **spinner** while a request is in flight.
+
+### Unchanged
+
+- The REPL command surface (`ReplSession`) and all output redaction are exactly as before; nothing about
+  scripted/piped usage changes.
+
+## [2.1.0] — 2026-09-01
+
+Generative seams — draft a skill from a goal, and let a model fill gaps in a provider adapter. Additive:
+both emit **validated config/manifests, never code**, and the scaffolder **writes nothing without your
+confirmation**.
+
+### Added
+
+- **`ai-runtime skills --scaffold "<goal>"`** — a model drafts a `*.skill.yaml` manifest that composes your
+  registered tools. It is refused unless it passes shape validation, names only real tools, has a safe
+  kebab-case id, and compiles — then it is printed and **saved only after you confirm** (`--yes` to skip the
+  prompt) into `.ai-runtime/skills/`. API: `Runtime.scaffoldSkill(goal)` + `saveScaffoldedSkill(manifest)`,
+  and `generateSkillManifest`.
+- **`suggestProviderConfig(analysis, ai)`** — an opt-in AI rung over `generateProviderConfig` that proposes a
+  model list when an OpenAPI spec doesn't enumerate one. The output is always the deterministic, **validated**
+  `ProviderConfig` — a bad suggestion can only propose model-id strings, never an unvalidated config.
+
+### Guarantees
+
+- Nothing generated is executed as code — manifests are data parsed by `parseManifest`; adapter output is a
+  validated `ProviderConfig`. Goals and specs are fenced as untrusted input.
+- The scaffolder never writes without confirmation, and a scaffolded id can never escape the skills directory.
+
+## [2.0.0] — 2026-09-01
+
+**The ecosystem milestone.** A first-party developer skill pack ships alongside the engine. This is **not a
+breaking change** — no engine code changed, the public API is fully backward compatible, and every 1.x
+config keeps working. 2.0 marks the start of the pack ecosystem.
+
+### Added
+
+- **`ai-runtime-developer-skills`** (published separately, `v1.0.0`) — a dependency-free developer skill pack
+  loaded via the existing `skills: { packages: [...] }` mechanism. Five skills, each fencing untrusted input
+  and **validating by evidence**:
+  - **`code-review`** — structured findings for a file or files (evidence: bytes read + ≥1 parsed finding).
+  - **`refactor`** — proposes a refactor toward a goal and **never writes** (returns `data.proposal`).
+  - **`migration-planner`** — an ordered migration plan for a manifest.
+  - **`dependency-analyzer`** — enumerates dependencies, cross-checked against the real manifest count.
+  - **`debugger`** — hypotheses + concrete next checks for an error.
+
+### Unchanged
+
+- The `ai-runtime-engine` public API, config schema, and CLI are all backward compatible with 1.x. The pack
+  is **not** bundled into the engine; install it separately.
+
+## [1.11.0] — 2026-09-01
+
+Scale & ops — per-tool/skill/provider concurrency caps and an OTLP telemetry exporter. Fully additive and
+opt-in: with no `concurrency` config and no `otlp` sink, behavior is byte-identical to 1.10.
+
+### Added
+
+- **`runtime.concurrency`** — cap how much runs at once: `maxParallelSteps` (orchestrator batch bound, a
+  config rung under the per-run override), `perTool` / `perSkill` (cap concurrent uses of a given tool/skill
+  within a wave), and `perProvider` (cap concurrent calls to a given provider across the router, under
+  fan-out). Backed by a small zero-dep `KeyedSemaphore`.
+- **`telemetry.sink: 'otlp'`** (+ `endpoint`, optional `headersEnv`) — an OpenTelemetry-shaped exporter that
+  batches the routing/health metadata events and POSTs them to an OTLP/HTTP endpoint. Metadata only, redacted,
+  and **all IO is swallowed** so telemetry never fails a run. The auth header value is read from the env var
+  **named** by `headersEnv` (never a value in config).
+- New public exports: `KeyedSemaphore` (`util/semaphore.ts`), `OtlpSink`, `FileSink`.
+
+### Guarantees
+
+- No `concurrency` config ⇒ scheduling is unchanged; no `otlp` sink ⇒ the sink chain is unchanged.
+- A capped tool/skill/provider still completes every step/call — the cap serializes, it never drops work.
+
+## [1.10.0] — 2026-09-01
+
+Encryption at rest — transparently encrypt the local store with a key you control. Fully additive and
+opt-in: with no `storage` config, the store stays plaintext exactly as before.
+
+### Added
+
+- **`runtime.storage: { encrypt: true, keyEnv: "<ENV>" }`** — transparently **AES-256-GCM**-encrypts every
+  store file (memory, conversations, executions, artifacts, …). The key is read from the env var **named**
+  by `keyEnv` (never a value); a missing key with `encrypt:true` is a hard config error at load. Zero new
+  dependencies (`node:crypto`).
+- New public exports: `makeCodec`, `deriveKey`, `encryptString`, `decryptString`, `ENVELOPE_PREFIX`,
+  `ContentCodec` (`store/crypto.ts`).
+
+### Guarantees
+
+- **Mixed store** — records written before encryption still read after you enable it; new writes are
+  encrypted. A wrong key surfaces as store corruption (reported by the integrity check), never wrong data.
+- **`meta.json` stays plaintext** so version/migration always works; stateless mode is unaffected.
+- The key lives only in memory — never written to disk, logged, put in telemetry, or included in an error.
+- Not configured ⇒ byte-identical to 1.9.
+
+## [1.9.0] — 2026-09-01
+
+Organization memory scope — a shared memory store above user/project/repository, for facts that belong to
+a whole team. Fully additive: with no `organization` configured, memory behaves exactly as 1.8.
+
+### Added
+
+- **`runtime.organization: "<name>"`** — enables the new **`organization`** memory scope, a store *above*
+  user/project/repository. Its id is **name-derived**, so every project and repo that configures the same
+  organization name shares one org store; different names never share, and project/repo isolation is
+  unchanged. `remember({ scope: 'organization' })`, search, delete-cascade, conflict-supersession, temporal
+  purge, and the integrity check all span the org area **when configured**.
+- New public export **`organizationId`** (`store/paths.ts`); `info` / `doctor` show the org store path when
+  configured.
+
+### Guarantees
+
+- **Not configured ⇒ nothing changes** — the org area is never traversed, and behavior is byte-identical to 1.8.
+- `remember({ scope: 'organization' })` with **no org configured throws a clear error** rather than silently
+  writing the fact to the project store.
+
+## [1.8.0] — 2026-09-01
+
+Smarter context compiler — optional model-verified loss checking and abstractive summarization. Fully
+additive and opt-in: with both flags unset, context compilation is byte-identical to 1.7.
+
+### Added
+
+- **`runtime.context.verifyLoss: true`** — after the deterministic compile, a model checks whether anything
+  task-critical was dropped and **appends** a `model-loss-verify` check to the context validation. It
+  **never blocks**: any budget / parse / model failure records an `inconclusive` (ok) check and leaves the
+  deterministic validation result untouched. New public export **`verifyContextLoss`**.
+- **`runtime.context.summarize: true`** — before compiling, over-budget **non-critical** blocks are
+  abstractively shortened by one model call each. `critical` blocks are never summarized, originals are
+  never mutated, a summary is used only if it actually shrinks the block, and any failure falls back to the
+  original (deterministic truncation then applies). New public export **`summarizeOverBudget`**.
+
+### Guarantees
+
+- Neither feature runs on a **dry run** (a dry run still makes zero model calls).
+- Both `wrapUntrusted`-fence the block/context text before it enters a prompt.
+- The loss verifier compares against the **true pre-summary originals**, so it catches loss from
+  summarization as well as from compilation.
+
+## [1.7.0] — 2026-09-01
+
+AI-assisted intent classification — a model picks the mode when the offline heuristic is unsure. Fully
+additive and opt-in: with `intent.aiFallback` unset, mode detection is byte-identical to 1.6.
+
+### Added
+
+- **`runtime.intent.aiFallback: true`** — when the deterministic heuristic classifier is *ambiguous*, the
+  Runtime consults **one** model call to choose the mode. A **confident** heuristic result pays **zero**
+  model cost (it is returned verbatim). Any model failure, unparseable output, or out-of-range mode degrades
+  back to the heuristic — the enhancement never breaks a run.
+- New public export **`AIIntentClassifier`** (`runtime/intent/aiClassifier.ts`) — implements the existing
+  `IntentClassifier` seam; usable directly via `RuntimeOptions.classifier` too.
+
+### Guarantees
+
+- **Precedence intact** — an explicit / config / env mode never reaches the classifier.
+- **Security** — the user's request is `wrapUntrusted`-fenced before it enters the classifier prompt (a
+  request is data to classify, never instructions), and the chosen mode is validated against the known modes.
+
+## [1.6.0] — 2026-09-01
+
+Semantic memory retrieval — rank durable facts by meaning, not just keywords. Fully additive: with no
+`embedding` config, memory retrieval is byte-identical to 1.5 (BM25 keyword ranking).
+
+### Added
+
+- **`runtime.embedding`** config — opt in to semantic retrieval: `{ provider: 'local' }` uses the zero-dep,
+  deterministic **`HashEmbedder`** (offline, no key); `{ provider: 'openai-compatible', baseUrl, apiKeyEnv,
+  model? }` calls a `POST {baseUrl}/embeddings` endpoint via **`HttpEmbedder`** (key by **env NAME** only,
+  never a value; the request URL is kept out of every error). Absent → BM25 exactly as before.
+- **`MemoryStore.searchSemantic(query, opts)`** — the async vector path: the *same* filter stage as
+  `search()` (scope / confidence / temporal / supersession / domain), then **cosine-similarity** ranking
+  over embeddings. `Runtime` chat retrieval and the REPL **`/memory search`** use it automatically when an
+  embedder is configured. Candidate vectors are cached per fact text (per instance).
+- New public exports: `cosineSimilarity`, `semanticRank` (`memory/semantic.ts`), `HashEmbedder`,
+  `HttpEmbedder`.
+
+### Guarantees
+
+- **`search()` is unchanged** — still synchronous BM25, the frozen public API since 1.0.
+- **Retrieval never breaks a run.** Any embedder problem — network failure, malformed response, an empty or
+  non-finite vector — **degrades to BM25**, never an error and never a silently-empty result.
+
+## [1.5.0] — 2026-09-01
+
+Model routing profiles — route your own way with a `models.md` file. Additive: with no file, routing is
+identical to 1.4.
+
+### Added
+
+- **`models.md`** (workspace root or `.ai-runtime/models.md`) — a friendly per-mode / per-task mapping of
+  which model to use, resolved through the router's existing controls (no second router). Sections
+  `## By mode` and `## By task`; each entry is a **soft prefer** (default), a **hard pin** (`=provider:model`
+  or `pin:`), or a **strategy** keyword (`best`/`fastest`/`cheapest`/`highest-quality`/`local-only`/… or
+  `free` → cheapest). Example: *chat → free, plan → a strong model, execute → model X, a task → a specific
+  model.* Precedence: **explicit per-run > `models.md` > config > defaults**; a `## By task` entry wins over
+  `## By mode`; a prefer never re-admits an excluded model.
+- **`ai-runtime models --profile`** prints the resolved profile; **`init`** scaffolds a commented
+  `models.md`; `runtime.modelProfile()` exposes it. `## By mode` steers Runtime modes; `## By task` steers
+  router tasks via `ai-runtime route <task>` (and any `AI.run({ task })` caller).
+
+**Scope:** in chat mode and for route tasks, all three directive kinds apply; orchestration modes
+(plan/execute/orchestrate/agent/debug) honor the **soft prefer** (a per-mode hard pin/strategy is not
+applied there — the planner and skills pick their own models).
+
+## [1.4.0] — 2026-09-01
+
+Budget-aware phased execution. When a task would need more model calls than your budget allows, it no
+longer fails partway — it tells you, and lets you run it in phases. Additive: with no call budget set,
+behavior is identical to 1.3.
+
+### Added
+
+- **Budget-aware orchestration** — set a call budget with `AI_MAX_CALLS` (or per-run `maxCalls`). When a
+  plan's estimated model calls exceed it, the run **notifies instead of failing**: it reports the estimate
+  and waits, executing nothing, so you can either raise the budget and re-run, or run what fits with
+  `--partial`. A `--partial` run executes the phases that fit the budget, checkpoints, and **pauses
+  resumably** (`waiting_for_budget`, a first-class non-failure) — raise `AI_MAX_CALLS` and
+  `resume-execution <id>` to continue from where it stopped. A phase is a plan wave; a skill step counts as
+  one model call, tool steps are free.
+- **`run --partial`**, the REPL **`/budget`** command (shows `AI_MAX_CALLS` / `AI_MAX_COST_USD`), and an
+  over-budget resume hint.
+
+### Fixed
+
+- An **approval-gated** over-budget plan now respects the call budget on resume (it previously ran to
+  completion, ignoring the budget, because the approval gate was reached before the budget check).
+
 ## [1.3.0] — 2026-09-01
 
 Token-by-token streaming. Additive and backward compatible — every new field is optional and, with
@@ -130,6 +691,23 @@ Initial release: the provider-agnostic AI **router** — capability-based routin
 scoring, evidence validation, fallback, health tracking, learning-based scoring, multi-model verification,
 budgets, MCP tools, OpenAPI-based adapter generation, and the `AI` class + CLI.
 
+[2.7.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.7.0
+[2.6.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.6.0
+[2.5.1]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.5.1
+[2.5.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.5.0
+[2.4.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.4.0
+[2.3.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.3.0
+[2.2.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.2.0
+[2.1.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.1.0
+[2.0.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.0.0
+[1.11.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.11.0
+[1.10.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.10.0
+[1.9.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.9.0
+[1.8.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.8.0
+[1.7.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.7.0
+[1.6.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.6.0
+[1.5.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.5.0
+[1.4.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.4.0
 [1.3.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.3.0
 [1.2.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.2.0
 [1.1.1]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.1.1