Skip to content

feat: add chat tree messaging tools - #29617

Closed
jscottmiller wants to merge 4 commits into
scott/chat-tree/2-chat-treefrom
scott/chat-tree/3-messaging
Closed

jscottmiller wants to merge 4 commits into
scott/chat-tree/2-chat-treefrom
scott/chat-tree/3-messaging

Conversation

@jscottmiller

Copy link
Copy Markdown
Contributor

Behind the chat-tree experiment, 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, and list_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.SendMessage as the chat owner (dbauthz.As with the owner's RBAC subject, rejecting deleted, suspended, or dormant owners), so queue capacity, the user_prompt_submit hook, queued-message promotion, interruption, error-state recovery, and model resolution apply unchanged. delivery is queue (default) or interrupt, mapped to the existing busy behaviors. An interrupt toward a target in requires_action is downgraded to queue so an agent cannot dismiss a pending human approval; the decision is made under the target's chat lock through the new additive SendMessageOptions.QueueOnRequiresAction, and SendMessageResult gains PreviousStatus and Downgraded (the HTTP path is unchanged). Targets are limited to the direct parent or direct kind = chat children with the same owner and organization; subagents neither receive the tools nor can be addressed through them.

The delivered row is a user message whose first part is the new server-only sender-chat part (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 from GetChatUserPromptsByChatID (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 resolved send_chat_message calls plus the call's position in the current batch (deterministic across re-execution). A coderd_chatd_chat_tree_messages_total{relation,delivery,outcome} counter records attempts.

The first commit fixes a PR1/PR2 sweep miss: toolAllowedForTurn, filterToolsForTurn, and the find_tools candidate list derived "root chat" from parent_chat_id IS NULL, so a named child in plan mode lost the root tool set. They now key on kind != subagent. It is kept as its own commit so a reviewer can ask for it to be folded into #29615 instead.

Notes for reviewers:

  • Delivery is not idempotent under at-least-once tool execution: the target row commits in SendMessage and 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_agent has the same property. An idempotency key would need a new query and is left out of this PR.
  • The hop and budget caps bound the tool path only; a model holding the owner's credentials inside a workspace can POST .../messages directly and produce an unmarked human row, as it can today. The caps are storm limiters for the cooperative model, not an authorization control.
  • Every send_chat_message call in a turn counts against the budget, including rejected attempts; the tool description and the rejection text say so.
  • ARCHITECTURE.md carries TODO markers where behavior changed; the prose is left for the maintainers.

UI contract (for chat-tree-ui)

  • Provenance row: a user role message whose parts include {type: "sender-chat", sender_chat_id, sender_chat_title, sender_chat_relation, relay_hop} followed by text parts. sender_chat_relation is the sender's position relative to the receiving chat (parent or child). The server always writes sender_chat_id, sender_chat_relation, and relay_hop; sender_chat_title is omitted when the sender has no title. The generated TS marks all four optional: treat a missing sender_chat_id as an unknown sender and a missing relay_hop as 1. Render the text as a user message 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. Editing such a row through PATCH .../messages/{message} drops the part and turns it into a human message; disable edit on provenance rows or accept that.
  • Prompt history (GET .../prompts, composer up-arrow) excludes relayed rows. Search includes them.
  • Tool call rows in the sender: send_chat_message with 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?}. relation here is the target's position relative to the sender, the opposite frame from the part's sender_chat_relation; delivery is started, queued, or interrupting. list_chat_tree returns {self: {chat_id, title, kind}, parent: {chat_id, title, kind, status} | null, children: [{chat_id, title, status, updated_at}]} with updated_at as an RFC 3339 timestamp with offset. Render like other builtin tool calls; a link to the target chat is useful.
  • Types come from typesGenerated.ts (ChatSenderChatPart, ChatSenderChatRelation, ChatMessagePartTypes). This PR adds only the minimal switch cases in messageParsing.ts and streamState.ts needed for typecheck.
Implementation plan (chat-tree-messaging)

Plan: chat-tree-messaging

Project chat-tree-messaging (implement-medium). Repository coder/coder.
Branch scott/chat-tree/3-messaging, based on scott/chat-tree/2-chat-tree (PR #29615, head
31e2922ecc; PR #29614 below it). Draft PR with label experimental after 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 queue or interrupt, fire and forget. A companion
read-only tool that returns the caller's tree neighbours. Provenance of the delivered message in the
target transcript. Everything behind the chat-tree experiment.

Out of scope: UI rendering (contract stated below for project chat-tree-ui), messaging arbitrary
ancestors 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)

  • kind is root | chat | subagent. The tree root is located by (owner_id, organization_id, kind = root); root_chat_id keeps its subagent-family meaning and is never the tree root.
  • parent_chat_id is the tree edge for named chats and the spawning chat for subagents. Depth 5.
  • Archive cascades over the subtree; an archived chat never has an unarchived descendant. Roots
    cannot be archived.
  • Subagent tools (wait_agent, message_agent, interrupt_agent, list_agents) accept only
    kind = subagent direct children; PR2 says named children must not be reached through them.
  • Experiment codersdk.ExperimentChatTree; off means no user-visible change.

What the code does today (verified on the branch)

  • Tool assembly: prepareGeneration (generation_preparer.go:497-534) builds the builtin list per
    generation step, not per turn; isRootChat := chat.Kind != database.ChatKindSubagent (:172);
    appendRootChatTools (chatd.go:3823-3881) appends p.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, checks
    isSubagentDescendant, loads the target, calls p.SendMessage(SendMessageOptions{ChatID, CreatedBy: targetChat.OwnerID, Content: [text], BusyBehavior}). Result reports chat_id, title, status, interrupted where interrupted is inferred from the pre-send status. The delivered row is
    a plain user text message with no provenance marker.
  • Server.SendMessage (chatd.go:1475-1631): validates busy behavior, runs the user_prompt_submit
    hook (chathooks.ChatFor(chat, &turnID), admission capacity class, denial returned as error),
    composes hook parts into the content, then inside ChatMachine.Update: archived check, model
    config resolution, tx.SendMessage (queue or interrupt semantics per ARCHITECTURE.md
    POST .../messages), returns Queued, QueuedMessage, Message, Chat. Publishes a sidebar
    status-change event. Sending to error state clears the error and starts a turn (E0 -> R0,
    E1 -> R1).
  • Tool callback context is dbauthz.AsChatd (chatd.go:3165 -> worker -> runner -> tool.Run), not
    the owner. Owner-scoped contexts are built ad hoc with callerModelConfigContext
    (chatd.go:1640-1658: httpmw.UserRBACSubject + dbauthz.As).
  • Experiments: Server.experiments (chatd.go:209), used by ExperimentChatAdvisor,
    ExperimentMCPToolSearch, ExperimentChatVirtualDesktop. PR2 gates only in coderd handlers
    (api.chatTreeEnabled()); chatd has no tree gate yet.
  • Message parts: codersdk.ChatMessagePart is 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) strips hook-context; client-submitted content
    goes through codersdk.ChatInputPart (text|file|file-reference only, exp_chats.go:6559), so
    server-only parts cannot be submitted. TestChatMessagePartVariantTags (codersdk/chats_test.go:221)
    enforces variants tags and omitempty rules; scripts/apitypings generates the TS union; frontend
    exhaustive switches in messageParsing.ts:307 and streamState.ts:220 fail typecheck on a new
    member until a case is added.
  • Name lists a new tool must join: builtinPlanToolAllowed (chatd.go:3474), allowedExploreToolNames
    (chatd.go:3547), unbilledSubagentToolNames (subagent_catalog.go:43, kept equal to the
    subagentTools set by TestUnbilledSubagentToolNamesMatchCatalog), tool-name assertions in
    chatd_test.go:339, :10518, chatd_internal_test.go:640-660.
  • Metrics: chatloop.Metrics (chatloop/metrics.go), constructed from cfg.PrometheusRegistry;
    labeled counter example ToolErrorsTotal. Subagent tools emit no metrics today.
  • The model is never told its own chat id or parent id (no prompt text, no CODER_CHAT_ID env in
    execute; AGENT_BROWSER_SESSION=<chat.ID> exists at chattool/execute.go:152-156).
  • Tests: subagent_internal_test.go (newInternalTestServer, chatdTestContext,
    createInternalParentChat, runSubagentTool, requireToolResponseMap); experiments default to
    codersdk.ExperimentsKnown in internal tests, override with withInternalTestServerExperiments.
  • Observed PR2 gap (not this project's scope, flagged): toolAllowedForTurn / filterToolsForTurn
    (chatd.go:3491-3526, call at generation_preparer.go:608, mcp_tool_search.go:46,63) still
    derive "root chat" from !parentChatID.Valid. With the experiment on, a named child in plan mode
    loses write_file, spawn_agent, propose_plan, and the other isRootChat plan tools. PR2's plan
    listed these functions in the kind sweep. See Open items.

Design decisions

D1. Tool surface: send_chat_message and list_chat_tree

send_chat_message(chat_id, message, delivery):

  • chat_id: UUID of a direct named child, or the literal parent. Accepting parent removes the
    need 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 as message_agent, which sits in the same tool list. Non-empty
    after trim, at most chatTreeMessageMaxRunes = 32768 runes (an agent relay is a prompt, not a
    file transfer; the sender can attach detail through files and reference paths).
  • delivery: queue (default) or interrupt, mapped to SendMessageBusyBehaviorQueue /
    SendMessageBusyBehaviorInterrupt. Same enum values as busy_behavior on the HTTP endpoint so
    the documented state table applies unchanged. Any other value is rejected. When the target is in
    requires_action (a human approval is pending there), interrupt is downgraded to queue so an
    agent cannot dismiss a human's approval prompt; the result reports delivery: queued and
    downgraded_from: interrupt. The downgrade is decided under the target's chat lock
    (SendMessageOptions.QueueOnRequiresAction, evaluated inside ChatMachine.Update), so a target
    that reaches requires_action between the tool's pre-checks and the transition is still not
    interrupted. The tool description states that an interrupt-delivered message runs after messages
    already queued on the target (FinishInterruption promotes 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}]}, unarchived kind = chat children only,
sorted updated_at desc with chat_id asc as the tiebreaker. Alternatives considered: (a) put parent and children into the
send_chat_message description at preparation time, as buildSpawnAgentDescription does. 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 (GetChatByID for the
parent, GetChildChatsByParentIDs(kinds=[chat], archived=false) for children) and is called only
when needed.

Both tools live in a new file coderd/x/chatd/chattree_tools.go and are appended in
appendRootChatTools after the subagent tools, only when p.experiments.Enabled(codersdk.ExperimentChatTree).
They are not part of subagentTools, so unbilledSubagentToolNames and
TestUnbilledSubagentToolNamesMatchCatalog are unaffected and the tools' runtime is billed like any
other builtin tool (they consume no child runtime that is billed elsewhere). Both tools go into the
unconditional true case of builtinPlanToolAllowed: they mutate no workspace, and the
isRootChat case is computed from !parentChatID.Valid, which is false for every named child
(see the PR2 gap under Open items). Both are false in allowedExploreToolNames.

D2. Allowed edges: direct parent and direct named children only

  • Sender kind root or chat (the tools are only appended when isRootChat, i.e. not a subagent).
  • Target must be either sender.ParentChatID (kind root or chat) or a row with
    ParentChatID == sender.ID AND kind = chat. Same owner and organization are re-checked explicitly
    even though the edge implies them.
  • Subagents do not get the tool. Their result channel is the wait_agent report, their parent may
    be blocked inside wait_agent, and PR2 fixed list_agents/message_agent to subagent children;
    giving subagents an upward channel would create a second, unstructured return path into a parent
    turn. Revisit only with a use case.
  • No arbitrary ancestors or descendants. Reason: (1) each hop is a chat the user can see and that
    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_count of one node rather than the subtree; (4) it matches the tree API shape the UI
    uses (depth, child_chat_count). Parents relay when needed.
  • Self-send is rejected as "not a neighbour" (self is neither parent nor child).
  • A legacy parentless kind = chat sender (experiment on, tree not yet materialised for this owner)
    gets no parent chat for parent. The tool does not call EnsureChatTreeRoot (PR2 decision 5:
    materialisation happens from the tree GET and POST /chats only).

D3. Delivery through Server.SendMessage, as message_agent does

sendChatTreeMessage(ctx, sender database.Chat, target database.Chat, message, delivery) calls
p.SendMessage(SendMessageOptions{ChatID: target.ID, CreatedBy: target.OwnerID, Content: [senderPart, text], BusyBehavior, QueueOnRequiresAction: true}). SendMessage gains the additive
QueueOnRequiresAction option and returns PreviousStatus (read under the lock) and Downgraded
in SendMessageResult; the HTTP path leaves the option false and is unchanged. This reuses: queue
capacity (MaxQueueSize), user_prompt_submit
admission (the hook sees the target chat and the message text; a denial is returned to the sender as
the tool error text; a *dispatch.Error is returned from the tool callback as a raw Go error, not a
JSON error result, so the turn fails closed exactly as spawn_agent does at subagent.go:744-745;
note that SendMessage parks a waiting target in E0 on dispatch failure, hook_server.go:84-114),
queued-message promotion, interruption (R0/R1 -> I1, promoted by FinishInterruption), error
state recovery (E0 -> R0, E1 -> R1), model config resolution (target's last_model_config_id),
sidebar watch event, spend attribution to the target chat.

Decision: a target in error state is accepted; delivery starts a new turn and clears the error, the
same 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. A
retryable 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_agent
has the same property. An idempotency key would need a new query and is out of scope here.

Rejections (tool error, is_error result, no exception): experiment off (tool absent);
chat_id unparsable; delivery not queue or interrupt; not a neighbour (missing, other owner
or 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 from
ErrChatArchived returned under the machine lock); empty message; message too long; queue full
(MessageQueueFullError); hop or per-turn limits (D6); hook denial; target model unavailable
(ErrNoDefaultChatModelConfig when 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 same
transitions, the message carries a sender-chat part, interrupt is downgraded to queue on
requires_action targets); under "Lifecycle hooks" (admission from inside a turn now also happens
for 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-chat message part on the delivered user row

The delivered message is a user role row (required by the state machine and by hooks) whose first
part is a new server-only part type:

ChatMessagePartTypeSenderChat ChatMessagePartType = "sender-chat"

// ChatSenderChatRelation is the sender's position relative to the receiving chat.
type ChatSenderChatRelation string
const (
    ChatSenderChatRelationParent ChatSenderChatRelation = "parent"
    ChatSenderChatRelationChild  ChatSenderChatRelation = "child"
)

// Fields are optional in the variants tag and omitempty so no other stored part grows.
// *uuid.UUID rather than uuid.NullUUID: NullUUID marshals as null and is never omitted
// (every stored part today carries "mcp_server_config_id":null), a pointer is omitted.
SenderChatID       *uuid.UUID             `json:"sender_chat_id,omitempty" format:"uuid" variants:"sender-chat?"`
SenderChatTitle    string                 `json:"sender_chat_title,omitempty" variants:"sender-chat?"`
SenderChatRelation ChatSenderChatRelation `json:"sender_chat_relation,omitempty" enums:"parent,child" variants:"sender-chat?"`
RelayHop           int                    `json:"relay_hop,omitempty" variants:"sender-chat?"` // at least 1 when written; readers treat a missing value as 1

The server always writes sender_chat_id, sender_chat_relation, and relay_hop;
sender_chat_title is omitted when the sender has no title. The TS type marks all four optional
because required fields would drop omitempty and add keys to every persisted part
(TestChatMessagePartVariantTags enforces the pairing). The UI treats a missing sender_chat_id
as an unknown sender.

  • Prompt assembly (chatprompt.partsToMessageParts): renders a fantasy.TextPart such 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.
  • Client conversion (db2sdk.chatMessageParts): kept (not stripped) so the UI can render provenance.
    StripInternal unaffected.
  • Client submission: impossible (ChatInputPart allow list), so a human cannot forge a sender.
  • chatprompt.TitleText (title generation) and toolsdk userFacingText look at text parts 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). partsToMessageParts has no default
    branch, so an older server drops the part and still sends the text (rollback safe).
  • Prompt history: GetChatUserPromptsByChatID (chats.sql:591-621, the composer's up-arrow
    history) aggregates text parts of every user row. It gains AND 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 indexing
    the text: a relayed message is part of the transcript.
  • Editing a relayed row through PATCH .../messages/{message} rebuilds the content from
    ChatInputPart types and drops the sender-chat part; the row becomes a human message and the hop
    chain resets. Stated in the UI contract.
  • Hook payload: chathooks.UserPromptMessage sends Prompt = text parts and Parts = all parts, so
    hook consumers receive the sender-chat part in Parts.
  • Frontend: make gen adds ChatSenderChatPart to the TS union; the exhaustive switches in
    messageParsing.ts and streamState.ts get a minimal case (collect into
    parsed.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 by
the model, not renderable distinctly, and applyPromptOverride could replace it; (b) a new
chat_message_role or a source column on chat_messages: migration, every role switch in chatd and
the frontend, and the state machine treats only user rows as turn starters. (a) is what
message_agent does today (nothing); message_agent is 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, which GetAuthorizationUserRoles does not
filter), then httpmw.UserRBACSubject(ctx, store, ownerID, rbac.ScopeAll) and dbauthz.As, failing
when the user is deleted or the returned status is not active (the HTTP layer rejects such users
at httpmw/apikey.go; callerModelConfigContext discards the status, and its name and nolint
rationale 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 (one GetChatByID) so the edge check does not depend on the per-step
snapshot. Target lookup, children listing, and p.SendMessage run under ownerCtx, so dbauthz
enforces chat read and update as the owner and the user_prompt_submit hook and the message are
attributed to the owner. This is a privilege reduction relative to message_agent, which runs as
AsChatd. dbauthz.IsNotAuthorizedError and sql.ErrNoRows both map to the single "not a
neighbour" 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 the sender-chat part plus the sender's
tool-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 per
step with GetChatMessagesByChatID (visibility user|both, deleted = false, compressed rows
included, no compaction cut). It is passed to appendRootChatTools through rootChatToolsOptions.
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.

  • Pending segment: the user rows after the last assistant row that has no unresolved tool calls,
    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 before
    writing 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.
  • Relay hop: every delivered sender-chat part carries relay_hop. Outgoing relay_hop = 1 + max relay_hop over the pending segment's rows (0 when none carries a part). Taking the max over the
    whole segment stops two children from alternating to keep a parent's hop low. Rejected when
    relay_hop > chatTreeMessageMaxHops = 12 with relay depth limit reached; wait for a human message before messaging again. A human message starts a fresh chain only when no relayed row
    shares its pending segment.
  • Per-turn send budget: chatTreeHumanTurnSendLimit = 20 when the pending segment has no relayed
    row, chatTreeRelayedTurnSendLimit = 3 when it has one. A relayed turn typically needs one reply
    upward and at most a couple of forwards downward; the human turn keeps room for fan-out to many
    children. Counting: send_chat_message tool-call parts after the pending segment that already
    have a matching tool-result (resolved) plus the position of the current call among the
    unresolved 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 batch
    is 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 last
    occurrence. Deterministic, no in-memory state, idempotent under at-least-once tool execution and
    replica takeover. Every resolved send_chat_message call counts, including rejected attempts (bad
    id, non-neighbour, hook denial); the tool description and the rejection text
    per-turn message limit reached (rejected attempts count too) say so.
  • Queue capacity on the target (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 .../messages directly and produce an unmarked human row; that is a
pre-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^11 turns in the theoretical worst case where every recipient at every level forwards to
three 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}. relation is the target's position relative to the sender (the opposite frame from
the delivered part's sender_chat_relation, which is the sender's position relative to the
receiver). delivery derivation: started iff !result.Queued (message_id set);
interrupting iff the effective delivery is interrupt and previous_status was running
(the R0/R1 -> I1 rows of the table); otherwise queued (queued_message_id set). I0/I1 + interrupt and I0/I1 + queue stay interrupting in status but are reported as queued, since the
message was only queued. previous_status is SendMessageResult.PreviousStatus, read under the
target's lock immediately before the transition. No type key (the target is not a subagent).
Errors: {error, chat_id?, title?} via toolJSONErrorResponse, except *dispatch.Error, which is
returned 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"}
(delivery is the effective one after any downgrade for delivered messages and the requested one
for 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 generic
ToolErrorsTotal{tool_name} already covers tool errors.

D9. Experiment gating

appendRootChatTools appends both tools only when p.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-chat conversion is unconditional).

Sequencing

  1. codersdk/chats.go: part type, relation type, fields, AllChatMessagePartTypes; make gen
    (apitypings, swagger); TestChatMessagePartVariantTags passes; frontend switch cases.
  2. chatprompt: prompt rendering of sender-chat; test. GetChatUserPromptsByChatID filter;
    make gen; query test.
  3. coderd/x/chatd/chattree_tools.go: args structs, chatOwnerContext, neighbour resolution
    (resolveChatTreeMessageTarget), pending segment, hop and budget counting from history,
    requires_action downgrade, sendChatTreeMessage, list_chat_tree; errors
    ErrChatTreeNotNeighbour, ErrChatTreeMessageRelayLimit, ErrChatTreeMessageTurnLimit,
    ErrChatTreeMessageTooLong, ErrChatOwnerInactive; appendRootChatTools wiring with
    messages added to rootChatToolsOptions; plan/explore allow lists; metrics.
  4. ARCHITECTURE.md TODO markers only.
  5. Tests (chattree_tools_internal_test.go, package chatd, real Postgres via dbtestutil,
    t.Parallel, unique ids, no sleeps):
    • tool presence: experiment on -> both tools for root and named chat, absent for subagent;
      experiment off -> absent; plan mode -> present for root chats.
    • child -> parent (kind chat and kind root): waiting target -> started, message row has
      sender-chat part with id, title, relation child, hop 1; running target with queue ->
      queued; with interrupt -> interrupting; error target -> started.
    • parent -> child by UUID; parent literal; parent UUID.
    • rejections: self, sibling, grandchild, subagent child, other owner's chat (same message),
      archived child, empty, too long, unparsable id, legacy parentless sender with parent.
    • hop: message delivered with hop 12 in the receiver's pending segment -> receiver's send
      rejected; human-only segment resets; mixed segment takes the max; empty history fails closed.
    • per-turn budget: resolved calls plus batch position; relayed turn limit 3; human turn limit 20;
      re-execution of the same tool call id yields the same decision.
    • interrupt toward a requires_action target is downgraded and reported.
    • hook: user_prompt_submit fires 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 from
      hooks_test.go).
    • authorization: GetChatByID on the target fails as owner for a chat the owner cannot read
      -> neighbour error; suspended owner -> tool error, nothing sent.
    • prompt history query excludes relayed rows.
    • list_chat_tree: parent, unarchived children only, sorted; root sender has parent: null.
    • prompt assembly renders the header; db2sdk keeps the part; metrics counter increments.
  6. Checks: make gen, make fmt, make lint, go test ./coderd/x/chatd/... ./codersdk/... ./coderd/database/db2sdk/..., site typecheck.

Contract for chat-tree-ui

  • Provenance row: a user role message whose parts include {type: "sender-chat", sender_chat_id, sender_chat_title, sender_chat_relation: ChatSenderChatRelation, relay_hop} followed by text
    parts. sender_chat_relation is the sender's position relative to the receiving chat. The server
    always writes sender_chat_id, sender_chat_relation, and relay_hop; sender_chat_title is
    omitted when the sender has no title; the generated TS marks all four optional, treat a missing
    sender_chat_id as an unknown sender and a missing relay_hop as 1. Render the text as a user
    message 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. Editing
    such a row drops the part and turns it into a human message; disable edit on provenance rows or
    accept that.
  • Prompt history (GET .../prompts, composer up-arrow) excludes relayed rows. Search includes them.
  • Tool call rows in the sender: send_chat_message with 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?}; relation here is
    the target's position relative to the sender, the opposite frame from the part's
    sender_chat_relation. list_chat_tree with result {self, parent, children}; updated_at is
    an RFC 3339 timestamp with offset. Render like other builtin tool calls; a link to the target chat
    is useful.
  • Types come from typesGenerated.ts (ChatSenderChatPart, ChatSenderChatRelation,
    ChatMessagePartTypes). This PR adds only the minimal switch cases needed for typecheck.

Testing approach

Internal tests in package chatd with newInternalTestServer and real Postgres; tool callbacks
invoked directly through appendRootChatTools + findToolByName + tool.Run. Hook tests reuse the
fake dispatcher pattern from hooks_test.go. No new SQL, so no dbauthz or query tests beyond the
existing wrappers.

Decisions and constraints (orchestrator, step 3)

  1. PR2 gap (toolAllowedForTurn, filterToolsForTurn, mcp_tool_search.go deriving the root tool
    set from parent_chat_id): fixed in this PR as its own first commit
    fix(coderd/x/chatd): derive the root tool set from chat kind, with a test that a named child
    in 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.
  2. Upward interrupt on a running parent: allowed, bounded by the caps; the sender chooses the
    delivery policy. The requires_action downgrade to queue stays.
  3. Limits confirmed: 32768 runes, 12 hops, 20 sends per human-initiated turn, 3 per relayed turn.
    All four are constants declared together in chattree_tools.go.
  4. Confirmed: subagents excluded as senders; list_chat_tree as a second tool; error state
    targets accepted; the GetChatUserPromptsByChatID edit is in scope.
  5. All REVIEW-plan.md dispositions stand as recorded.

Decisions and constraints (orchestrator, step 6)

  1. REVIEW-diff chore: Initial GHA workflow #1: the additive SendMessageOptions.QueueOnRequiresAction, evaluated inside
    ChatMachine.Update against the locked chat, with PreviousStatus and Downgraded on
    SendMessageResult; the HTTP path is unchanged. Covered by a test that flips the target to
    requires_action from inside the user_prompt_submit hook consumer.
  2. REVIEW-diff chore: Initial database scaffolding #2: non-idempotent delivery is documented (D3 and the PR body); no idempotency key.
  3. REVIEW-diff chore: Add golangci-lint and codecov #3: the end-to-end fake-model budget test is included
    (TestSendChatMessage_TurnBudgetThroughGenerationLoop).
  4. All other REVIEW-diff.md dispositions stand as recorded and are applied.

Open questions (resolved at the step 3 checkpoint, kept for the record)

  1. PR2 gap: plan-mode tool filtering keys on parentChatID.Valid (see "What the code does today"),
    so a named child in plan mode loses write_file, spawn_agent, propose_plan, and the other
    root-only plan tools. This plan avoids depending on it (D1). Fix in PR2, in this PR (small:
    pass chat.Kind != subagent through filterToolsForTurn / toolAllowedForTurn /
    mcp_tool_search.go), or defer?
  2. Upward interrupt: allowed (default here, with the requires_action downgrade in both
    directions), 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.
  3. Subagents excluded from the tool (D2). Confirm.
  4. Limits: 32768 runes, 12 hops, 20 sends per human turn, 3 per relayed turn. Confirm or adjust.
  5. list_chat_tree as a second tool versus description or prompt injection (D1). Confirm.
  6. error state targets accepted (D3). Confirm.
  7. Prompt history query edit (excluding relayed rows) is in scope (D4). 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 three
read-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.

# Reviewer Severity Location Finding Disposition Action
1 Tomas, Priya high / medium chattree_tools.go downgrade and outcome; chatd.go SendMessage The requires_action -> queue downgrade and previous_status come from an unlocked snapshot read before SendMessage; with hooks enabled the window includes a network dispatch. If the target moves running -> requires_action in that window, A0/A1 + interrupt cancels the human's pending approval, which the downgrade exists to prevent, and the tool reports interrupting while the target is running. accept Add SendMessageOptions.QueueOnRequiresAction bool evaluated against lockedChat.Status inside machine.Update; return PreviousStatus (locked) and Downgraded in SendMessageResult; derive previous_status, downgraded_from, and the outcome from those. HTTP path unchanged (option false). Test: seed requires_action from inside the hook consumer so the status flips between snapshot and lock, assert no cancellation rows and downgraded_from.
2 Tomas medium chattree_tools.go send; generation.go commit ordering Delivery is not idempotent under at-least-once tool execution: the target row commits in SendMessage, 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_agent has the same property. accept (document) Record as a known limitation shared with message_agent in PLAN D3 and the PR body; an idempotency key would need a new query, which is out of scope for this PR.
3 Tomas medium tests No test exercises the real wiring 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. accept Add an end-to-end test with a fake model emitting more send_chat_message calls than the relayed budget in one step from a chat whose starting prompt carries a sender-chat part; assert only chatTreeRelayedTurnSendLimit deliver and the rest return ErrChatTreeMessageTurnLimit.
4 Tomas medium tests REVIEW-plan #5 asked for compaction-boundary and model-only-row coverage; none present. accept Unit cases: compressed assistant/tool rows after the relayed row keep relayed/maxHop/resolvedSends; [assistant(pending), tool(cancel), human] segment is the human row only. DB case: a visibility = model user row after the relayed row is absent from GetChatMessagesByChatID and does not affect the hop.
5 Tomas, Priya low outcome mapping interrupting derived from the stale previousStatus misreports W -> running and I0 + interrupt cases. accept Subsumed by #1 (locked PreviousStatus); I0/I1 + interrupt reports queued.
6 Tomas low pending segment A previous turn that errored before writing an assistant row leaves its user row adjacent to the next human prompt, so the human's fresh turn inherits relayed/maxHop. Over-count only, fail closed. accept (document) State in PLAN D6 as a conservative edge; no code change.
7 Tomas low budget counting Rejected send_chat_message attempts (bad id, non-neighbour, hook denial) consume the budget; the error text does not say so. accept Keep counting every resolved call (conservative); say so in the tool description and in ErrChatTreeMessageTurnLimit text.
8 Tomas low tests Untested transitions: E1 + queue, I0 + queue/interrupt, MessageQueueFullError, ErrChatArchived under the lock. accept (part) Add E1 + queue, I0 + interrupt (reports queued), 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.
9 Tomas nit metrics delivery label is the requested delivery on hop/budget rejections but the effective one elsewhere. accept Compute the effective delivery before the rejection checks; requires the locked decision from #1, so rejections before the lock use the requested value and the label is documented as "requested for pre-send rejections".
10 Tomas nit list_chat_tree sort UpdatedAt ties are ordered by query order. accept Add ID as a tiebreaker.
11 Ilse low codersdk/chats.go SenderChatID doc The pointer-versus-NullUUID rationale is a doc comment and is copied into swagger, TS, and docs. accept Keep the first sentence as the doc comment; move the rationale to a non-doc comment; make gen.
12 Ilse low tool result relation vs part sender_chat_relation The same enum is emitted with opposite frames (target relative to sender in the result, sender relative to receiver in the part) and the inversion is not stated. accept State the frame in the tool description and in the UI contract for tool call rows.
13 Ilse low senderChatPartToText The header tells the model to reply with send_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. accept Reword: "Do not reply unless a reply is needed; if it is and the send_chat_message tool is available, use it."
14 Ilse nit RelayHop doc "absent means the prompt was not relayed" is stated on a field that exists only inside the sender-chat variant. accept Reword to "at least 1 when written; readers treat a missing value as 1".
15 Ilse nit PLAN contract "the server always writes all four fields" is stronger than the code: sender_chat_title is omitted when the title is empty. accept Adjust the contract wording in PLAN.
16 Ilse nit list_chat_tree updated_at time.Time marshals as RFC 3339 with offset; not in the contract. accept (document) Add to the UI contract; keep the field.
17 Priya low chatOwnerContext Deleted-but-active owners pass: GetAuthorizationUserRoles has no deleted = false predicate. HTTP can never act for such a user. accept Load the owner with GetUserByID (filters deleted) before UserRBACSubject; sql.ErrNoRows -> ErrChatOwnerInactive. Test alongside the suspended case.
18 Priya low allowSend Duplicate tool call ids in one assistant row share a position and all pass. accept Use the index of the last occurrence of the id, so duplicates occupy separate slots.
19 Priya low error responses Unexpected store errors are returned verbatim to the model (parity with subagent tools). accept Pass through typed/sentinel errors (ErrChatArchived, MessageQueueFullError, UserPromptDeniedError, ErrNoDefaultChatModelConfig, ErrChatTree*, ErrChatOwnerInactive); replace others with a fixed message and log the detail with chat ids.
20 Priya nit chatstate cancellation text Agent-initiated A0/A1 + interrupt writes "interrupted by user message". reject Unreachable from this tool once #1 enforces the downgrade under the lock.
21 Priya nit chatOwnerContext dormant Dormant owners are rejected while HTTP auto-activates them. accept (document) Fail closed is acceptable; note in PLAN D5.
22 Priya info scope Hop and budget bound only the tool path; a model with owner credentials in the workspace can POST .../messages directly and produce an unmarked row (pre-existing). accept (document) State in the PR body and PLAN D6 that the caps are storm limiters for the cooperative model, not an authorization control.

Verified sound by the panel: budget derivation matches the generation loop (assistant row committed
before executeLocalTools, input.Messages unchanged into the tool closure, batch position stable on
re-execution); model-only rows cannot reset or hide a chain; queued rows preserve the part and hop
through every promotion path; *dispatch.Error escape mirrors spawn_agent and fails the turn; the
non-racy outcome mapping matches the transition table; no lock nesting; every store call after
chatOwnerContext runs as the owner and the neighbour check has no existence oracle; the part cannot
be forged or stripped by clients or hook overrides (applyPromptOverride keeps non-text parts);
variants/omitempty/codegen are consistent and make gen is clean; the @> query is correct and keeps
the 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 ChatKindSubagent with a regression test.

Open items for the step 6 checkpoint (resolved)

  1. Finding 1 changes SendMessageOptions/SendMessageResult (additive, HTTP path unchanged).
    Confirmed and applied.
  2. Finding 2: documenting non-idempotent delivery (parity with message_agent) rather than adding an
    idempotency key and query. Confirmed; documented in PLAN D3 and the PR body.
  3. Finding 3: the end-to-end test drives a fake model through the worker. Confirmed and added as
    TestSendChatMessage_TurnBudgetThroughGenerationLoop.

Generated by Coder Agents on behalf of @jscottmiller.

@jscottmiller jscottmiller added the experimental Changes that might not necessarily be merged, until its approved to proceed with. label Sep 20, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Docs preview

Check 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
jscottmiller force-pushed the scott/chat-tree/3-messaging branch from 92b9504 to f6b2363 Compare September 20, 2026 02:55
@jscottmiller
jscottmiller force-pushed the scott/chat-tree/2-chat-tree branch 2 times, most recently from 1718073 to a33eb1c Compare September 20, 2026 04:27
Scott Miller 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.
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
jscottmiller force-pushed the scott/chat-tree/3-messaging branch from db5fcbd to 3e72a00 Compare September 20, 2026 20:09
@linear-code

linear-code Bot commented Sep 22, 2026 •

Copy link
Copy Markdown

@github-actions github-actions Bot locked and limited conversation to collaborators Oct 16, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

experimental Changes that might not necessarily be merged, until its approved to proceed with.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant