dreampiler/kandev
1
0
Fork 0
Code Issues 43 Pull Requests Actions 6 Packages Projects Releases Wiki Activity

docs: remove duplicated runtime default claims (#3608)

Browse Source
This commit is contained in:
Carlos Florêncio
2026-09-11 17:41:00 +01:00
committed by GitHub
parent 8cccefbb93
commit 52b9c55a24
5 changed files with 301 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md
+19 -18
View File
@@ -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@<effective-version>` with the ACP
arguments above. For example, an unmodified Claude installation launches
`npx --yes --prefer-offline @agentclientprotocol/claude-agent-acp@<effective-version>`.
The `<effective-version>` 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@<effective-version>` 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
docs/decisions/0034-agentclientprotocol-codex-acp.md
+6 -4
View File
@@ -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
docs/plans/managed-runtime-pin-docs/plan.md
+132
View File
@@ -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 `@<effective-version>` 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.
docs/plans/managed-runtime-pin-docs/task-01-remove-duplicated-defaults.md
+136
View File
@@ -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.
docs/specs/agents/system-design/mcp-timeout-budgets.md
+8 -6
View File
@@ -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) {