Repository navigation
feat: add chat tree messaging tools - #29617
Closed
jscottmiller wants to merge 4 commits into
Closed
jscottmiller wants to merge 4 commits into
jscottmiller wants to merge 4 commits into
Conversation
Contributor
Docs previewCheck off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here. |
jscottmiller
force-pushed
the
scott/chat-tree/3-messaging
branch
from
September 20, 2026 02:55
92b9504 to
f6b2363
Compare
jscottmiller
force-pushed
the
scott/chat-tree/2-chat-tree
branch
2 times, most recently
from
September 20, 2026 04:27
1718073 to
a33eb1c
Compare
added 3 commits
September 20, 2026 04:33
Plan-mode tool filtering, external MCP visibility, and stop-after tools derived the root chat from a null parent_chat_id. Named tree children have a parent and were treated as subagents, losing write_file, spawn_agent, propose_plan, and the other root-only plan tools. Pass the kind-derived isRootChat that prepareGeneration already computes.
A user prompt delivered by a neighbouring chat's agent carries a server-only sender-chat part with the sender's id, title, relation, and relay hop. Prompt assembly renders it as a provenance header ahead of the text; clients receive it unchanged. The composer prompt history excludes rows carrying the part so relays are not offered as the user's own prompts.
Add send_chat_message and list_chat_tree builtin tools for root and named chats when the chat-tree experiment is enabled. send_chat_message delivers a fire-and-forget user prompt to the direct parent or a direct named child through Server.SendMessage with queue or interrupt delivery, running as the chat owner. The delivered row carries a sender-chat part with the relay hop; a relay depth cap and a per-turn send budget derived from the sender's history bound agent-to-agent loops, and interrupt is downgraded to queue when the target is waiting on a human approval. Hook dispatch failures fail the sender's turn. Record outcomes in chat_tree_messages_total and mark the affected ARCHITECTURE.md sections with TODOs.
jscottmiller
force-pushed
the
scott/chat-tree/3-messaging
branch
from
September 20, 2026 04:34
f6b2363 to
db5fcbd
Compare
Decide the requires_action interrupt downgrade under the target chat lock (SendMessageOptions.QueueOnRequiresAction, PreviousStatus and Downgraded on SendMessageResult), reject deleted chat owners, give duplicated tool call ids separate budget slots, report only typed errors to the model, order list_chat_tree ties by id, and state the relation frame, budget accounting, and conditional reply wording in the tool text. Adds the hook-consumer race test, the worker-driven fake-model budget test, and the compaction and model-only history cases.
jscottmiller
force-pushed
the
scott/chat-tree/3-messaging
branch
from
September 20, 2026 20:09
db5fcbd to
3e72a00
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Behind the
chat-treeexperiment, the agent of a root or named chat gets two builtin tools:send_chat_message(chat_id, message, delivery)delivers a fire-and-forget prompt to the chat's direct parent (chat_id: "parent"or its UUID) or to one of its direct named children, andlist_chat_tree()returns the chat's parent and unarchived named children. Stacked on #29615 (scott/chat-tree/2-chat-tree), which sits on #29614.Delivery goes through
Server.SendMessageas the chat owner (dbauthz.Aswith the owner's RBAC subject, rejecting deleted, suspended, or dormant owners), so queue capacity, theuser_prompt_submithook, queued-message promotion, interruption, error-state recovery, and model resolution apply unchanged.deliveryisqueue(default) orinterrupt, mapped to the existing busy behaviors. Aninterrupttoward a target inrequires_actionis downgraded toqueueso an agent cannot dismiss a pending human approval; the decision is made under the target's chat lock through the new additiveSendMessageOptions.QueueOnRequiresAction, andSendMessageResultgainsPreviousStatusandDowngraded(the HTTP path is unchanged). Targets are limited to the direct parent or directkind = chatchildren with the same owner and organization; subagents neither receive the tools nor can be addressed through them.The delivered row is a
usermessage whose first part is the new server-onlysender-chatpart (sender_chat_id,sender_chat_title,sender_chat_relation,relay_hop). It renders as a provenance header ahead of the text in model prompts, is returned to clients, cannot be submitted by clients, and is excluded fromGetChatUserPromptsByChatID(the composer's prompt history). Loops and floods are bounded by two constants derived from the sender's own history: a relay hop cap of 12 consecutive agent-to-agent deliveries since the last human-initiated turn, and a per-turn send budget of 20 calls for human-initiated turns or 3 for relayed turns, counted from resolvedsend_chat_messagecalls plus the call's position in the current batch (deterministic across re-execution). Acoderd_chatd_chat_tree_messages_total{relation,delivery,outcome}counter records attempts.The first commit fixes a PR1/PR2 sweep miss:
toolAllowedForTurn,filterToolsForTurn, and thefind_toolscandidate list derived "root chat" fromparent_chat_id IS NULL, so a named child in plan mode lost the root tool set. They now key onkind != subagent. It is kept as its own commit so a reviewer can ask for it to be folded into #29615 instead.Notes for reviewers:
SendMessageand the sender's tool result commits later with the assistant step, so a retryable commit failure or replica takeover between the two delivers twice.message_agenthas the same property. An idempotency key would need a new query and is left out of this PR.POST .../messagesdirectly and produce an unmarked human row, as it can today. The caps are storm limiters for the cooperative model, not an authorization control.send_chat_messagecall in a turn counts against the budget, including rejected attempts; the tool description and the rejection text say so.UI contract (for
chat-tree-ui)userrole message whose parts include{type: "sender-chat", sender_chat_id, sender_chat_title, sender_chat_relation, relay_hop}followed bytextparts.sender_chat_relationis the sender's position relative to the receiving chat (parentorchild). The server always writessender_chat_id,sender_chat_relation, andrelay_hop;sender_chat_titleis omitted when the sender has no title. The generated TS marks all four optional: treat a missingsender_chat_idas an unknown sender and a missingrelay_hopas 1. Render the text as a user message with a provenance header (for exampleFrom <title>linking to/agents/<sender_chat_id>, with the relation) and do not show it as typed by the human. The part never appears in client-submitted content. Queued previews (QueuedMessagesList) receive the same parts. Editing such a row throughPATCH .../messages/{message}drops the part and turns it into a human message; disable edit on provenance rows or accept that.GET .../prompts, composer up-arrow) excludes relayed rows. Search includes them.send_chat_messagewith args{chat_id, message, delivery}and a JSON result{chat_id, title, relation, previous_status, status, delivery, downgraded_from?, message_id?, queued_message_id?, relay_hop}or{error, chat_id?, title?}.relationhere is the target's position relative to the sender, the opposite frame from the part'ssender_chat_relation;deliveryisstarted,queued, orinterrupting.list_chat_treereturns{self: {chat_id, title, kind}, parent: {chat_id, title, kind, status} | null, children: [{chat_id, title, status, updated_at}]}withupdated_atas an RFC 3339 timestamp with offset. Render like other builtin tool calls; a link to the target chat is useful.typesGenerated.ts(ChatSenderChatPart,ChatSenderChatRelation,ChatMessagePartTypes). This PR adds only the minimal switch cases inmessageParsing.tsandstreamState.tsneeded for typecheck.Implementation plan (chat-tree-messaging)
Plan: chat-tree-messaging
Project
chat-tree-messaging(implement-medium). Repositorycoder/coder.Branch
scott/chat-tree/3-messaging, based onscott/chat-tree/2-chat-tree(PR #29615, head31e2922ecc; PR #29614 below it). Draft PR with labelexperimentalafter the step 6 checkpoint.Revision 3: incorporates the plan panel review (
REVIEW-plan.md) and the diff panel review(
REVIEW-diff.md).Scope
A builtin chatd tool that lets the agent of a tree chat send a message to its direct parent or to one
of its direct named children, with delivery
queueorinterrupt, fire and forget. A companionread-only tool that returns the caller's tree neighbours. Provenance of the delivered message in the
target transcript. Everything behind the
chat-treeexperiment.Out of scope: UI rendering (contract stated below for project
chat-tree-ui), messaging arbitraryancestors or descendants, wait-for-reply, subagent chats using the tool, reparenting, new HTTP
endpoints, new SQL queries or migrations (none are needed).
Fixed constraints (from PR2 Invariants and API contract)
kindisroot | chat | subagent. The tree root is located by(owner_id, organization_id, kind = root);root_chat_idkeeps its subagent-family meaning and is never the tree root.parent_chat_idis the tree edge for named chats and the spawning chat for subagents. Depth 5.cannot be archived.
wait_agent,message_agent,interrupt_agent,list_agents) accept onlykind = subagentdirect children; PR2 says named children must not be reached through them.codersdk.ExperimentChatTree; off means no user-visible change.What the code does today (verified on the branch)
prepareGeneration(generation_preparer.go:497-534) builds the builtin list pergeneration step, not per turn;
isRootChat := chat.Kind != database.ChatKindSubagent(:172);appendRootChatTools(chatd.go:3823-3881) appendsp.subagentTools(ctx, func() database.Chat { return opts.chat }, opts.modelConfigID). Every tool in the slice is auto-marked builtin(
generation_preparer.go:586-589); there is no separate registry.message_agent(subagent.go:940-995) ->sendSubagentMessage(:1385-1422): trims, checksisSubagentDescendant, loads the target, callsp.SendMessage(SendMessageOptions{ChatID, CreatedBy: targetChat.OwnerID, Content: [text], BusyBehavior}). Result reportschat_id, title, status, interruptedwhereinterruptedis inferred from the pre-send status. The delivered row isa plain user text message with no provenance marker.
Server.SendMessage(chatd.go:1475-1631): validates busy behavior, runs theuser_prompt_submithook (
chathooks.ChatFor(chat, &turnID), admission capacity class, denial returned as error),composes hook parts into the content, then inside
ChatMachine.Update: archived check, modelconfig resolution,
tx.SendMessage(queue or interrupt semantics per ARCHITECTURE.mdPOST .../messages), returnsQueued,QueuedMessage,Message,Chat. Publishes a sidebarstatus-change event. Sending to
errorstate clears the error and starts a turn (E0 -> R0,E1 -> R1).dbauthz.AsChatd(chatd.go:3165 -> worker -> runner ->tool.Run), notthe owner. Owner-scoped contexts are built ad hoc with
callerModelConfigContext(
chatd.go:1640-1658:httpmw.UserRBACSubject+dbauthz.As).Server.experiments(chatd.go:209), used byExperimentChatAdvisor,ExperimentMCPToolSearch,ExperimentChatVirtualDesktop. PR2 gates only in coderd handlers(
api.chatTreeEnabled()); chatd has no tree gate yet.codersdk.ChatMessagePartis both wire and persistence format.hook-context(model only) and
hook-notice(user only) show the pattern for server-attached parts:chatprompt.partsToMessageParts(chatprompt.go:1577-1586) includes or skips them;db2sdk.chatMessageParts(db2sdk.go:1740-1755) stripshook-context; client-submitted contentgoes through
codersdk.ChatInputPart(text|file|file-referenceonly,exp_chats.go:6559), soserver-only parts cannot be submitted.
TestChatMessagePartVariantTags(codersdk/chats_test.go:221)enforces variants tags and omitempty rules;
scripts/apitypingsgenerates the TS union; frontendexhaustive switches in
messageParsing.ts:307andstreamState.ts:220fail typecheck on a newmember until a case is added.
builtinPlanToolAllowed(chatd.go:3474),allowedExploreToolNames(
chatd.go:3547),unbilledSubagentToolNames(subagent_catalog.go:43, kept equal to thesubagentToolsset byTestUnbilledSubagentToolNamesMatchCatalog), tool-name assertions inchatd_test.go:339,:10518,chatd_internal_test.go:640-660.chatloop.Metrics(chatloop/metrics.go), constructed fromcfg.PrometheusRegistry;labeled counter example
ToolErrorsTotal. Subagent tools emit no metrics today.CODER_CHAT_IDenv inexecute;AGENT_BROWSER_SESSION=<chat.ID>exists atchattool/execute.go:152-156).subagent_internal_test.go(newInternalTestServer,chatdTestContext,createInternalParentChat,runSubagentTool,requireToolResponseMap); experiments default tocodersdk.ExperimentsKnownin internal tests, override withwithInternalTestServerExperiments.toolAllowedForTurn/filterToolsForTurn(
chatd.go:3491-3526, call atgeneration_preparer.go:608,mcp_tool_search.go:46,63) stillderive "root chat" from
!parentChatID.Valid. With the experiment on, a named child in plan modeloses
write_file,spawn_agent,propose_plan, and the otherisRootChatplan tools. PR2's planlisted these functions in the
kindsweep. See Open items.Design decisions
D1. Tool surface:
send_chat_messageandlist_chat_treesend_chat_message(chat_id, message, delivery):chat_id: UUID of a direct named child, or the literalparent. Acceptingparentremoves theneed for the model to know its parent id (it is never in the prompt). The parent's UUID is also
accepted.
message: same argument name asmessage_agent, which sits in the same tool list. Non-emptyafter trim, at most
chatTreeMessageMaxRunes = 32768runes (an agent relay is a prompt, not afile transfer; the sender can attach detail through files and reference paths).
delivery:queue(default) orinterrupt, mapped toSendMessageBusyBehaviorQueue/SendMessageBusyBehaviorInterrupt. Same enum values asbusy_behavioron the HTTP endpoint sothe documented state table applies unchanged. Any other value is rejected. When the target is in
requires_action(a human approval is pending there),interruptis downgraded toqueueso anagent cannot dismiss a human's approval prompt; the result reports
delivery: queuedanddowngraded_from: interrupt. The downgrade is decided under the target's chat lock(
SendMessageOptions.QueueOnRequiresAction, evaluated insideChatMachine.Update), so a targetthat reaches
requires_actionbetween the tool's pre-checks and the transition is still notinterrupted. The tool description states that an interrupt-delivered message runs after messages
already queued on the target (
FinishInterruptionpromotes the queue head).list_chat_tree()returns{self: {chat_id, title, kind}, parent: {chat_id, title, kind, status} | null, children: [{chat_id, title, status, updated_at}]}, unarchivedkind = chatchildren only,sorted
updated_at descwithchat_id ascas the tiebreaker. Alternatives considered: (a) put parent and children into thesend_chat_messagedescription at preparation time, asbuildSpawnAgentDescriptiondoes. Rejected:descriptions are rebuilt every generation step, so a long child list is re-sent to the model on every
step and is still stale within the step; (b) system prompt injection, same cost every turn; (c) no
tool, the model relies on the user pasting ids. The tool is one cheap query (
GetChatByIDfor theparent,
GetChildChatsByParentIDs(kinds=[chat], archived=false)for children) and is called onlywhen needed.
Both tools live in a new file
coderd/x/chatd/chattree_tools.goand are appended inappendRootChatToolsafter the subagent tools, only whenp.experiments.Enabled(codersdk.ExperimentChatTree).They are not part of
subagentTools, sounbilledSubagentToolNamesandTestUnbilledSubagentToolNamesMatchCatalogare unaffected and the tools' runtime is billed like anyother builtin tool (they consume no child runtime that is billed elsewhere). Both tools go into the
unconditional
truecase ofbuiltinPlanToolAllowed: they mutate no workspace, and theisRootChatcase is computed from!parentChatID.Valid, which is false for every named child(see the PR2 gap under Open items). Both are
falseinallowedExploreToolNames.D2. Allowed edges: direct parent and direct named children only
rootorchat(the tools are only appended whenisRootChat, i.e. not a subagent).sender.ParentChatID(kindrootorchat) or a row withParentChatID == sender.ID AND kind = chat. Same owner and organization are re-checked explicitlyeven though the edge implies them.
wait_agentreport, their parent maybe blocked inside
wait_agent, and PR2 fixedlist_agents/message_agentto subagent children;giving subagents an upward channel would create a second, unstructured return path into a parent
turn. Revisit only with a use case.
has its own transcript, so a relayed message leaves a trace at every level; (2) authorization stays
one row lookup and one equality check with no recursive walk; (3) fan-out is bounded by
child_chat_countof one node rather than the subtree; (4) it matches the tree API shape the UIuses (
depth,child_chat_count). Parents relay when needed.kind = chatsender (experiment on, tree not yet materialised for this owner)gets
no parent chatforparent. The tool does not callEnsureChatTreeRoot(PR2 decision 5:materialisation happens from the tree GET and
POST /chatsonly).D3. Delivery through
Server.SendMessage, asmessage_agentdoessendChatTreeMessage(ctx, sender database.Chat, target database.Chat, message, delivery)callsp.SendMessage(SendMessageOptions{ChatID: target.ID, CreatedBy: target.OwnerID, Content: [senderPart, text], BusyBehavior, QueueOnRequiresAction: true}).SendMessagegains the additiveQueueOnRequiresActionoption and returnsPreviousStatus(read under the lock) andDowngradedin
SendMessageResult; the HTTP path leaves the option false and is unchanged. This reuses: queuecapacity (
MaxQueueSize),user_prompt_submitadmission (the hook sees the target chat and the message text; a denial is returned to the sender as
the tool error text; a
*dispatch.Erroris returned from the tool callback as a raw Go error, not aJSON error result, so the turn fails closed exactly as
spawn_agentdoes atsubagent.go:744-745;note that
SendMessageparks awaitingtarget inE0on dispatch failure,hook_server.go:84-114),queued-message promotion, interruption (
R0/R1 -> I1, promoted byFinishInterruption),errorstate recovery (
E0 -> R0,E1 -> R1), model config resolution (target'slast_model_config_id),sidebar watch event, spend attribution to the target chat.
Decision: a target in
errorstate is accepted; delivery starts a new turn and clears the error, thesame as a human message. Alternative (reject) would leave an errored child unreachable until a human
intervenes; the sender learns the prior status from the result.
Known limitation: delivery is not idempotent under at-least-once tool execution. The target row
commits inside
SendMessage; the sender's tool result commits later with the assistant step. Aretryable commit failure or a replica takeover between the two re-executes the call and delivers the
message twice (the hop and budget derivation is idempotent, the side effect is not).
message_agenthas the same property. An idempotency key would need a new query and is out of scope here.
Rejections (tool error,
is_errorresult, no exception): experiment off (tool absent);chat_idunparsable;deliverynotqueueorinterrupt; not a neighbour (missing, other owneror org, not parent, not direct named child, subagent, self; one message:
chat is not the parent or a direct child of this chat); target archived (chat is archived, both from the pre-check and fromErrChatArchivedreturned under the machine lock); empty message; message too long; queue full(
MessageQueueFullError); hop or per-turn limits (D6); hook denial; target model unavailable(
ErrNoDefaultChatModelConfigwhen the target's last model is disabled and the org has no default);sender owner not active (D5). Typed and sentinel errors are reported by their own message; any other
store error is logged with the sender and target ids and reported as a fixed
internal error sending chat tree message.Everything in ARCHITECTURE.md about the queue and interruption flow is unchanged; the only new
producer of
SendMessage(m, queue|interrupt)is this tool. TODO markers (no prose edits): under"Generation goroutine" tool list and its "turn limit" bullet (relay chains are bounded by the hop
cap, not the turn limit); under
POST .../messages(the tool is a second producer of the sametransitions, the message carries a
sender-chatpart,interruptis downgraded toqueueonrequires_actiontargets); under "Lifecycle hooks" (admission from inside a turn now also happensfor tree messages and a dispatch failure parks a waiting target); under "Auto-archive loop" (a relay
chain keeps a subtree active).
D4. Provenance: a
sender-chatmessage part on the delivered user rowThe delivered message is a
userrole row (required by the state machine and by hooks) whose firstpart is a new server-only part type:
The server always writes
sender_chat_id,sender_chat_relation, andrelay_hop;sender_chat_titleis omitted when the sender has no title. The TS type marks all four optionalbecause required fields would drop
omitemptyand add keys to every persisted part(
TestChatMessagePartVariantTagsenforces the pairing). The UI treats a missingsender_chat_idas an unknown sender.
chatprompt.partsToMessageParts): renders afantasy.TextPartsuch as[Message from your parent chat "Orchestrator" (chat_id 1234...). It was sent by that chat's agent, not by the user. Do not reply unless a reply is needed; if it is and the send_chat_message tool is available, use it.]ahead of the text. The model therefore sees who sent it and how to answer;the conditional wording covers persisted rows rendered after the experiment is turned off.
db2sdk.chatMessageParts): kept (not stripped) so the UI can render provenance.StripInternalunaffected.ChatInputPartallow list), so a human cannot forge a sender.chatprompt.TitleText(title generation) andtoolsdk userFacingTextlook attextparts only;toolsdk consumers therefore see the relayed text as an ordinary user message and must read the
part for provenance (documented limitation, no change here).
partsToMessagePartshas no defaultbranch, so an older server drops the part and still sends the text (rollback safe).
GetChatUserPromptsByChatID(chats.sql:591-621, the composer's up-arrowhistory) aggregates
textparts of every user row. It gainsAND NOT (content @> '[{"type":"sender-chat"}]')so relayed messages are not offered as the human's own prompts(query edit only,
make gen, no migration, no audit table change). Full-text search keeps indexingthe text: a relayed message is part of the transcript.
PATCH .../messages/{message}rebuilds the content fromChatInputParttypes and drops thesender-chatpart; the row becomes a human message and the hopchain resets. Stated in the UI contract.
chathooks.UserPromptMessagesendsPrompt= text parts andParts= all parts, sohook consumers receive the
sender-chatpart inParts.make genaddsChatSenderChatPartto the TS union; the exhaustive switches inmessageParsing.tsandstreamState.tsget a minimal case (collect intoparsed.senderChat/ no-op) so typecheck passes. Rendering is the UI project's.Alternatives: (a) a text prefix convention such as
[from <title>]: forgeable by the human and bythe model, not renderable distinctly, and
applyPromptOverridecould replace it; (b) a newchat_message_roleor asourcecolumn onchat_messages: migration, every role switch in chatd andthe frontend, and the state machine treats only
userrows as turn starters. (a) is whatmessage_agentdoes today (nothing);message_agentis left as is.D5. Authorization: owner subject through dbauthz
The tool derives an owner context once per call with a new helper
chatOwnerContext(ctx, store, ownerID):GetUserByID(rejecting deleted rows, whichGetAuthorizationUserRolesdoes notfilter), then
httpmw.UserRBACSubject(ctx, store, ownerID, rbac.ScopeAll)anddbauthz.As, failingwhen the user is deleted or the returned status is not
active(the HTTP layer rejects such usersat
httpmw/apikey.go;callerModelConfigContextdiscards the status, and its name and nolintrationale describe model ACLs, not an authorization boundary, so it is not reused). Dormant owners
are rejected too, although the HTTP layer auto-activates them on their next request; failing closed
is acceptable for an agent-initiated send. The sender row is
re-read under
ownerCtx(oneGetChatByID) so the edge check does not depend on the per-stepsnapshot. Target lookup, children listing, and
p.SendMessagerun underownerCtx, so dbauthzenforces chat read and update as the owner and the
user_prompt_submithook and the message areattributed to the owner. This is a privilege reduction relative to
message_agent, which runs asAsChatd.dbauthz.IsNotAuthorizedErrorandsql.ErrNoRowsboth map to the single "not aneighbour" error (no existence oracle, same as
validateChatTreeParent). The explicit edge, owner,organization, and kind checks stay as application checks on top. No audit entry: human messages
(
postChatMessages) are not audited either; provenance is thesender-chatpart plus the sender'stool-call row.
D6. Loops and floods: relay hop counter plus per-turn cap
Two agents can otherwise message each other forever, each message starting a new turn, and a
parent with many children can start a storm.
All counting reads
generationPrepareInput.Messages, the history the generation loop loads perstep with
GetChatMessagesByChatID(visibilityuser|both,deleted = false, compressed rowsincluded, no compaction cut). It is passed to
appendRootChatToolsthroughrootChatToolsOptions.Model-only rows (hook model context, compaction anchors, clear sentinels) are not in it, so they
cannot reset a chain, and a mid-turn compaction does not hide the triggering message. An empty or
unreadable history is a tool error (fail closed), never hop 1.
i.e. the user rows that started the current turn (a turn can start with several unanswered user
rows,
message_conversion.go:559-574). Conservative edge: a previous turn that errored beforewriting an assistant row leaves its user row adjacent to the next human prompt, so that human turn
inherits the earlier row's relayed state and hop. This over-counts and fails closed; no code
handles it specially.
sender-chatpart carriesrelay_hop. Outgoingrelay_hop = 1 + max relay_hop over the pending segment's rows(0 when none carries a part). Taking the max over thewhole segment stops two children from alternating to keep a parent's hop low. Rejected when
relay_hop > chatTreeMessageMaxHops = 12withrelay depth limit reached; wait for a human message before messaging again. A human message starts a fresh chain only when no relayed rowshares its pending segment.
chatTreeHumanTurnSendLimit = 20when the pending segment has no relayedrow,
chatTreeRelayedTurnSendLimit = 3when it has one. A relayed turn typically needs one replyupward and at most a couple of forwards downward; the human turn keeps room for fan-out to many
children. Counting:
send_chat_messagetool-call parts after the pending segment that alreadyhave a matching
tool-result(resolved) plus the position of the current call among theunresolved calls of the current assistant row (the generation loop commits the assistant row with
its tool-call parts before executing them,
generation.go:202-217, 453-460, so the current batchis already in history and an atomic counter would double count). Call k of a batch is allowed iff
resolved + k <= limit; a duplicated call id in one batch occupies the slot of its lastoccurrence. Deterministic, no in-memory state, idempotent under at-least-once tool execution and
replica takeover. Every resolved
send_chat_messagecall counts, including rejected attempts (badid, non-neighbour, hook denial); the tool description and the rejection text
per-turn message limit reached (rejected attempts count too)say so.MaxQueueSize) bounds burst at the receiver.Scope of the caps: hop and budget bound the tool path only. A model holding the owner's credentials
inside a workspace can
POST .../messagesdirectly and produce an unmarked human row; that is apre-existing property of owner credentials, not something this PR changes. The caps are storm
limiters for the cooperative model, not an authorization control.
Trade-off: the hop cap strictly ends ping-pong between two agents after 12 unattended exchanges
(an implement-medium orchestration lifecycle is about six), and the relayed budget bounds a storm
to
20 * 3^11turns in the theoretical worst case where every recipient at every level forwards tothree others; a colluding neighbour can refill the per-turn budget by sending one message, so the
budget is a storm limiter, not an anti-collusion control. Both are single constants. Alternatives:
a global per-owner rate limit (shared state across replicas, and a stuck loop is per pair);
rejecting delivery when the target's last user message came from the sender (breaks legitimate
two-message sequences); a decrementing budget carried in the part (hard bound, but every send must
split it and the semantics are hard to explain to the model).
D7. Tool result
Success:
{chat_id, title, relation: "parent"|"child", previous_status, status, delivery: "started"|"queued"|"interrupting", downgraded_from?: "interrupt", message_id?, queued_message_id?, relay_hop}.relationis the target's position relative to the sender (the opposite frame fromthe delivered part's
sender_chat_relation, which is the sender's position relative to thereceiver).
deliveryderivation:startediff!result.Queued(message_idset);interruptingiff the effective delivery isinterruptandprevious_statuswasrunning(the
R0/R1 -> I1rows of the table); otherwisequeued(queued_message_idset).I0/I1 + interruptandI0/I1 + queuestayinterruptingin status but are reported asqueued, since themessage was only queued.
previous_statusisSendMessageResult.PreviousStatus, read under thetarget's lock immediately before the transition. No
typekey (the target is not a subagent).Errors:
{error, chat_id?, title?}viatoolJSONErrorResponse, except*dispatch.Error, which isreturned as a raw error (D3).
D8. Metrics
One counter vec on
chatloop.Metrics:coderd_chatd_chat_tree_messages_total{relation="parent"| "child", delivery="queue"|"interrupt", outcome="started"|"queued"|"interrupting"|"rejected"}(
deliveryis the effective one after any downgrade for delivered messages and the requested onefor rejections, since the downgrade is only known under the target's lock), and
RecordChatTreeMessage(...)with the nil-receiver guard used by the other recorders. The genericToolErrorsTotal{tool_name}already covers tool errors.D9. Experiment gating
appendRootChatToolsappends both tools only whenp.experiments.Enabled(codersdk.ExperimentChatTree).No dev bypass (matches PR2). With the experiment off nothing changes: no tool, no new part is ever
written. Rows written while on remain readable when off (
sender-chatconversion is unconditional).Sequencing
codersdk/chats.go: part type, relation type, fields,AllChatMessagePartTypes;make gen(apitypings, swagger);
TestChatMessagePartVariantTagspasses; frontend switch cases.chatprompt: prompt rendering ofsender-chat; test.GetChatUserPromptsByChatIDfilter;make gen; query test.coderd/x/chatd/chattree_tools.go: args structs,chatOwnerContext, neighbour resolution(
resolveChatTreeMessageTarget), pending segment, hop and budget counting from history,requires_actiondowngrade,sendChatTreeMessage,list_chat_tree; errorsErrChatTreeNotNeighbour,ErrChatTreeMessageRelayLimit,ErrChatTreeMessageTurnLimit,ErrChatTreeMessageTooLong,ErrChatOwnerInactive;appendRootChatToolswiring withmessagesadded torootChatToolsOptions; plan/explore allow lists; metrics.chattree_tools_internal_test.go, packagechatd, real Postgres viadbtestutil,t.Parallel, unique ids, no sleeps):experiment off -> absent; plan mode -> present for root chats.
sender-chatpart with id, title, relationchild, hop 1; running target withqueue->queued; with
interrupt-> interrupting;errortarget -> started.parentliteral; parent UUID.archived child, empty, too long, unparsable id, legacy parentless sender with
parent.rejected; human-only segment resets; mixed segment takes the max; empty history fails closed.
re-execution of the same tool call id yields the same decision.
interrupttoward arequires_actiontarget is downgraded and reported.user_prompt_submitfires for the target with the text; denial surfaces as tool error;dispatch error returns a raw error and the waiting target is parked in
error(pattern fromhooks_test.go).GetChatByIDon the target fails as owner for a chat the owner cannot read-> neighbour error; suspended owner -> tool error, nothing sent.
list_chat_tree: parent, unarchived children only, sorted; root sender hasparent: null.db2sdkkeeps the part; metrics counter increments.make gen,make fmt,make lint,go test ./coderd/x/chatd/... ./codersdk/... ./coderd/database/db2sdk/...,sitetypecheck.Contract for chat-tree-ui
userrole message whose parts include{type: "sender-chat", sender_chat_id, sender_chat_title, sender_chat_relation: ChatSenderChatRelation, relay_hop}followed bytextparts.
sender_chat_relationis the sender's position relative to the receiving chat. The serveralways writes
sender_chat_id,sender_chat_relation, andrelay_hop;sender_chat_titleisomitted when the sender has no title; the generated TS marks all four optional, treat a missing
sender_chat_idas an unknown sender and a missingrelay_hopas 1. Render the text as a usermessage with a provenance header (for example
From <title>linking to/agents/<sender_chat_id>,with the relation), and do not show it as typed by the human. The part never appears in
client-submitted content. Queued previews (
QueuedMessagesList) receive the same parts. Editingsuch a row drops the part and turns it into a human message; disable edit on provenance rows or
accept that.
GET .../prompts, composer up-arrow) excludes relayed rows. Search includes them.send_chat_messagewith args{chat_id, message, delivery}and aJSON result
{chat_id, title, relation, previous_status, status, delivery, downgraded_from?, message_id?, queued_message_id?, relay_hop}or{error, chat_id?, title?};relationhere isthe target's position relative to the sender, the opposite frame from the part's
sender_chat_relation.list_chat_treewith result{self, parent, children};updated_atisan RFC 3339 timestamp with offset. Render like other builtin tool calls; a link to the target chat
is useful.
typesGenerated.ts(ChatSenderChatPart,ChatSenderChatRelation,ChatMessagePartTypes). This PR adds only the minimal switch cases needed for typecheck.Testing approach
Internal tests in package
chatdwithnewInternalTestServerand real Postgres; tool callbacksinvoked directly through
appendRootChatTools+findToolByName+tool.Run. Hook tests reuse thefake dispatcher pattern from
hooks_test.go. No new SQL, so no dbauthz or query tests beyond theexisting wrappers.
Decisions and constraints (orchestrator, step 3)
toolAllowedForTurn,filterToolsForTurn,mcp_tool_search.goderiving the root toolset from
parent_chat_id): fixed in this PR as its own first commitfix(coderd/x/chatd): derive the root tool set from chat kind, with a test that a named childin plan mode keeps the root tool set. The PR body notes that it corrects a PR1/PR2 sweep miss so
a reviewer can ask for it to be folded down.
interrupton a running parent: allowed, bounded by the caps; the sender chooses thedelivery policy. The
requires_actiondowngrade toqueuestays.All four are constants declared together in
chattree_tools.go.list_chat_treeas a second tool;errorstatetargets accepted; the
GetChatUserPromptsByChatIDedit is in scope.REVIEW-plan.mddispositions stand as recorded.Decisions and constraints (orchestrator, step 6)
SendMessageOptions.QueueOnRequiresAction, evaluated insideChatMachine.Updateagainst the locked chat, withPreviousStatusandDowngradedonSendMessageResult; the HTTP path is unchanged. Covered by a test that flips the target torequires_actionfrom inside theuser_prompt_submithook consumer.(
TestSendChatMessage_TurnBudgetThroughGenerationLoop).REVIEW-diff.mddispositions stand as recorded and are applied.Open questions (resolved at the step 3 checkpoint, kept for the record)
parentChatID.Valid(see "What the code does today"),so a named child in plan mode loses
write_file,spawn_agent,propose_plan, and the otherroot-only plan tools. This plan avoids depending on it (D1). Fix in PR2, in this PR (small:
pass
chat.Kind != subagentthroughfilterToolsForTurn/toolAllowedForTurn/mcp_tool_search.go), or defer?interrupt: allowed (default here, with therequires_actiondowngrade in bothdirections), or rejected toward the parent so a child can never cancel the parent's running work?
Priya rated the running-work case HIGH; the sender is the owner's own agent and the caps bound
repetition, so the plan keeps it allowed. Decide.
list_chat_treeas a second tool versus description or prompt injection (D1). Confirm.errorstate targets accepted (D3). Confirm.Diff review findings and dispositions (REVIEW-diff.md)
REVIEW-diff: chat-tree-messaging
Panel review of the step 5 diff (
31e2922ecc..493e18a506, three commits) by the same threeread-only personas as the plan review: Tomas (state machine, queue and interruption, multi-replica
correctness), Ilse (persistence format, wire contract, codegen, compatibility), Priya (access control,
abuse resistance, fail-closed behaviour). Dispositions below were confirmed by the orchestrator at the
step 6 checkpoint (open items 1 to 3 answered yes; all other dispositions stand as recorded) and are
applied on the branch.
chattree_tools.godowngrade and outcome;chatd.goSendMessagerequires_action->queuedowngrade andprevious_statuscome from an unlocked snapshot read beforeSendMessage; with hooks enabled the window includes a network dispatch. If the target movesrunning -> requires_actionin that window,A0/A1 + interruptcancels the human's pending approval, which the downgrade exists to prevent, and the tool reportsinterruptingwhile the target isrunning.SendMessageOptions.QueueOnRequiresAction boolevaluated againstlockedChat.Statusinsidemachine.Update; returnPreviousStatus(locked) andDowngradedinSendMessageResult; deriveprevious_status,downgraded_from, and the outcome from those. HTTP path unchanged (option false). Test: seedrequires_actionfrom inside the hook consumer so the status flips between snapshot and lock, assert no cancellation rows anddowngraded_from.chattree_tools.gosend;generation.gocommit orderingSendMessage, the sender's tool result commits later; a retryable commit failure or replica takeover re-executes the call and delivers twice. Budget/hop derivation is idempotent; the side effect is not.message_agenthas the same property.message_agentin PLAN D3 and the PR body; an idempotency key would need a new query, which is out of scope for this PR.loadGenerationState -> input.Messages -> rootChatToolsOptions.messages -> tool; every test hands the tool a hand-built history, so a later change to pass pruned prompt rows would silently remove the per-batch cap.send_chat_messagecalls than the relayed budget in one step from a chat whose starting prompt carries asender-chatpart; assert onlychatTreeRelayedTurnSendLimitdeliver and the rest returnErrChatTreeMessageTurnLimit.relayed/maxHop/resolvedSends;[assistant(pending), tool(cancel), human]segment is the human row only. DB case: avisibility = modeluser row after the relayed row is absent fromGetChatMessagesByChatIDand does not affect the hop.interruptingderived from the stalepreviousStatusmisreportsW -> runningandI0 + interruptcases.PreviousStatus);I0/I1 + interruptreportsqueued.relayed/maxHop. Over-count only, fail closed.send_chat_messageattempts (bad id, non-neighbour, hook denial) consume the budget; the error text does not say so.ErrChatTreeMessageTurnLimittext.E1 + queue,I0 + queue/interrupt,MessageQueueFullError,ErrChatArchivedunder the lock.E1 + queue,I0 + interrupt(reportsqueued), and queue-full cases. Archive-under-lock cannot be raced deterministically without a hook; covered by the same locked-status path as #1 and skipped.deliverylabel is the requested delivery on hop/budget rejections but the effective one elsewhere.list_chat_treesortUpdatedAtties are ordered by query order.IDas a tiebreaker.codersdk/chats.goSenderChatIDdocNullUUIDrationale is a doc comment and is copied into swagger, TS, and docs.make gen.relationvs partsender_chat_relationsenderChatPartToTextsend_chat_message; persisted rows render unconditionally, so with the experiment off or after rollback the model is told to use a tool it does not have.RelayHopdocsender-chatvariant.sender_chat_titleis omitted when the title is empty.list_chat_treeupdated_attime.Timemarshals as RFC 3339 with offset; not in the contract.chatOwnerContextactiveowners pass:GetAuthorizationUserRoleshas nodeleted = falsepredicate. HTTP can never act for such a user.GetUserByID(filtersdeleted) beforeUserRBACSubject;sql.ErrNoRows->ErrChatOwnerInactive. Test alongside the suspended case.allowSendErrChatArchived,MessageQueueFullError,UserPromptDeniedError,ErrNoDefaultChatModelConfig,ErrChatTree*,ErrChatOwnerInactive); replace others with a fixed message and log the detail with chat ids.chatstatecancellation textA0/A1 + interruptwrites "interrupted by user message".chatOwnerContextdormantPOST .../messagesdirectly and produce an unmarked row (pre-existing).Verified sound by the panel: budget derivation matches the generation loop (assistant row committed
before
executeLocalTools,input.Messagesunchanged into the tool closure, batch position stable onre-execution); model-only rows cannot reset or hide a chain; queued rows preserve the part and hop
through every promotion path;
*dispatch.Errorescape mirrorsspawn_agentand fails the turn; thenon-racy outcome mapping matches the transition table; no lock nesting; every store call after
chatOwnerContextruns as the owner and the neighbour check has no existence oracle; the part cannotbe forged or stripped by clients or hook overrides (
applyPromptOverridekeeps non-text parts);variants/omitempty/codegen are consistent and
make genis clean; the@>query is correct and keepsthe index; rollback degrades to a plain user message; the prompt header escapes the title with
%q;the first commit keys every plan-mode helper on
ChatKindSubagentwith a regression test.Open items for the step 6 checkpoint (resolved)
SendMessageOptions/SendMessageResult(additive, HTTP path unchanged).Confirmed and applied.
message_agent) rather than adding anidempotency key and query. Confirmed; documented in PLAN D3 and the PR body.
TestSendChatMessage_TurnBudgetThroughGenerationLoop.Generated by Coder Agents on behalf of @jscottmiller.