Repository navigation
Conversation
A project groups the conversations that work toward one goal: a coordinator conversation the person mainly talks to, and its threads. - Projects API under /api/projects: create, list, get, patch, delete, plus /threads to list, add and remove members. Records live in projects.json with the same atomic-write and file-lock store as workspaces.json; a corrupted or newer-schema file answers 409 and is never overwritten. - Membership is the `project` conversation tag, so children started with start_child_conversation join their parent's project. The threads endpoint groups members by attention (needs_you, working, finished, idle) derived from execution_status. - ConversationService gains list_tagged_conversations and set_conversation_tag (single-tag change that keeps the other tags). - openhands.tools.project: list_project_threads and message_project_thread, server-registered tools that let a coordinator follow and steer its threads. The message tool refuses a thread that is waiting for confirmation (running it would approve the pending action) and sends to a running thread without requesting a new run. - Feature map family F36 with 19 recipes, all passing on a fresh server with a real model. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
Review found that message_project_thread checked a thread's status and
then ran it in a separate request, so a thread that reached a
confirmation in between would have its pending action approved by the
run.
- EventService.run()/send_message() take refuse_pending_confirmation;
the check is made under the run lock, where no other run can change
the status. A refused send keeps the message and raises
ValueError("waiting_for_confirmation").
- New POST /api/projects/{id}/threads/{conversation_id}/messages uses
it: 409 for a thread already waiting (nothing saved), otherwise
run_requested tells whether a run was started.
- The tool delivers through that route, waits up to 300 s (a running
thread holds its state lock for a whole tool call) and, on a
timeout, says the message may still arrive and must not be resent.
- Project writes re-check the coordinator under the file lock, tag the
coordinator only after the record is saved (rolling back if it
vanished), and run file I/O off the event loop; tag updates lock per
conversation.
- F36 gains message-rest and message-refused recipes; 21 recipes pass
on a fresh server with a real model.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
Second review confirmed the confirmation guard holds on every path, and found that the route could still say a run was requested when the message was parked behind a confirmation or a stop. - EventService.send_message(run=True) now returns "started", "queued" (a run was already active) or "not_run"; run=False returns None, so existing callers are unaffected. - The messages route answers run: started | queued | waiting_for_confirmation | not_run instead of run_requested, and the tool words each case without claiming more than happened. - A failed coordinator tag on PATCH undoes the whole change, and only if no later write touched the project; it never restores a coordinator that now leads another project. Exceptions while tagging roll back too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
REST API breakage checks (OpenAPI) — ✅ PASSEDResult: ✅ PASSED |
This comment has been minimized.
This comment has been minimized.
Coverage Report •
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
A finished run tags its conversation with how the agent's last message ended (turn=asked|answered) and, when the critic scored it at least 0.9, resolved=auto. A new user message removes both. The project threads list uses them for needs_input and resolved groups and reports automation_id. Children no longer copy their parent's resolved/turn tags. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
Projects keep artifacts, the files they produce or are given that do not belong in a source repository, under the persistence dir. Routes list, upload, download and delete them, and copy a file from a member conversation's workspace (paths, symlinks included, must stay inside it). The save_project_artifact tool lets an agent save its deliverables there. Deleting a project deletes its artifacts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
Open workspace files without following a final symlink or blocking on a FIFO, in a worker thread, and check the opened file again. Match artifact names in full (no trailing newline), refuse trailing dots or spaces, Windows device names and names differing only in case, and serialize saves and deletes per project. Refuse an oversized upload before copying it. List a running thread as working even if it is still tagged resolved, and skip tag writes a user message does not need. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
A Stop hook that denies stopping on a plain message makes the agent go on to a finish that may not repeat its question. Once the agent stops on a question, keep turn=asked until the next user message. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
The Resolve button can mark conversations outside a project too, so a new user message clears resolved/turn wherever they are set. Recording outcomes stays limited to project members. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
GET /api/conversations/{id} took tags from base_state.json, which a
running conversation saves only when its run releases the state lock, so
a tag PATCH (for example resolving a running thread) stayed invisible
until the run ended. Read tags from meta.json, which the PATCH writes
first and the catalog already uses.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
…-xwkk9b # Conflicts: # .agents/skills/verify-agent-server/references/feature-map/README.md
|
Generated by Claude Code |
OpenHands calls these conversations. Routes move to
/api/projects/{id}/conversations, the list field is `conversations`, the
models are ProjectConversation*, and the coordinator tools are
list_project_conversations and message_project_conversation.
THREAD_STATE_TAG_KEYS becomes BOARD_TAG_KEYS and ThreadOutcomeSubscriber
becomes ConversationOutcomeSubscriber.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
A message one project conversation sends another (the coordinator's message_project_conversation, or POST .../messages with sender_conversation_id) now records sender="conversation:<id hex>" and opens with a line telling the receiving agent who sent it and that it approves nothing on the person's behalf. A child started by a project member gets a system-prompt note naming the conversation that started it, and its task message records that parent as sender. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
A ReactionEvent (target_event_id, emoji, removed, source) records an emoji
on a message; it never reaches the LLM. Agents react with the new react and
unreact tools (openhands.tools.reaction), which default to the person's
latest message. The executor only reads the log: the observation carries
the reaction and the agent records the event right after it on its own
thread, through a new Observation.follow_up_events() hook, so it is safe
with parallel tool calls. People react through
POST /api/conversations/{id}/reactions (LocalConversation.react), which
defaults to the agent's latest message or finish and never runs the agent.
Emoji come from a fixed set of shortcodes. New feature-map family F37.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
- A user message that arrives while a finished run's outcome is still being written now queues a reopen behind it, so a stale turn/resolved=auto no longer lands after the person wrote again (reproduced by test_a_user_message_before_the_outcome_is_saved_still_reopens). - A child gets guidance naming its own parent: inherited guidance is removed first, also when the parent has left its project. - Titles in the sender header and guidance are flattened to one line without quotes or brackets. - Reaction targets come from the active branch. - execute_tool records an observation's follow-up events, and rerun_actions logs them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
A ReactionEvent (target_event_id, emoji, removed, source) records an emoji
on a message; it never reaches the LLM. Agents react with the new react and
unreact tools (openhands.tools.reaction), which default to the person's
latest message. The executor only reads the log: the observation carries
the reaction and the agent records the event right after it on its own
thread, through a new Observation.follow_up_events() hook, so it is safe
with parallel tool calls. People react through
POST /api/conversations/{id}/reactions (LocalConversation.react), which
defaults to the agent's latest message or finish and never runs the agent.
Emoji come from a fixed set of shortcodes. New feature-map family F37.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
… on every tool path Reaction part of de324a9 from #6602. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
…s the first
A feature flag is a yes/no switch the user sets for themselves, stored in
PersistedSettings.features and read when a conversation starts.
GET /api/settings/features lists the known features with their state, and
PATCH /api/settings/features/{key} {enabled} turns one on or off; unknown
keys are 404. The registry is openhands.agent_server.features.
The first flag, conversation_reactions (off by default), gives every new
OpenHands-agent conversation the react and unreact tools through a new
finalize(feature_tools=...) parameter (ACP agents are left alone), and
lets POST /api/conversations/{id}/reactions through; while it is off that
route answers 409. Feature map F37 covers both.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt
ReactionEvent / ReactionEmoji types with isReactionEvent, ConversationClient.react(), and SettingsClient.listFeatures() / updateFeature() with the FeatureFlag type. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJ5sQMXhwgSTG2Ztkt
- Coordinator tools say to delegate by default. When a member finishes a
turn the coordinator started, the coordinator gets the member's final
message as one update (project_wake.notify_coordinator). Turns the person
starts in a member do not wake it, and an answered update starts no round.
- read_project_conversation and GET /api/projects/{id}/conversations/{cid}/messages
give the coordinator a member's latest messages on demand.
- POST /api/conversations/{id}/events takes optional sender_conversation_id
(records the sender and a "Sent by" line; a sender in a project only reaches
its project) and refuse_pending_confirmation (409 instead of approving).
With run it reports the run outcome. The project-only messages route is
gone; message_project_conversation now uses the generic route.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
|
Two CI failures on 4a4a34c (the merge of main) aren't from this PR:
This PR touches neither the terminal tools nor the sandbox-pause path or its test, and both tests pass 3/3 locally on this head. I'll rerun the failed jobs once the run finishes. Generated by Claude Code |
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Re-review at head 4a4a34cc (delta since the approved f76a7784: a single merge from main; mergeStateStatus is CLEAN). Verified in this workspace:
- The only change in the range is the merge of
main, whose commits are dependency bumps (boto3 1.44.1, prettier 3.10.0 and @openrouter/sdk 1.5.91 inclients/typescript) plus the already-reviewed verify-scale tests (#6984). The merge diff touches onlyuv.lock,openhands-sdk/pyproject.tomlandclients/typescript/package-lock.json— no Projects code, no route or SDK behavior change. - This matches the PR body's current contract diff, which is unchanged in shape from the previously approved head.
Test results at this exact head: Projects router + board + project tools 209 passed. CI on this exact head SHA: 54 checks success, 1 known skip, 0 failures.
No material findings on the current head.
✅ APPROVED
The client no longer reserves the coordinator's conversation id, so a new coordinator can never collide with an existing conversation and ConversationService needs no reuse_existing switch. Co-authored-by: openhands <openhands@all-hands.dev> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
…a profile Drop create_conversation and the extra _create_conversation keywords: start_conversation takes the server's tools, the first message carries sender_conversation_id, and the title is saved after the start. A project worker always runs an agent profile; with none to run, the start is refused (422). start_child_conversation is back to main's copied child for everyone else. Co-authored-by: openhands <openhands@all-hands.dev> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
A client no longer reserves the coordinator's id, so the server picks it before the start and the <PROJECT> block says which conversation the coordinator is: one that calls the API itself can send as itself. F36 now activates an agent profile: workers start from the predefined worker profile, built from the active one, and are refused without it. Co-authored-by: openhands <openhands@all-hands.dev> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
Remove the pending-confirmation guard from the shared send path: refuse_pending_confirmation, the held/run outcomes on the send route, HeldForUser, admission_refusal and the sender special case are gone, so POST /events and EventService.send_message behave as on main. Projects keeps two checks of its own: message_worker refuses a worker waiting for confirmation, and project updates save without running a coordinator that waits for one, so no agent approves another's actions. The sender header stays in message_sender where main has it; Projects adds project_sender_header beside it for the scope check and role. ASK_USER moves back to main's place in experimental_features. Co-authored-by: openhands <openhands@all-hands.dev> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
… with the user The live check no longer requires the coordinator to call message_worker: it may decline on its own, as its prompt says only the user approves. It still checks the worker keeps waiting and got no new message. Co-authored-by: openhands <openhands@all-hands.dev> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Re-review at head aede9ccd (delta since the approved 4a4a34cc: five branch commits plus merges from main; mergeStateStatus is CLEAN). Verified in this workspace:
4641eb341— the shared send path returns to main's behavior.refuse_pending_confirmation, theSendMessageResponserun outcomes,admission_refusal()andHeldForUserare gone;POST /api/conversations/{id}/eventsanswersSuccessagain and behaves as on main. I traced where the Projects-specific protections now live and confirmed they are still enforced: themessage_workertool refuses a worker listed aswaiting_for_confirmationbefore sending anything (impl.pystatus check), and every server delivery to a coordinator goes through_deliver(), which clears the run flag when_waits_for_confirmation()is true, so an update is saved without approving pending actions. The member-side answer path (pass_on_answer) applies the same check (run=not await _waits_for_confirmation(member)). The sender header lives inmessage_sender.pyas on main, withproject_sender_headerlayered beside it for project scoping and role.308bed138/3a45ea35c— project conversations start throughstart_conversation. Workers always run an agent profile (422 with none),start_child_conversationis back to main's copy for non-projects, and the coordinator's id is chosen by the server rather than client-reserved, removing the id-collision surface without losing the "one coordinator per project" behavior (concurrent duplicate coordinator starts now simply get distinct ids; the previously tested reserved-id 422 path was removed with the reservation mechanism itself).e6352bdf8names the coordinator's own id in its<PROJECT>block;aede9ccd0regenerates the coordinator prompt snapshot and F36 recipe wording only.
Test results at this exact head: Projects router + board + cards + parent/child + project tools + run-admission + event-router suites 292 passed. CI on this exact head SHA: 54 checks success, 1 known skip, 0 failures.
No material findings on the current head.
✅ APPROVED
…nternally A project never adopts an existing conversation: coordinator_conversation_id is gone from POST and PATCH /api/projects. POST starts a new coordinator when asked, as before. The coordinator's and worker's prompt, project context and tools reach the agent through finalize's project_role (a ProjectRole), set only by ProjectService. AgentLaunchAdditions is main's again, so no client can ask for a coordinator prompt, and start_conversation loses server_tools. Restore needs nothing of its own: the finalized agent is saved with the conversation, as on main. F36 now checks that a coordinator and a worker keep their prompt, context and tools after a restart and use a project tool. Co-authored-by: openhands <openhands@all-hands.dev> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
…prompt it has not sent yet Co-authored-by: openhands <openhands@all-hands.dev> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
OpenHands/software-agent-sdk#6602 no longer takes coordinator_conversation_id on POST or PATCH /api/projects; only "coordinator" starts the project's coordinator. Drop it from the request type (Canvas never sent it). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwM9SZ2RcWff4zZivYR
Co-authored-by: openhands <openhands@all-hands.dev> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
tool_module_qualnames lists every tool module the server has registered, so a worker's response names message_worker even though its agent does not have it. Co-authored-by: openhands <openhands@all-hands.dev> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: openhands <openhands@all-hands.dev>
…-xwkk9b # Conflicts: # openhands-agent-server/openhands/agent_server/event_service.py # openhands-sdk/openhands/sdk/conversation/types.py
…to claude/project-thread-xwkk9b
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Re-review at head 2aacbbd4 (delta since the approved aede9ccd: five branch commits, two merges from main, and one self-merge adopting #7012; mergeStateStatus is CLEAN). Verified in this workspace:
bd6c00c14— a project never adopts an existing conversation.coordinator_conversation_idis removed fromPOSTandPATCH /api/projects, so the id-collision surface from the previous reserved-id mechanism is gone entirely; a project's coordinator is always started by the server. I confirmed the role delivery is now closed:ProjectRole(prompt,<PROJECT>context, tools) is afinalize()parameter set only byProjectService(coordinator and worker call sites), not readable fromAgentLaunchAdditionsor any client-supplied request field — no client can ask for a coordinator prompt or project tools. ACP agents are still refused for coordination (runs_in_a_projectcheck).872916163(self-merge) — sender/stop/update/paused/card "headers" renamed to "lines" per #7012, wording preserved; pure naming acrossproject_wake.py,project_prompts.py,message_sender.py.3d952fc31/e9147274a/5ae3ad95aare F36 recipe corrections only.- Merges from
mainadopt #7007 (typed already-running errors) and #7010/#6925/#6811 upstream; no carried copies.
Test results at this exact head: Projects router + board + cards + parent/child + project tools + SDK launch suites 359 passed. CI on this exact head SHA: 54 checks success, 1 known skip, 0 failures.
No material findings on the current head.
✅ APPROVED
Only the server gives a conversation the Projects role and tools, so main's launch path no longer strips Projects tools by class, and an ordinary child is copied from its parent as on main. A Projects tool a conversation still holds refuses to run when Projects is off or it is not in a project. Co-authored-by: openhands <openhands@all-hands.dev> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
|
The Generated by Claude Code |
|
Generated by Claude Code |
all-hands-bot
left a comment
There was a problem hiding this comment.
This review was posted by an AI agent (OpenHands).
Re-review at head ecbb860c (delta since the approved 2aacbbd4: one branch commit plus the merge of main/v1.63.0). Verified in this workspace:
0fed774a3— Projects: drop withheld tools and the child's role stripping. Since only the server assigns the Projects role and tools (viafinalize(project_role=...), unchanged in scope),withheld_toolsis removed fromfinalize(), and an ordinary child is copied from its parent as onmain. The off-switch is still enforced where it matters: project tools resolve their project from the caller's tags and translate the API's 404PROJECTS_OFF_DETAILinto an agent-visible refusal ("do not retry"), and a tool held by a conversation without aprojecttag refuses with_NOT_IN_PROJECT. Feature-flag tests and parent/child tests were trimmed to match; 245 tests (Projects router + board + cards + parent/child + project tools + feature flag) pass at this exact head.- The merge from
mainbrings v1.63.0 and #6846 (verified-models additions); no carried copies of other PRs. - CI note: the
Persisted settingscheck fails on this head (1 of 55) withModuleNotFoundError: No module named 'litellm.llms.openai.chat.gpt_5_transformation'while generating baseline payloads from the published 1.63.0 baseline under--exclude-newer. I traced this to the main-side model-list commitee062ba88(#6846): the same check fails on that commit onmain, succeeded at98f0fe18dand4b9a72375onmain, and the module imports fine in this workspace with litellm 1.108.3. The failure reproduces on main-line commits and is not introduced by this PR; the Projects code in this range is unaffected by it. Flagging as mergeStateStatus UNSTABLE context rather than a PR finding.
No material findings on the current head.
✅ APPROVED
HUMAN:
AGENT:
Live verification evidence — 2026-11-16
Strong local source-level evidence for the Projects core, not proof of every feature in this large PR pair. The SDK and Canvas #19495 were exercised together with real DeepSeek models and a real browser in Paper. Canvas used the locally built TypeScript client from the SDK branch, not published 1.62.0 packages.
https://github.com/enyst/openhands-evidence/blob/fe6606c8bebd962267c993d4c82d783da87c3a27/.pr/OpenHands/software-agent-sdk/pr-6602/2026-11-16/README.md).2a4b4e20c1d253bc56df2591e16c9166d5dd99d7, plus 3/3 fresh mention and 2/2 client repetitions. The final merge-resolution sourceb9bb0e962c6f3c3f01a37f7bccb62677da8cdeb4passed F37 12/12, two fresh mention repetitions and 121 targeted tests, retaining upstream's independently fixed F37 unchanged. The remaining F36 recipe correction was merged into this branch via #6908. [Before/after runs, negative controls and exact source provenance](https://github.com/enyst/openhands-evidence/blob/fe6606c8bebd962267c993d4c82d783da87c3a27/.pr/OpenHands/software-agent-sdk/pr-6602/2026-11-16/gap-followup/README.md).donereply. [Observed link target](https://github.com/enyst/openhands-evidence/blob/fe6606c8bebd962267c993d4c82d783da87c3a27/.pr/OpenHands/software-agent-sdk/pr-6602/2026-11-16/gap-followup/checks/gap-browser-link.json),[executed click/resulting URL](https://github.com/enyst/openhands-evidence/blob/fe6606c8bebd962267c993d4c82d783da87c3a27/.pr/OpenHands/software-agent-sdk/pr-6602/2026-11-16/gap-followup/checks/gap-browser-click.json),[worker answer](https://github.com/enyst/openhands-evidence/blob/fe6606c8bebd962267c993d4c82d783da87c3a27/.pr/OpenHands/software-agent-sdk/pr-6602/2026-11-16/gap-followup/checks/gap-browser-worker-answer.json).Screenshots illustrate the states; these executed checks establish navigation.Selected Paper screenshots
Projects board: untitled conversation identifiers fit their columns after the separately delivered Canvas wrapping fix.
[Paper Projects board with wrapped conversation identifiers](
https://raw.githubusercontent.com/enyst/openhands-evidence/fe6606c8bebd962267c993d4c82d783da87c3a27/.pr/OpenHands/software-agent-sdk/pr-6602/2026-11-16/paper-wrapped-board.png)Coordinator mention: the real model names its worker with a clickable conversation link.
[Paper coordinator answer with its clickable worker mention](
https://raw.githubusercontent.com/enyst/openhands-evidence/fe6606c8bebd962267c993d4c82d783da87c3a27/.pr/OpenHands/software-agent-sdk/pr-6602/2026-11-16/gap-followup/paper-coordinator-mention.png)After clicking: the linked worker opens with its real answer. Browser snapshots use Canvas
6a8331920af5b4c505d42084764eaa33ba420c7fand SDK launcher source2258f2e38fe1317d19bc80389c5aacf6d2bc9733; detailed build provenance is in the follow-up ledger, separate from the later direct API recipe runs above.[Paper linked worker with its actual done reply](
https://raw.githubusercontent.com/enyst/openhands-evidence/fe6606c8bebd962267c993d4c82d783da87c3a27/.pr/OpenHands/software-agent-sdk/pr-6602/2026-11-16/gap-followup/paper-worker-opened.png)Why
Once a user runs several agents at once, a chat window stops being the right shape: what they need is one conversation to talk to (a coordinator) and a view of every other conversation grouped by what it needs from them. Insider Cat (OpenHands#19495, #6605) already makes a saved, tool-using conversation the user's companion, but it has no project to belong to, and it starts and steers workers by calling the API from its terminal, which no UI can render or check.
This PR gives the Agent Server a Project resource and gives a coordinator typed tools to follow and steer its conversations, so every front end (Canvas, the Insider App, CLI) can build the same board on one open API.
Summary
projectsin/api/settings/experimental, off by default). While it is off, every/api/projectsroute answers 404 (following the switch at once), new conversations get no project tools even when their agent spec lists them (finalizegainswithheld_tools), a member's child is an ordinary child (noprojecttag, worker tools, guidance or memory), and no update or copy of the user's messages reaches a coordinator. Projects on disk are kept. A coordinator started while it was on keeps its tools, and after the switch each project tool call tells it Projects is turned off and not to retry. Agent-server tests run with it on unless markedprojects_off./api/projects: create, list, get, patch, delete;GET /conversationslists members grouped by attention;PUT/DELETE /conversations/{conversation_id}change membership. Records live inprojects.json, with the same atomic-write and file-lock store asworkspaces.json; a corrupted or newer-schema file answers 409 and is never overwritten.POST /api/projectstakes an optionalcoordinator: {working_dir, agent_profile_id?, title?}, plus the start-request fields a client such as Insider needs for its own coordinator:conversation_id,tags,conversation_runtime,agent_launch_additions,confirmation_policy,security_analyzerandmax_iterations(the server still adds the project tag and the tools; a reserved id that already exists is 422). The server starts the coordinator in that workspace from the given profile (or the user's active one) with the coordinator and worker tools, tags it with the project, leaves it idle with no first message, and returns the project withcoordinator_conversation_idset (201). If the coordinator cannot start (no profile, a launch failure), no project is kept and the request answers 422; giving bothcoordinatorandcoordinator_conversation_idis a 422 too. Passing an existingcoordinator_conversation_id, or none, works as before.projectconversation tag (PROJECT_TAG_KEYin the SDK). The conversations a project member starts withstart_child_conversationget theprojecttag, so they join the project with no extra call. They get no other tag of the parent's, such as Insider'sinsidercat/insiderrole.POST /api/conversations/{conversation_id}/eventstakes an optionalrefuse_pending_confirmation. Withrun, it never runs a conversation that is waiting for confirmation, sinceLocalConversation.run()treats that run as approval: a conversation already waiting answers 409 and nothing is saved. A conversation the user paused, or one stopped on an error or stuck, is held for the user the same way (409 with its own detail and the status in astatusfield, which the project tool reads), so another conversation's message cannot resume it, and the check itself is a new option onEventService.run()/send_message(), decided under the run lock. Withrun, the response now also says what happened:runisstarted,queued(a run was already active),waiting_for_confirmation(message kept, not run)paused,error,stuckornot_run. There is no project-only message route; Engel asked for one route every client already uses. Refusals are small typed exceptions,ConversationAlreadyRunning,GoalAlreadyRunningandHeldForUser(with the status), stillValueErrors with the old messages, so callers catch a type instead of comparing strings. Which conversations may run is one rule,admission_refusal()inevent_service.py, which returns the refusal to raise: for another conversation, only an idle or finished one; actions left unconfirmed count as waiting for confirmation whatever the status says; and itsfrom_usercase (Voice'ssend_message_if_idlein feat(agent-server): realtime voice broker for Insider controller conversations #5180) may also resume a pause. A stuck conversation stays stuck when a guarded message is saved, a run that never started is reportednot_run, and the run replacing an interrupted ACP prompt may resume the server's own pause.worker_agent_profile_id(new optional field on project create/patch, 404 for an unknown profile), or else the user's active agent profile. It keeps the parent link, the parent as sender of its task, worktree isolation, and the parent's confirmation policy, plugins, hooks and secrets. It does not take the parent's agent, launch additions or client tools. The server addswrite_artifact,list_artifacts,read_artifact,read_project_memoryandupdate_project_memoryto it. Children outside projects still copy their parent, as before.openhands.tools.project, registered by the agent-server likestart_child_conversation:list_project_conversations,message_project_conversation(a thin tool over the send route) andread_project_conversation. They read the project from the caller's tags at call time, so a conversation only reaches its own project's conversations.project_coordinatorandproject_worker(context/prompts/sections/project.py, pinned by snapshots). The coordinator keeps no coding-workflow sections; it gets ROUTING, BRIEFS, COORDINATING_WORKFLOW, WHAT_YOU_HEAR and TALKING_TO_THE_USER, and a persona replaces only its SOUL. A worker is the default coding agent plus WHO_IS_SPEAKING and YOUR_REPORT: it asks in its report instead of "consulting the user", treats a request whose origin a summary lost as the user's for what to do but never as approval, and never usesgit stashin a shared worktree.prompt_presetis a field ofAgent,OpenHandsAgentSettingsandOpenHandsAgentProfile. The server assigns the role at launch (AgentLaunchAdditions.prompt_preset) to every coordinator and worker it starts, whatever profile it runs, and renders the project (name, goal, who started the worker, theMEMORY.mdindex capped at 6,000 characters) in a dynamic<PROJECT>block (AgentLaunchAdditions.project_context). On first use the server creates two predefined profiles from the user's active one,project-coordinator(terminal, file editor, task tracker, plus the project tools) andproject-worker(the user's tools withoutstart_child_conversation), used when a project names no profile. The section-by-section design is at https://enyst.github.io/arch/project-agent-profiles.html.sender_conversation_id(whichmessage_project_conversationfills in) recordssender: "conversation:<id hex>"on the savedMessageEventand opens with a line telling the receiving agent who sent it (the coordinator, another conversation of the project, or another conversation) and that it approves nothing on the user's behalf. A sender in a project can only message its own project's conversations (422). A run asked for by a sender is always guarded. Both fields live onConversationMessageRequest, the events route's body, not on the SDKSendMessageRequestthat is alsoinitial_message. UIs can then fold such messages as instructions instead of showing them as the user's words. Every child's task message records its parent as sender, and a project worker's brief opens with the same [Sent by ...] line.[Title](conversation:<id hex>)(conversation_mention()in the SDK). The title is cut to one line with no brackets, parentheses, quotes or backslashes, so it cannot end a link or a header early. The coordinator can copy these into what it tells the user, and UIs render them as links. The headers' opening phrases ([Sent by,[Update from,[Reply in,[Message from the user in) are unchanged. Theconversation_mentionsexperimental feature (the agent's read-onlyfind_conversationsandread_conversationtools, their guidance, verify family F38) came from #6851, now merged intomain.mainnow. The reaction lookup fix (#6901) is merged too, so this PR carries no copies of other PRs anymore. Decision cards (ask_user, #6852) are merged intomainnow; this PR only adds the Projects path for workers' questions, and its closing rule (the message saved after a tap's answer closes the question, whoever delivers it).projectsandask_useron): when a member's turn that the coordinator started ends on anask_usercard, the board counts the card as the turn's output (turn=asked,askis the question, no judge), and the coordinator gets an update with the question and options. A coordinator started whileask_useris on getsask_userwith afor_conversationfield; when the user answers that card, by a tap or in the chat, the server records the same answer on the member's card (AskUserAnswerEvent) and runs the member, with the coordinator as sender, through the same confirmation guard as other server deliveries. Only the user's own answer in the coordinator does this; the coordinator's messages cannot answer a member's card. Tests:tests/agent_server/test_project_cards.py. Tool-call approvals are not part of this.project_wake.py): when a member finishes a turn that the coordinator started (its task message or a follow-up), the coordinator gets one message with the member's final message, an "Update from" line and the member as sender, and runs on it, without approving a pending confirmation. Each message the user writes in a member ([Message from the user in ...) and the member's final reply to it ([Reply in ...) are copied to the coordinator too, without running it: they keep it aware of everything said in the project, and running it on each would tempt it to forward them back. The board ignores these copies, so they neither reopen the coordinator nor start a turn. The coordinator does not see members' events;read_project_conversation(overGET /api/projects/{id}/conversations/{conversation_id}/messages, the latest messages andfinishtexts) reads more on demand. When a member the coordinator started stops on the user instead (waiting for approval, an error, stuck), the coordinator is woken with a line saying what it waits on, once per stop; a pause the user made is saved for its awareness without a run. A delivery that finds every run slot taken waits for a free one in the background instead of leaving the update unread, and a failed save is retried. When the server starts, it delivers any update a member's coordinator-started turn should have sent but did not (the server stopped first, or every attempt failed), from the member's event log; turns the user started are not replayed. A run the server's own shutdown cut off is marked as such: it comes back paused rather than errored (the interrupted tool's error says the server was shut down, not that it crashed), the coordinator hears nothing while the server goes down, and after the start it is told a restart interrupted the member, not the user. The board writes a turn's outcome as soon as the run finishes, and the resolution judge's verdict replaces it when it differs.mainnow:ReactionEvent,react/unreacttools,POST /api/conversations/{id}/reactions, and theconversation_reactionsexperimental feature under/api/settings/experimental. With the feature on, every conversation the server starts gets the react tools, project workers included.project_board.py): when a project member's run finishes, the server tags itturn=asked|answered(did the agent's last message ask the user something) and, when the critic scored the task at least 0.9,resolved=auto. The user resolves a conversation withresolved=userthrough the conversation tagPATCH; any new user message clears both, in a project or not.GET /conversationsreportsresolved,turnandautomation_id, andattentionisneeds_you,needs_input,working,finished,idleorresolved(resolved never hides a conversation that is running or blocked on the user). Once the agent stops on a question,turnstaysaskeduntil the user answers, even when a Stop hook makes it go on to afinishthat does not repeat the question. Children do not copyresolved/turn. The messages a/goalloop sends its own conversation now carrysender: "goal_loop", so the board does not take them for the user's words, and messages the server delivers to a coordinator leave its/goalloop running.POST /api/projects/{id}/conversations/{conversation_id}/resolveand/reopen(204) set and clearresolved=user, and both clearresolvenote. The server ownsproject,turn,ask,resolvedandresolvenote: a client'sPATCH /api/conversations/{id}merges its tags under the server's tag lock and keeps those as they are, so a full set read a moment earlier cannot undo a board update or change membership. Those routes are the only way to resolve or reopen.project_artifacts.py): files a project produces or is given that do not belong in a repository. Routes under/api/projects/{id}/artifactsupload (multipart), list, download and delete them, andPOST .../artifacts/from-conversationcopies a file from a member's workspace; that file is opened without following a final symlink or blocking on a FIFO and must stay inside the working directory. Thewrite_artifacttool lets an agent save its deliverables, andlist_artifactsandread_artifactlet it see the project's files and read one: small UTF-8 text comes back inline, anything else is copied into its workspace (.agent_tmp/artifacts/<name>, or a path it names inside the workspace). The tools only work in a project. A download is sent like a workspace file or trajectory download,application/octet-streamas an attachment, plusX-Content-Type-Options: nosniff, so an uploaded HTML or SVG file is saved, never rendered from the server's origin. Deleting a project deletes its artifacts. A project's artifacts and memory share one lock, a thread lock plus a file lock likeprojects.json's, so server processes sharing a persistence folder take turns.asktag, so the board can show what a conversation needs from the user, not only that it needs something.GET /conversationsreportsaskwhileturnisasked; a new user message clears it, and children do not copy it.project_memory.py):MEMORY.md(an index of one-line rules and links) and lowercase.mdtopic files under<persistence dir>/projects/<id>/memory/, beside the project'sartifacts/.GET /api/projects/{id}/memorylists them;GET/PUT/DELETE .../memory/{name}read, write and delete one. Every write names the revision it was based on, and a stale one answers 409 with the current file to merge, so two conversations cannot silently lose each other's change. Theread_project_memoryandupdate_project_memorytools let agents keep it, and a conversation a project member starts getsMEMORY.mdin its first message, marked as data, not instructions.ProjectsClientinclients/typescript(exported from@openhands/typescript-client/clients) covers every/api/projectsroute: projects, membership, the transcript route, artifacts (upload, copy from a conversation, download, read as text, delete) and memory with revisions, with the wire types (Project,ProjectConversation,ProjectArtifact,ProjectMemoryFile, …) andprojectIdKey. The coordinator's start fields reuse the generatedStartConversationRequesttypes, so the public weak-type budget is unchanged. The routes are client-ahead entries inendpoint-audit.config.jsonuntil a release carries them. Canvas can then drop its hand-written Projects service.GET /api/git/repositories/{owner}/{repo}/pull-requests/{number}?provider=github), theHTTPExceptionheaders fix, and reading session-socket messages while a step runs are now onmain(feat(agent-server): read a pull request's state and CI result #6704, fix(agent-server): keep HTTPException headers in error responses #6706, fix(agent-server): read session-socket messages while a step runs #6709), so this PR no longer carries them. Projects UIs use the status route for each conversation's PR card.GET /api/conversations/{id}now reads tags frommeta.json, which a tagPATCHwrites first, instead ofbase_state.json, which a running conversation saves only when its run releases the state lock. Before, resolving a running conversation stayed invisible until its run ended.REST API contract changes
Compared with base OpenAPI
ee062ba88704for public/api/**paths.Issue Number
Fixes #6637. Follows the Insider Cat drafts above and OpenHands#17557.
How to Test
Unit and route tests (real
ConversationService, no mocks for tag persistence):They pass, including the race the send guard handles (a conversation already waiting when the guarded send runs keeps the message, is not run, and stays
waiting_for_confirmation), a subscriber registered by the realConversationService, Stop hook bounces, a FIFO in the workspace, the sender and its header line (and the 422 for a sender outside the target's project), the coordinator update (run only for turns it started), the copies of the user's messages and replies (in order, without a run, ignored by the coordinator's board),/goalnudges and deliveries that leave a coordinator's/goalloop running, a worker started from its profile with only the project tag and the worker tools, hostile titles in mentions, the transcript route, asks (including list questions and a Stop hook bounce), memory revisions and conflicts, the worker note (once, even for a worker's own children), and tags read before the state is saved (that test fails without the fix). Acrosstests/agent_server, the one failure istest_exited_leader_descendant_does_not_block_recovery, which also fails onmainin this container (it needs a reaping PID 1, per the verify-agent-server skill).TypeScript client (in
clients/typescript):npm test(416 passed, including theProjectsClienttest of every route's method, path, query and body),npm run lint,npm run format:check,npm run check:public-type-budget(unchanged, 103 sites),npm run check:agent-server-apiandnpm run audit:endpointspass. Canvas #19495 with this client packed locally and its Projects service moved ontoProjectsClientpassesnpm run typecheckand its project tests.Live, against a real server and a real model (DeepSeek), with the new feature-map family:
All 34 F36 recipes pass on 255c665, including F36.mention, where the coordinator answered with a mention of the conversation it started. All 7 F37 (reactions) recipes pass on d24b2ad, after #6609 merged into main. Among them, a coordinator with
start_child_conversation,list_project_conversationsandmessage_project_conversationstarts a child that joins the project, lists it, and sends it a follow-up that makes it run again; the child's system prompt names the coordinator, and both its messages carry the coordinator as sender. When the child finishes, the coordinator gets its final message and reads its transcript withread_project_conversation. When the user talks to a member directly, the coordinator gets a copy of each message and reply and stays idle, and the member gets no coordinator messages. Asked to tell a conversation that is waiting for approval to "go ahead", the tool refuses, and the conversation keeps waiting with no new message. A conversation whose agent asks a question lists asneeds_inputand is reopened by the answer; an agent withwrite_artifactsaves its report and is refused a path outside its workspace. A question saves itsaskand the answer clears it; an agent adds a line toMEMORY.mdwith the revision it read, a blind overwrite is refused, and the child it starts sees the index in its first message.In a live Insider run with dispatch-only Coordinator and Worker profiles, the Cat started two worker conversations from the Worker profile, both finished and merged their PRs, and a release-notes file was saved to the project. In a full OpenHands stack (verify-openhands, DeepSeek) built from an earlier revision of this branch, a message sent from the Canvas conversation chat cleared
resolved=userand, in a second run,resolved=auto, keeping the other tags, and/api/projectsanswered.Video/Screenshots
See Live verification evidence above for inline Paper screenshots and pinned links to the full evidence ledger, browser observations, before/after failures and corrected F36/F37 runs.
Type
Notes
ConversationMessageRequest) (the send route answers{"success": true}as before unlessrunis set, when it addsrun), new optional keywords onEventService.run()/send_message()(send_messagenow also returns its run outcome;run=Falsestill returnsNone), a newonly_if_absentkeyword onset_conversation_tag, a newkeep_goal_loopkeyword onEventService.send_message(), a new optionalworker_agent_profile_idon projects, and new SDK constants. Existing routes are unchanged, except that conversation reads now report the tags last written, a child's first message records its parent assender,/goalmessages recordgoal_loopassender, and a project member's child starts from an agent profile instead of a copy of its parent. Older SDK clients cannot parse the newReactionEvent, as with any new event type; it belongs in the release notes.projecttag stays. It deletes the project's folder,projects/<id>/(artifacts and memory).turnandaskare heuristics on the last paragraph of the agent's final message.automation_idcomes from theautomationidtag OpenHands automations already set; an automation's conversations join a project only when it starts them with the project's tag.main, found no blockers. It found that the projects store could be set up with the default folder when a relay ran first, and that deliveries to a coordinator stopped its/goalloop while a member's/goalnudges were taken for the user's words; both are fixed and tested, and the sender header now promises a reply only to a coordinator. Still open and minor: a run-less copy turns a finished coordinatoridleon the board, and two members messaging each other at once can wait out the 300 s tool timeout. The bot review approved the PR before the worker, coordinator-prompt and mentions changes. A later outside review found three more: a run-less copy turned a stuck coordinator idle, so the next update resumed it (fixed and tested); two project creations reserving one coordinator id at once both succeeded (the second is now a 422, tested); and restart reconciliation reads only the 50 newest coordinator messages, so an old update can be delivered again (#6817, out of scope here).🤖 Generated with Claude Code
https://claude.ai/code/session_013ArwwJH94xGSYwfoyccT4E
🐳 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:ecbb860-pythonRun
All tags pushed for this build
About Multi-Architecture Support
ecbb860-python) is a multi-arch manifest supporting both amd64 and arm64ecbb860-python-amd64) are also available if neededGenerated by Claude Code