Repository navigation
docs(verify): map maintenance 2026-11-15 - #6869
Conversation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJSRAiRLzhbUrepjY4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJSRAiRLzhbUrepjY4
REST API breakage checks (OpenAPI) — ✅ PASSEDResult: ✅ PASSED |
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Reviewed as a fresh pass on head ede5eb7d against the repo guidance (AGENTS.md, .agents/skills/custom-codereview-guide.md).
Scope: The change is confined to the repository-owned verification skills (.agents/skills/verify-agent-server/, .agents/skills/verify-sdk/) — feature-map documentation, recipes, and verification programs for the daily map-maintenance pass. No product code, API surface, CI, or compatibility surface is touched, so this belongs in this repository; docs/chore is the right classification.
Verification performed on this head:
tests/cross/test_verify_sdk_skill.py tests/cross/test_verify_agent_server_skill.py: 93 passed, matching the PR's claim.control-agent-server map checkok (35 files, 1007 ids — agrees with the README index count),map coverageok (0 unowned routes),sdk-map checkok.- Spot-checked the map's behavioral claims against the product code at this baseline; all consistent: plain-HTTP
SameSite=laxcookie minting inauth_router.py(#6760), the/api/mcp/oauth/redirectroute andcallback_base_urlvalidation inmcp_router.py(#6221), theLLM request failed: ...structured retry-log line and the 2×timeout retry budget plus exhausted-timeout summary inretry_mixin.py(#6198, #6822), content-free completions raisingLLMNoResponseErrorinside the retry boundary with thefinish_reason="length"exemption inllm.py(#6178),owner_started_atzombie/pid-reuse lease takeover inconversation_lease.py(#6827), snapshot-context stats dropping per-call lists on the wire whilebase_state.jsonkeeps them (#6823), and cipher/secrets inheritance onfork()inlocal_conversation.py(#5765). - Cross-checked linked GitHub state: every bug whose known-failure marker was dropped (#6741, #6826, #6828, #6842, #6844) is closed with its fix merged. The two open bugs the map now documents (#6864 quick-timeout classification, #6848 pause-during-startup) are correctly recorded as Known failures with reproductions, open fix PRs (#6866, #6849), and current readiness labels — documenting reality is the maintenance pass's job, not a defect here.
Findings: None. No material correctness, security, compatibility, or acceptance-criterion issue on the current head. The new recipes are exercised by the passing cross tests, and the baseline move to 2aae48b6 follows the map's documented maintenance convention.
✅ APPROVED
HUMAN:
Engel Nyst (@enyst) set up a daily automation that keeps the verify-agent-server and verify-sdk feature maps current. This PR is its run for main@2aae48b, after PR #5765.
AGENT:
I'm an AI agent helping Engel Nyst (@enyst) with project work.
Why
Daily delta pass over both feature maps for the 15 commits in
3c66af1d..2aae48b6(11 product PRs). The map changes below come from live runs on main at 2aae48b, plus an independent re-run of every edited family.Summary
Agent-server map (verify-agent-server): delta pass,
3c66af1d..2aae48b6map ownerslisted F01, F02, F03, F04, F05, F06, F08, F09, F10, F12, F19, F20, F29, F30, F31, F32, F37. F07 was added because its known bug [Bug]: full_state WebSocket snapshot omits use_snapshot=True, breaking conversations >~1,550 LLM calls with frame_too_large #6741 closed.F30.chat-usage-per-request: map drift from fix: send snapshot-form stats in full_state and conversation info #6823, fixed here.F37.rest-while-confirming: the model asked for a second confirmable action. It passed 2/2 on re-run.F12.docker-*,F31.storage-retention), and a ChatGPT login is needed forF09.acp-effort-codex.F07.error-frame, an unedited bullet. It has a frame-ordering race: the first error frame can arrive beforesync. It passed on re-run and also failed on 2026-11-14. Left for a separate recipe fix.F02.workspace-session-plain-http(new, fix(agent-server): SameSite=Lax for workspace cookie on plain HTTP #6760): plain HTTP to a non-loopback host mintsSameSite=laxwithoutSecure/Partitioned; HTTPS behind a proxy still getsSameSite=none; Secure; Partitioned. passF07.snapshot-compact-stats([Bug]: full_state WebSocket snapshot omits use_snapshot=True, breaking conversations >~1,550 LLM calls with frame_too_large #6741 fixed by fix: send snapshot-form stats in full_state and conversation info #6823): the known-bug marker is dropped, and the bullet now also checks that RESTGET /api/conversations/{id}returns the aggregates with empty per-call lists. passF10.ask-agent-usage-saved([Bug]: ask_agent usage is not saved: REST and a restarted server miss what the stats socket event already reported #6844 fixed by fix(sdk): save ask_agent usage with the conversation state #6845): marker dropped. passF19.oauth-public-redirect([Bug]: Install-time MCP OAuth redirect URI is unreachable when the browser is not on the agent-server host #6828 fixed by fix(agent-server): support public MCP OAuth callbacks #6221): marker dropped; the redirect URI is now{web_url}/api/mcp/oauth/redirect. passGET /api/mcp/oauth/redirect(it was unowned inmap coverage), all pass:F19.oauth-redirect-routeF19.oauth-redirect-unknown-stateF19.oauth-callback-base-url-validationF19.oauth-web-url-precedenceF30.chat-reuse-paused([Bug]: Gateway turn on a paused or errored conversation answers 409/500 although the message is saved and the run finishes #6842 fixed by fix(agent-server): answer a gateway turn on a paused conversation with its own run #6843): marker dropped. passF30.chat-usage-per-request(drift from fix: send snapshot-form stats in full_state and conversation info #6823): per-calltoken_usagesare now read frombase_state.json, because REST stats no longer list them. passF31.lease-zombie-owner-takeover(Agent-server restart waits up to 45 s for its own conversations when the old owner PID is reused or a zombie #6826 fixed by fix(agent-server): take over a conversation lease whose owner PID was reused or is a zombie #6827): marker dropped; the lease recordsowner_started_at. passmap checkandmap coverageare ok (216 routes, 0 unowned).SDK map (verify-sdk): delta pass,
3c66af1d..2aae48b6sdk-map ownerslisted S01-S14, S17, S20. S15 was added for its [Bug]: Native DeepSeek image-loss rejection is retried and surfaces as LLMServiceUnavailableError instead of LLMBadRequestError #6840 Gotcha.S14.preset-gpt5-geminifailed because the model declined to write the file; it passed 2/2 on re-run.S13.llm-analyzerfailed because DeepSeek labelsrm -rf scratchMEDIUM. That happens on BASE too (3/3 there, 3/4 on main), so it is not a regression; a note is added.S01.empty-reply-nudge(drift from fix(llm): retry content-free completions instead of nudging into STUCK #6178): a content-free reply is retried inside the LLM call with no nudge. If every retry is content-free, the run ends ERROR with one retryableLLMNoResponseError. A reasoning-only reply is still nudged. passS02.no-response-retry(fix(llm): retry content-free completions instead of nudging into STUCK #6178): the bullet now also covers content-free choices (plain and streamed),finish_reason="length"and reasoning-only. The new checks pass; the bullet still fails only on Known failure [Bug]: On the Responses API path an empty stream is retried as a connection error, never as LLMNoResponseError #6657.S02.timeouts(fix(llm): bound retries of LLM calls that keep hitting the timeout, and say why they failed #6822): a hard timeout stops after 2 attempts and carries the summary; quick timeouts keep every retry. passS02.retries(fix(llm): log safe exception types and retry decisions #6198): a 2xx response with a non-JSON body is retried. passS02.thinking-text-reply([Bug]: Text and reasoning-only replies lose every thinking block signature, so the thinking is not sent back on the next request (regression from #4870) #6837 fixed by fix(sdk): keep the signature on thinking blocks masking did not change #6839) andS02.image-adapter-loss([Bug]: Native DeepSeek image-loss rejection is retried and surfaces as LLMServiceUnavailableError instead of LLMBadRequestError #6840 fixed by fix(llm): report DeepSeek image loss as a bad request, without retries #6841): Known failure notes dropped. passS04.pause-during-startup(new, open [Bug]: pause()/interrupt() during run() startup is taken for a resume, the agent keeps running #6848, fix PR fix(sdk): keep a pause that lands while run() is starting #6849): Known failure. It passed on the fix(sdk): keep a pause that lands while run() is starting #6849 branch.S04.fork-keeps-secrets(new, fix(sdk): keep the source's cipher and secrets on a forked conversation #5765): the SDK side ofF10.fork-keeps-credentials. It passes on main and fails before fix(sdk): keep the source's cipher and secrets on a forked conversation #5765. passS04.ask-agent-usage-saved([Bug]: ask_agent usage is not saved: REST and a restarted server miss what the stats socket event already reported #6844 fixed): Known failure note dropped. passS05.error-classification: two new bullets.config/settings. passS20.llm-retry-log(new, fix(llm): log safe exception types and retry decisions #6198): retry log lines carry the type and decision fields and no raw provider body. passsdk-map checkis ok.tests/cross/test_verify_sdk_skill.py tests/cross/test_verify_agent_server_skill.py: 93 passed.Both maps
WindowsTerminal) is blocked on this machine because it needs Windows (S14.terminal-windows).Server:/Same promise:links yet. These natural twins were compared and agree:F10.ask-agent-usage-savedandS04.ask-agent-usage-saved: pass on both.F10.fork-keeps-credentialsandS04.fork-keeps-secrets: pass on both.F07.snapshot-compact-statsand the Canvas usage panel: agree.config/settings.ConversationErrorEvent.control-openhands doctor), which predates every fix in this range. Users see them only after Canvas pins a newer release. A Gotcha was added to each affected family:callback_base_url(fix(mcp): send the browser's backend URL as the MCP OAuth callback base OpenHands#19744). 1.62.0 ignores it.Issue Number
#5751
How to Test
Evidence, pinned to evidence commit bf2271de54196a4763857efe2fe42ef7cf0ae702:
https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/agent-server-report-main.md)https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/sdk-report-main.md)https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/agent-server-report-edited.md)https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/sdk-report-edited.md)[F02.workspace-session-plain-http](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F02-auth-and-sessions-22-plain-http-to-a-non-loopback-host-f02-wo.json):the lax and none cookie headers.[main xpass](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/main/transcripts/F07-session-socket-20-compact-snapshot-stats-f07-snapshot-comp.json)and[edited pass](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F07-session-socket-20-compact-snapshot-stats-f07-snapshot-comp.json):the snapshot without per-call lists, and REST with empty lists.[route](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F19-mcp-23-redirect-to-the-agent-server-s-own-route.json)[unknown state](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F19-mcp-24-unknown-sign-ins-on-the-redirect-route-f.json)[callback_base_url](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F19-mcp-25-callback-base-url-validation-f19-oauth-c.json)[web_url precedence](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F19-mcp-26-web-url-wins-over-the-request-f19-oauth-.json)[public redirect](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F19-mcp-22-redirect-uri-on-the-public-origin-f19-oa.json)[F10.ask-agent-usage-saved](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F10-fork-navigate-condense-ask-26-ask-usage-on-get-and-after-a-restart-f10.json)[F30.chat-reuse-paused](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F30-openai-gateway-18-continue-a-paused-conversation-f30-chat-.json)[F31.lease-zombie-owner-takeover](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F31-persistence-and-limits-05-zombie-owner-takeover-f31-lease-zombie-o.json)[main fail (drift)](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/main/transcripts/F30-openai-gateway-14-usage-per-request-f30-chat-usage-per-req.json)and[edited pass](https://github.com/enyst/openhands-evidence/blob/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/edited/transcripts/F30-openai-gateway-14-usage-per-request-f30-chat-usage-per-req.json).https://github.com/enyst/openhands-evidence/blob/b50ebd464f326b70f83fd8ae96e14476c567b650/software-agent-sdk/bugs/2026-11-15/quick-timeout-summary/README.md)Video/Screenshots
Agent Canvas (OpenHands/OpenHands main 02c438a) launched on an agent-server built from this pass's checkout (2aae48b):
#6221, MCP OAuth (Canvas F17): the provider's consent page shows the redirect URI on the backend origin,
/api/mcp/oauth/redirect.[F17 OAuth redirect URI](
https://raw.githubusercontent.com/enyst/openhands-evidence/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/ui/F17.install-unsupported_oauth-popup-authorize.png)#6221, a completed OAuth install against a local OAuth MCP server (Canvas F17): the server is installed and reachable.
[F17 OAuth server installed](https://raw.githubusercontent.com/enyst/openhands-evidence/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/ui/F17.custom-add-remote_oauth-server-installed-tested.png)#6823, snapshot-form stats (Canvas F07.display-cost): the usage panel keeps non-zero totals after a backend restart.
[F07 usage after restart](
https://raw.githubusercontent.com/enyst/openhands-evidence/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/ui/F07.display-cost_usage-after-server-restart.png)#6760, workspace cookie on loopback (Canvas F08): the file preview loads. The plain-HTTP non-loopback browser path could not be driven, because the stack binds 127.0.0.1; it was checked at header level in F02.
[F08 preview](
https://raw.githubusercontent.com/enyst/openhands-evidence/bf2271de54196a4763857efe2fe42ef7cf0ae702/software-agent-sdk/map-maintenance/2026-11-15/ui/F08.files-rich-plain_html-preview-cookie.png)Design Doc
Not applicable: map maintenance only, no product change.
Type
Notes
The map edits touch only the two skills' directories. Nothing is added under
.pr/.Generated by Claude Code
🐳 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
eclipse-temurin:17-jdkpython-node-runtimepython-node-runtimepython-node-runtimegolang:1.21-bookwormPull (multi-arch manifest)
# Each variant is a multi-arch manifest supporting both amd64 and arm64 docker pull ghcr.io/openhands/agent-server:ede5eb7-pythonRun
All tags pushed for this build
About Multi-Architecture Support
ede5eb7-python) is a multi-arch manifest supporting both amd64 and arm64ede5eb7-python-amd64) are also available if needed