Skip to content

docs(verify): link SDK and agent-server map twins - #6728

Open
enyst wants to merge 2 commits into
mainfrom
claude/project-thread-9gswn2
Open

enyst wants to merge 2 commits into
mainfrom
claude/project-thread-9gswn2

Conversation

@enyst

@enyst enyst commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

HUMAN:

start a new thread to solve this, go through everything in sdk and server maps, and link them appropriately "There were no SDK/server twin pairs to drive, because the map has no Server: links yet."


AGENT:

Requested by Engel · project thread

I'm an AI agent (Claude Code) helping Engel Nyst (@enyst) with project maintenance.

Why

The daily map routine drives SDK/agent-server twin pairs (an SDK bullet and an agent-server bullet that prove the same promise), because twins that disagree usually locate a bug at the seam between the SDK and the server. No bullet carried a link, so the 2026-11-10 run drove no pairs.

Summary

  • Reviewed all 458 SDK bullets against all 953 agent-server bullets. 136 SDK bullets now end with Server: ..., naming 229 agent-server bullets, which end with Same promise: ... naming them back. A link means "a pass driving both expects the same answer", not "related feature": server-only contract (status codes, auth, stores, webhooks) and SDK-only behavior (local workspaces, visualizers, logging, LLM internals, critic, planning tools) stay unlinked. The 2026-11-03 overlap table was the starting point; I re-checked each pair against current main, tightened loose ones (e.g. S14.terminal-exec, S13.llm-analyzer, S19.acp-settings had no true twin) and added missing ones (e.g. S02.error-mapping ↔ F20.validate-*, S04.pause ↔ F33.conversation-pause, S08.marketplace-auto-load ↔ F25.catalog-registered-marketplace).
  • Link contract documented in both map indexes ("Twin links") and in mapping.md.
  • sdk-map check and control-agent-server map check validate links both ways: the named ID exists in the other map, names this bullet back, and the link ends the line in the exact form. New sdk-map links / control-agent-server map links [--file] [--id] list the pairs.
  • Both daily.md files get a step 3, Twins: drive the twins of the families a change touched, and treat a disagreeing pair as a finding.

Issue Number

Fixes #6727

How to Test

uv sync --dev
export PATH="$PWD/.agents/skills/verify-sdk/scripts:$PWD/.agents/skills/verify-agent-server/scripts:$PATH"
sdk-map check                      # ok, 0 problems
control-agent-server map check     # ok, 0 problems (routes included)
sdk-map links --id S04.pause       # 6 pairs
control-agent-server map links --file F08
uv run pytest tests/cross/test_verify_sdk_skill.py tests/cross/test_verify_agent_server_skill.py   # 97 passed

New tests cover a one-sided link, an unknown target, a malformed link, the --file filter, and a checkout without the sibling map (checks skip).

Type

  • Bug fix
  • Feature
  • Refactor
  • Breaking change
  • Docs / chore

Notes

  • Surfaces: sdk, server (running an SDK bullet through control-sdk --surface remote) is not part of this PR, because that runner doesn't exist yet. The 253 SDK bullets that run inside the server but have no driving F bullet stay unlinked until it does.
  • The routine's stranded 2026-11-10 map commits (branch cloud/sweet-darwin-b4uwcp) touch a few of the same bullet lines (S04, F07, F15); whichever lands second needs a small rebase.

🤖 Generated with Claude Code

https://claude.ai/code/session_013ArwwJcJzCzwmKD5zoVnd1


🐳 Agent Server images for this PR — GHCR package, pull/run commands, and all pushed tags (click to expand)

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant Architectures Base Image Docs / Tags
java amd64, arm64 eclipse-temurin:17-jdk Link
python-slim amd64, arm64 python-node-runtime Link
python-minimal amd64, arm64 python-node-runtime Link
python amd64, arm64 python-node-runtime Link
golang amd64, arm64 golang:1.21-bookworm Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:bd418bc-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-bd418bc-python \
  ghcr.io/openhands/agent-server:bd418bc-python

All tags pushed for this build

ghcr.io/openhands/agent-server:bd418bc-golang-amd64
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-golang-amd64
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-golang-amd64
ghcr.io/openhands/agent-server:bd418bc-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:bd418bc-golang-arm64
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-golang-arm64
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-golang-arm64
ghcr.io/openhands/agent-server:bd418bc-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:bd418bc-java-amd64
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-java-amd64
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-java-amd64
ghcr.io/openhands/agent-server:bd418bc-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:bd418bc-java-arm64
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-java-arm64
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-java-arm64
ghcr.io/openhands/agent-server:bd418bc-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:bd418bc-python-amd64
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-python-amd64
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-python-amd64
ghcr.io/openhands/agent-server:bd418bc-python-node-runtime-amd64
ghcr.io/openhands/agent-server:bd418bc-python-arm64
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-python-arm64
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-python-arm64
ghcr.io/openhands/agent-server:bd418bc-python-node-runtime-arm64
ghcr.io/openhands/agent-server:bd418bc-python-minimal-amd64
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-python-minimal-amd64
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-python-minimal-amd64
ghcr.io/openhands/agent-server:bd418bc-python-node-runtime-minimal-amd64
ghcr.io/openhands/agent-server:bd418bc-python-minimal-arm64
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-python-minimal-arm64
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-python-minimal-arm64
ghcr.io/openhands/agent-server:bd418bc-python-node-runtime-minimal-arm64
ghcr.io/openhands/agent-server:bd418bc-python-slim-amd64
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-python-slim-amd64
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-python-slim-amd64
ghcr.io/openhands/agent-server:bd418bc-python-node-runtime-slim-amd64
ghcr.io/openhands/agent-server:bd418bc-python-slim-arm64
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-python-slim-arm64
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-python-slim-arm64
ghcr.io/openhands/agent-server:bd418bc-python-node-runtime-slim-arm64
ghcr.io/openhands/agent-server:bd418bc-golang
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-golang
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-golang
ghcr.io/openhands/agent-server:bd418bc-golang_tag_1.21-bookworm
ghcr.io/openhands/agent-server:bd418bc-java
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-java
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-java
ghcr.io/openhands/agent-server:bd418bc-eclipse-temurin_tag_17-jdk
ghcr.io/openhands/agent-server:bd418bc-python-minimal
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-python-minimal
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-python-minimal
ghcr.io/openhands/agent-server:bd418bc-python-node-runtime-minimal
ghcr.io/openhands/agent-server:bd418bc-python-slim
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-python-slim
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-python-slim
ghcr.io/openhands/agent-server:bd418bc-python-node-runtime-slim
ghcr.io/openhands/agent-server:bd418bc-python
ghcr.io/openhands/agent-server:bd418bc52b6492dd6ce4f08d9da30866dd68a713-python
ghcr.io/openhands/agent-server:claude-project-thread-9gswn2-python
ghcr.io/openhands/agent-server:bd418bc-python-node-runtime

About Multi-Architecture Support

  • Each variant tag (e.g., bd418bc-python) is a multi-arch manifest supporting both amd64 and arm64
  • Docker automatically pulls the correct architecture for your platform
  • Individual architecture tags (e.g., bd418bc-python-amd64) are also available if needed

Review every bullet of the SDK map (S01..S21) and the agent-server map
(F01..F34) and link the ones that prove the same promise on both surfaces:
136 SDK bullets now end with `Server:` naming 229 agent-server bullets,
which end with `Same promise:` naming them back.

Define the link contract in both map indexes, make `sdk-map check` and
`control-agent-server map check` validate the links in both directions
(target exists, names the bullet back, exact form), add `sdk-map links`
and `control-agent-server map links` to list the pairs, and add a twins
step to both daily passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJcJzCzwmKD5zoVnd1
@enyst enyst self-assigned this Nov 10, 2026
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

@enyst
enyst marked this pull request as ready for review November 10, 2026 18:08
@enyst
enyst requested a review from all-hands-bot November 10, 2026 18:08

@all-hands-bot all-hands-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This review was posted by an AI agent (OpenHands).

Reviewed at head 3a97f03e89591dd4c9bcc92797de8857a78fa060 (55 files, +840/−369). Scope gate: the change touches only .agents/skills/verify-sdk/, .agents/skills/verify-agent-server/, and tests/cross/, all owned by this repository; linked issue #6727 is ready-for-dev. No public API, REST contract, settings, events, or persisted-state surfaces are touched, so the compatibility checkpoints do not apply.

What I verified on this head:

  • Both tools validate the twin links bidirectionally and pass: sdk-map check → ok, 0 problems (458 IDs); control-agent-server map check → ok, 0 problems (953 IDs, routes included). Link counts match the PR description exactly: 136 SDK bullets with Server: links naming 229 agent-server bullets, 268 pairs in each direction; zero malformed links, unknown targets, duplicates, or wrong-prefix IDs.
  • Spot-read a dozen pairs in full text (S04.pause ↔ F05./F33, S13.confirm- ↔ F08/F33, S19.profile-store ↔ F21., S03.meta-profile-store ↔ F22., S02.error-mapping ↔ F20.validate-, S17.usability ↔ F27.catalog, S10.command-exec ↔ F27.hooks-conversation, S20.conversation-args ↔ F04.): each is genuinely the same promise on both surfaces, matching the documented contract. The claimed removals (S14.terminal-exec, S13.llm-analyzer, S19.acp-settings) indeed have no links, and the claimed additions (S02↔F20, S04↔F33, S08↔F25) exist.
  • The S01.stuck-recover ↔ F05.stuck-rerun pair links a bullet that self-declares a known failure (#6648); this is consistent with the daily-pass rule that a disagreeing pair is a finding "unless the difference is already a known bug on one side", so it is not a defect.
  • Error paths behave as the tests assert: malformed link form, unknown target, one-sided link, --file filtering, and a checkout without the sibling map (skips cleanly) — all exercised directly, not just via the tests.
  • Diff integrity: every removed map bullet line reappears with only a link appended (0 mismatches across 365 replaced lines); nothing else in the maps was rewritten. Ruff check/format clean on the changed scripts; doc anchors and the new daily-pass commands parse against the real CLIs.
  • Tests: uv run pytest tests/cross/test_verify_sdk_skill.py tests/cross/test_verify_agent_server_skill.py → 97 passed, matching the PR claim.
  • Checks on this head are green; the one failing "Validate PR description" run is stale — the same check has later successful runs on this exact SHA, and the REST API breakage bot reports PASSED at 2026-11-10T17:42Z.

No material correctness, security, or compatibility findings.

✅ APPROVED

@enyst enyst mentioned this pull request Nov 14, 2026
1 of 5 tasks
Resolve conflicts by taking main's map text and re-applying the PR's
Server:/Same promise: links (all 365 linked bullets still exist on main).
Link 28 new twin pairs main added (model router, ask_user, message edits,
reactions, runtime MCP add, ACP effort, public-skills switch, ...), and
move F09.load-plugin-twice to main's new S10.plugin-hooks-reload-once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwMeAwT1A2JVHapmA1X
@enyst
enyst requested a review from all-hands-bot November 20, 2026 00:05

@all-hands-bot all-hands-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"This review was posted by an AI agent (OpenHands).\n\nFresh review of head bd418bc52b6492dd6ce4f08d9da30866dd68a713 (the prior approval from this account was on 3a97f03e, before the merge of main).\n\nScope: entirely within .agents/skills/verify-sdk/, .agents/skills/verify-agent-server/, and tests/cross/ \u2014 SDK/agent-server verification tooling and maps, owned by this repository. No production SDK/server code paths, no API or compatibility surfaces, no secrets.\n\nVerified on the current head in a clean checkout:\n- sdk-map check \u2192 ok, 0 problems (21 files, 504 ids); control-agent-server map check \u2192 ok, 0 problems (38 files, 1068 ids), routes included.\n- sdk-map links --id S04.pause \u2192 exactly the 6 pairs the PR claims; control-agent-server map links --file F08 works as documented.\n- Both tools agree on the full pair list (295 edges, each direction naming the other back).\n- uv run pytest tests/cross/test_verify_sdk_skill.py tests/cross/test_verify_agent_server_skill.py \u2192 100 passed (the PR body cites 97; the count grew because the head merged newer main \u2014 all pass).\n- All GitHub Actions checks on this head are green (cross-tests, agent-server suites, OpenAPI, builds).\n\nLink contract: the bidirectional check is strict \u2014 the named ID must exist in the sibling map, must name the bullet back, and the link must end the line in the exact documented form; duplicate IDs, unknown targets, and malformed lines are all reported (exercised directly, including through the new tests covering one-sided links, unknown targets, malformed links, the --file filter, and the missing-sibling skip). Spot-checked claimed pairs (S02.error-mapping \u2194 F20.validate-*, S08.marketplace-auto-load \u2194 F25.catalog-registered-marketplace, S04.pause \u2194 F05.*/F33.conversation-pause): the linked bullets do state the same promise on both surfaces.\n\nFreshness: the branch merged main at 3d638f2e (including map maintenance #7006) and the merge commit linked the new twins; the three main commits since (ruff bump, release, ACP fix) do not touch any linked bullet lines, and the checks above run against current main content. The PR body's 136/229 counts predate that merge (the merged head carries more linked bullets), which is description staleness only \u2014 the map data itself validates consistent. The git status note about the stranded cloud/sweet-darwin-b4uwcp branch still applies and is correctly flagged for a rebase by whichever lands second.\n\nIssue #6727 remains open with ready-for-dev/priority:low; this PR delivers its acceptance criteria as described.\n\nNo material correctness, security, compatibility, or acceptance-criterion defects found.\n\n\u2705 APPROVED\n"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

verify: link the SDK map and the agent-server map where they prove the same promise

3 participants