diff --git a/apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md b/apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md index 4500f93f08..43ad855f60 100644 --- a/apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md +++ b/apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md @@ -1,26 +1,27 @@ # Managed npm ACP runtimes Kandev invokes these managed npm-provided ACP runtimes with the exact effective -version. The default values below are the reviewed pins in -`managed_npm_runtime_versions.json` at this commit. An operator selection takes -precedence for the current default generation. It remains effective until -**Use Kandev default** clears it or a later shipped package/default generation -resets it during startup. +version. The current default values are in the +[managed runtime catalogue](managed_npm_runtime_versions.json). An operator +selection takes precedence for the current default generation. It remains +effective until **Use Kandev default** clears it or a later shipped +package/default generation resets it during startup. -| Agent | Package | Default version | ACP arguments | -| --- | --- | --- | --- | -| Claude | `@agentclientprotocol/claude-agent-acp` | `0.75.1` | none | -| Codex | `@agentclientprotocol/codex-acp` | `1.10.0` | none | -| OpenCode | `opencode-ai` | `1.18.29` | `acp --print-logs --log-level ERROR` | -| Copilot | `@github/copilot` | `1.0.83` | `--acp` | -| Gemini | `@google/gemini-cli` | `0.58.0` | `--acp` | -| Pi | `pi-acp` | `0.0.33` | none | +| Agent | Package | ACP arguments | +| --- | --- | --- | +| Claude | `@agentclientprotocol/claude-agent-acp` | none | +| Codex | `@agentclientprotocol/codex-acp` | none | +| OpenCode | `opencode-ai` | `acp --print-logs --log-level ERROR` | +| Copilot | `@github/copilot` | `--acp` | +| Gemini | `@google/gemini-cli` | `--acp` | +| Pi | `pi-acp` | none | Normal capability probes, sessions, container commands, and one-shot inference -use `npx --yes --prefer-offline package@effective-version` with the ACP -arguments above. For example, an unmodified Claude installation currently -launches `npx --yes --prefer-offline @agentclientprotocol/claude-agent-acp@0.75.1`. -OpenCode's error-only log flags +use `npx --yes --prefer-offline package@` with the ACP +arguments above. For example, an unmodified Claude installation launches +`npx --yes --prefer-offline @agentclientprotocol/claude-agent-acp@`. +The `` placeholder resolves at launch to the exact Kandev +default or the exact operator selection. OpenCode's error-only log flags are part of its managed command so agentctl can observe terminal provider diagnostics without reading OpenCode's private log files. The exact top-level package is pinned, but npm transitive ranges, its cache, and the registry still @@ -40,7 +41,7 @@ the registry, and the selected version remain unchanged. The **Update agent** action in Settings is the explicit freshness boundary for the Kandev host. Its candidate preparation resolves the requested trusted -`package@effective-version` with online preference, then launches a fresh ACP +`package@` with online preference, then launches a fresh ACP capability probe. Successful probes replace the advertised version, models, modes, commands, and configuration options used for later launches. Already-running sessions continue with their existing process. The normal diff --git a/docs/decisions/0034-agentclientprotocol-codex-acp.md b/docs/decisions/0034-agentclientprotocol-codex-acp.md index b0d8cefa62..37875b0616 100644 --- a/docs/decisions/0034-agentclientprotocol-codex-acp.md +++ b/docs/decisions/0034-agentclientprotocol-codex-acp.md @@ -12,10 +12,12 @@ Kandev's `codex-acp` agent previously launched `@zed-industries/codex-acp`. That Kandev's `codex-acp` agent launches the exact effective version of `@agentclientprotocol/codex-acp` for ACP chat and one-shot inference sessions. -The reviewed Kandev default is currently `1.10.0`; an install-wide operator -selection can override it. Normal launches prefer npm's execution cache. The -install script still installs `@openai/codex` for `codex login`; that native -authentication helper is separate from the managed ACP runtime. +The reviewed Kandev default is listed in the [managed runtime +catalogue](../../apps/backend/internal/agent/agents/managed_npm_runtime_versions.json). +An install-wide operator selection can override it. Normal launches prefer +npm's execution cache. The install script still installs `@openai/codex` for +`codex login`. That native authentication helper is separate from the managed +ACP runtime. The host operator can deliberately refresh the ACP package through **Settings > Agents > Update agent**. Kandev then re-probes the bridge and diff --git a/docs/plans/managed-runtime-pin-docs/plan.md b/docs/plans/managed-runtime-pin-docs/plan.md new file mode 100644 index 0000000000..3150f31867 --- /dev/null +++ b/docs/plans/managed-runtime-pin-docs/plan.md @@ -0,0 +1,132 @@ +--- +created: 2026-09-11 +status: complete +requirements: + - REQ-AGENTS-RUNTIME-UPDATES-001 +system_design: + - ../../specs/agents/system-design/runtime-updates-01.md +legacy_specs: [] +--- + +# Implementation Plan: Remove duplicated runtime defaults + +## Overview + +Replace current-version claims in three documents with links to the runtime +catalogue. Preserve exact versions that identify historical experiments. +One sequential work order completes this documentation repair. + +## Evidence and root cause + +[PR 3606](https://github.com/kdlbs/kandev/pull/3606) changes only +`apps/backend/internal/agent/agents/managed_npm_runtime_versions.json`. +Its [review comment](https://github.com/kdlbs/kandev/pull/3606#discussion_r3989535885) +identifies stale defaults in three documents. + +The updater writes the JSON catalogue. The workflow stages only that file. +Separate prose and a table duplicate the current defaults without an update +mechanism. Each version change can therefore leave those claims stale. + +The read-only reproduction compares the PR catalogue with these claims: + +- `ACP_BRIDGE_VERSIONS.md` lists six default versions and a concrete Claude + launch example as current. +- ADR 0034 calls Codex `1.10.0` the current default. +- The timeout design calls Claude `0.75.1` the default at this commit. + That same version also identifies the binary used in historical experiments. + +## Requirement conformance + +The agents system owns the managed runtime catalogue and update lifecycle. +[REQ-AGENTS-RUNTIME-UPDATES-001](../../specs/agents/requirements/runtime-updates.md) +already defines exact defaults (`AC-AGENTS-RUNTIME-UPDATES-001.5`) and the grouped +maintenance PR (`AC-AGENTS-RUNTIME-UPDATES-001.9`). The implementation follows +those criteria. This repair corrects descriptions of that implementation. + +No new product requirement or ADR is necessary. The existing +[system design](../../specs/agents/system-design/runtime-updates-01.md#scheduled-pin-update-workflow) +continues to describe the updater. The +[token decision](../../decisions/2026-09-04-use-repository-token-for-runtime-pin-prs.md) +continues to govern workflow authorization. + +The related packages are `managed-runtime-version-awareness` and +`managed-runtime-pin-workflow-auth`. This package does not reopen their runtime +or workflow work orders or replace their recorded results. + +## Scope + +### In scope + +- Link current defaults directly to the JSON catalogue in all three documents. +- Preserve the agent names, package names, ACP arguments, and effective-version semantics. +- Identify the timeout experiments as historical evidence for their exact tested binary. + +### Out of scope + +- Version bumps, runtime code, updater code, or workflow changes. +- Generated documentation tables or a general documentation scanner. +- New timeout experiments or changes to their recorded results. +- UI changes, browser tests, and public website documentation. +- Pushing, merging, rerunning PR 3606, or replying to its review thread during implementation. + +## Technical approach + +In `apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md`, remove the +default-version column. Link to the adjacent JSON catalogue for current +defaults. Use `@` in the Claude command example and explain +that the placeholder represents the resolved exact version. + +In `docs/decisions/0034-agentclientprotocol-codex-acp.md`, replace the numeric +current-default claim with a relative catalogue link. Preserve the decision, +package identity, and operator-selection semantics. + +In `docs/specs/agents/system-design/mcp-timeout-budgets.md`, keep `0.75.1`, +`0.3.257`, the binary path, and the experiment results. Remove the claim that +the experiment version is the current default. Link current defaults to the +catalogue and state that the evidence concerns the tested version. + +The workflow requires no change. After this repair reaches `main`, its next +run starts from documentation that does not duplicate current version values. +A fix applied only to the automation branch can disappear because the workflow +recreates that branch from `origin/main`. + +## Tests + +The regression check is the **current-default documentation audit** in Task 01. +Before the correction, it finds the three current-version claims. After the +correction, those claims are absent and all three catalogue links resolve. +This documentation-only repair uses direct inspection instead of permanent +tests that assert prose wording. + +Existing updater fixtures cover changed and unchanged catalogues for +`AC-AGENTS-RUNTIME-UPDATES-001.9`. The existing workflow contract suite covers +the grouped PR and validation sequence. These checks supplement the document +audit without changing their test files. + +No E2E test is necessary because runtime and rendered UI behavior do not change. + +## Work orders + +- [x] [Task 01: Remove duplicated runtime defaults](task-01-remove-duplicated-defaults.md) + +## Verification results + +Package and implementation validation on 2026-09-11: + +- `python3 scripts/lint-spec-files.py --all`: passed. +- `node --test scripts/update-agent-runtime-pins.test.mjs`: 7 tests passed. +- `python3 .github/scripts/update-agent-runtime-pins-workflow-contract_test.py`: 9 tests passed. +- The current-default documentation audit passed after the three corrections. +- All three catalogue links resolve to + `apps/backend/internal/agent/agents/managed_npm_runtime_versions.json`. +- `make -C apps/backend build`: passed. The build reported non-fatal missing + `codesign`/`rcodesign` warnings for Darwin artifacts. +- `git diff --check`: passed. +- `git status --short`: contains only the three target documents and this plan package. +- Requirement IDs, acceptance IDs, and the system-design path exist. + +## Risks + +- A broad version replacement can falsely imply that newer runtimes passed old experiments. +- Relative links must resolve from each document, including the deeply nested timeout design. +- This repair removes the known recurring cause. It cannot guarantee that future reviews contain no other findings. diff --git a/docs/plans/managed-runtime-pin-docs/task-01-remove-duplicated-defaults.md b/docs/plans/managed-runtime-pin-docs/task-01-remove-duplicated-defaults.md new file mode 100644 index 0000000000..c6210ad3d6 --- /dev/null +++ b/docs/plans/managed-runtime-pin-docs/task-01-remove-duplicated-defaults.md @@ -0,0 +1,136 @@ +--- +id: "01-remove-duplicated-defaults" +title: "Remove duplicated runtime defaults" +status: done +wave: 1 +depends_on: [] +plan: "plan.md" +requirements: + - REQ-AGENTS-RUNTIME-UPDATES-001 +acceptance_criteria: + - AC-AGENTS-RUNTIME-UPDATES-001.5 + - AC-AGENTS-RUNTIME-UPDATES-001.9 +system_design: + - ../../specs/agents/system-design/runtime-updates-01.md +--- + +# Task 01: Remove duplicated runtime defaults + +## Summary + +Make the JSON catalogue the reference for current runtime defaults in three +documents. Preserve exact historical versions and the existing runtime behavior. + +## In scope + +- Remove the default-version column from the ACP runtime table. +- Replace the concrete current Claude command with an explained effective-version placeholder. +- Replace the ADR's current Codex version with a catalogue link. +- Separate the timeout experiment's tested version from the current default. +- Use relative Markdown links to the JSON catalogue in all three documents. + +## Out of scope + +Runtime code, catalogue values, workflow changes, generated tables, permanent +test changes, public website changes, and GitHub mutations are excluded. + +## Acceptance + +1. All three documents link to the existing JSON catalogue for current defaults. + The runtime table and launch example contain no duplicated default numbers. +2. The timeout document retains the exact tested versions, binary path, and + experiment results. It makes no claim that those versions remain current. +3. Package names, ACP arguments, effective-version semantics, and the JSON-only + maintenance path remain unchanged. All listed verification commands pass. + +## Verification + +Run all commands from the repository root. + +### Current-default documentation audit + +Before editing, run this search and record the stale claims: + +```bash +rtk proxy rg -n -A 3 -B 2 'at this commit|currently|pinned at|Default version' apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md docs/decisions/0034-agentclientprotocol-codex-acp.md docs/specs/agents/system-design/mcp-timeout-budgets.md +``` + +After editing, repeat the search. Inspect any remaining matches in context. +The timeout document can still describe unrelated settings as currently unset. +No match can assert that a literal runtime version is the current default. + +Run this search to inspect the links and preserved experiment identifiers: + +```bash +rtk proxy rg -n 'managed_npm_runtime_versions.json|0\.75\.1|0\.3\.257|effective-version' apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md docs/decisions/0034-agentclientprotocol-codex-acp.md docs/specs/agents/system-design/mcp-timeout-budgets.md +``` + +Resolve each Markdown link relative to its document. All three must reach +`apps/backend/internal/agent/agents/managed_npm_runtime_versions.json`. +Inspect the diff to verify that experiment measurements and conclusions remain intact. + +### Existing automated checks + +```bash +rtk proxy node --test scripts/update-agent-runtime-pins.test.mjs +rtk proxy python3 .github/scripts/update-agent-runtime-pins-workflow-contract_test.py +rtk proxy python3 scripts/lint-spec-files.py --all +rtk proxy git diff --check +rtk proxy git diff --stat +rtk proxy git status --short +``` + +The final diff contains only the three documentation corrections and package +status updates. Record each result before marking this work order done. + +## Files likely touched + +- `apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md` +- `docs/decisions/0034-agentclientprotocol-codex-acp.md` +- `docs/specs/agents/system-design/mcp-timeout-budgets.md` +- `docs/plans/managed-runtime-pin-docs/plan.md` +- `docs/plans/managed-runtime-pin-docs/task-01-remove-duplicated-defaults.md` + +## Dependencies + +None. The completed documentation repair must reach `main` before a scheduled +run can inherit it. Publication remains a separate delivery step. + +## Risks + +Global version replacements can corrupt historical evidence. A repair confined +to the bot branch can disappear on the next workflow run. + +## Parallelism + +`sequential` + +## Inputs + +- [Runtime requirements](../../specs/agents/requirements/runtime-updates.md), criteria 001.5 and 001.9. +- [Scheduled update design](../../specs/agents/system-design/runtime-updates-01.md#scheduled-pin-update-workflow). +- [Review evidence and technical approach](plan.md). +- `scripts/update-agent-runtime-pins.mjs` and its existing fixture tests. +- `.github/workflows/update-agent-runtime-pins.yml` and its existing contract tests. + +## Results + +Implemented the documentation repair. The ACP runtime table now links to the +JSON catalogue and contains no duplicated default versions. The Claude launch +example uses an effective-version placeholder with its exact-version meaning. +ADR 0034 links to the catalogue instead of naming a current Codex version. +The timeout design preserves the tested Claude and SDK versions, binary path, +measurements, and conclusions while identifying them as historical experiment +evidence. + +Verification passed: + +- `node --test scripts/update-agent-runtime-pins.test.mjs`: 7 tests passed. +- `python3 .github/scripts/update-agent-runtime-pins-workflow-contract_test.py`: 9 tests passed. +- `python3 scripts/lint-spec-files.py --all`: passed. +- `make -C apps/backend build`: passed. The build reported non-fatal missing + `codesign`/`rcodesign` warnings for Darwin artifacts. +- The post-edit current-default documentation audit found no stale default + claims. The remaining `currently` match describes an unrelated unset value. +- All three relative catalogue links resolve to the existing JSON catalogue. +- `git diff --check`: passed. diff --git a/docs/specs/agents/system-design/mcp-timeout-budgets.md b/docs/specs/agents/system-design/mcp-timeout-budgets.md index e9487638ba..047a94a5d5 100644 --- a/docs/specs/agents/system-design/mcp-timeout-budgets.md +++ b/docs/specs/agents/system-design/mcp-timeout-budgets.md @@ -88,12 +88,14 @@ Separately, the CLI runs a per-tool-call idle watchdog. This section and its experiments were verified against a different binary than the CLI version above: `node_modules/@anthropic-ai/claude-agent-sdk-darwin-arm64/claude`, bundled by `@agentclientprotocol/claude-agent-acp@0.75.1` as -`claude-agent-sdk@0.3.257` (the managed default Claude ACP runtime pinned at -this commit; an operator selection can launch a different version — see -`apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md`), not -`~/.local/share/claude/versions/*`. The watchdog function is rewritten -below with descriptive names from that binary's minified source (logic and -constants unchanged; the minified identifiers are not): +`claude-agent-sdk@0.3.257`, not `~/.local/share/claude/versions/*`. These exact +versions identify the binary used for the experiments, not a current default. +Current managed defaults are listed in the [managed runtime +catalogue](../../../../apps/backend/internal/agent/agents/managed_npm_runtime_versions.json). +An operator selection can launch a different version (see +`apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md`). The watchdog +function is rewritten below with descriptive names from that binary's minified +source. The logic and constants are unchanged. The minified identifiers are not: ```js function idleTimeoutMs(server) {