Repository navigation
feat: add chat tree root, named children, and tree API - #29615
Closed
jscottmiller wants to merge 3 commits into
Closed
jscottmiller wants to merge 3 commits into
jscottmiller wants to merge 3 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/1-chat-kind
branch
from
September 20, 2026 04:22
9dcc802 to
124e669
Compare
jscottmiller
force-pushed
the
scott/chat-tree/2-chat-tree
branch
from
September 20, 2026 04:22
31e2922 to
1718073
Compare
added 3 commits
September 20, 2026 04:27
Behind the chat-tree experiment, each owner gets one lazily created root
chat per organization. GET /organizations/{organization}/chats/tree creates
the root on first read, adopts the owner's parentless chats under it, and
returns root and chat kind rows with depth and direct child counts.
POST /chats accepts parent_chat_id (validated and locked in the creating
transaction, depth capped at 5 including the root) and defaults to the
root when omitted.
Archive cascades over the recursive subtree through parent_chat_id;
unarchive covers the chat and its subagents and is blocked under an
archived parent; tree roots reject archive, pin, and sharing.
Auto-archive treats a chat as inactive only when its whole subtree is,
and dbpurge skips archived chats with unarchived descendants now that the
parent and root foreign keys cascade on delete.
Adds chatstate.CreateIdleChat (N -> W) and TODO markers in
ARCHITECTURE.md for the human-authored updates.
Address the diff review: the archive cascade re-reads the subtree after locking members so a child committed under a descendant during the cascade is archived too; auto-archive records nested candidates once and walks each candidate's subtree through a chat_subtree function inside the LATERAL; tree roots start with the standard system messages and resolve their model config before the locked transaction; root creation through POST /chats is audited; adoption verifies the root belongs to the owner; tree position is returned to the owner only; resolver failures other than missing models surface as errors; an owner's unanchored parent gets a distinct error.
jscottmiller
force-pushed
the
scott/chat-tree/1-chat-kind
branch
from
September 20, 2026 04:27
124e669 to
5598ce1
Compare
jscottmiller
force-pushed
the
scott/chat-tree/2-chat-tree
branch
from
September 20, 2026 04:27
1718073 to
a33eb1c
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 new
chat-treeexperiment, each user gets one lazily created tree root per organization and can create named child chats under it, up to depth 5 including the root. Stacked on #29614 (scott/chat-tree/1-chat-kind).GET /organizations/{organization}/chats/treecreates the caller's root on first read (titleRoot,kind = root, standard initial system messages, statuswaiting), adopts the caller's parentless chats under it (changing onlyparent_chat_id), and returns root and chat kind rows withdepthandchild_chat_count;archived=truereturns archived rows plus the root.POST /chatsacceptsparent_chat_id(validated and locked in the creating transaction: same owner and organization, not a subagent, not archived, depth below the limit) and defaults to the root when omitted.GET /chats/{chat}reportsdepthandchild_chat_countto the owner. Roots cannot be archived, pinned, or shared.GET /chatsstill listskind = chatrows only. With the experiment off the tree route is 404,parent_chat_idis 400, no root is created, and chats stay parentless.Semantics: archiving cascades over the recursive subtree through
parent_chat_id(named children and subagents) atomically, and re-reads the subtree after locking members so a child created concurrently under a descendant is included; unarchiving covers the chat and its direct subagents only and is rejected while the parent is archived. Auto-archive candidates arekind = chatrows whose whole subtree is inactive (walked per candidate through a newchat_subtreefunction), archived as a subtree, and recorded once per tick. Migration000599switches the parent and root foreign keys toON DELETE CASCADE;DeleteOldChatsskips archived rows with an unarchived descendant, so a subtree is purged by its parent's retention age.root_chat_idkeeps its existing meaning (the spawning chat of a subagent) and is never the tree root; downstream code locates the tree root by(owner_id, organization_id, kind = 'root').Internals:
chatstate.CreateIdleChat(N -> W),Server.EnsureChatTreeRoot(per owner/org advisory lock,ReadCommittedtransaction, model config resolved before the lock),validateChatTreeParent,ChatTreeParent; dbauthz wrappers scoped to the owner's chats in the organization;codersdk.Client.ChatTree,ChatTreeResponse,ChatTreeMaxDepth,CreateChatRequest.ParentChatID. ARCHITECTURE.md carries TODO markers where behavior changed; the prose is left for the maintainers.Notes for reviewers:
POST /chats.chatHelpers.tsdescribing the removedCOALESCE(root_chat_id, parent_chat_id)precedence.Implementation plan (chat-tree-model)
Plan: chat-tree-model
Project
chat-tree-model(implement-medium). Repositorycoder/coder, baseorigin/main(a698b026fe).Branch stack:
scott/chat-tree/1-chat-kindandscott/chat-tree/2-chat-tree, two draft PRs.Revision 2: incorporates the plan panel review (
REVIEW-plan.md).Scope
First layer of the chat tree: data model, semantics, internal functions, and HTTP API. No UI, no
parent/child messaging tool. Everything user-visible is behind the new
chat-treeexperiment.Out of scope: sidebar tree (project
chat-tree-ui),send_chat_messagetool (projectchat-tree-messaging), move/reparent API, drag and drop. One exception, accepted from review:four existing frontend sites that infer "subagent" from
parent_chat_idare switched tokindso the legacy sidebar does not misrender named children when the experiment is on.
What the code does today (verified)
chats.parent_chat_idandchats.root_chat_idare set only on subagent chats(
coderd/x/chatd/subagent.go:1208-1380, both set at:1277-1278,:1351-1352). Subagentscannot spawn subagents (
subagent_catalog.go:264-272), soroot_chat_id == parent_chat_idonevery existing child.
parent_chat_id IS NULL" is the de facto discriminator for "top-level user chat" in:GetChats(chats.sql:747),GetChatWorkerAcquisitionCandidates(:2477),GetAutoArchiveInactiveChatCandidates(:2544),AutoArchiveInactiveChats(:2929),CountChatCapacityActiveByPool/CountChatCapacityQueuedByPool/GetChatQueuedForCapacity(
:2967,:2979,:3000),GetChatsUpdatedAftertelemetryhas_parent(:2393).chat_acl_only_on_root_chats,chats_pin_order_parent_check,idx_chats_auto_archive_candidates,idx_chats_worker_acquisition_candidates(
dump.sql:2212,:2216,:4804,:4822).chats_expandedcoalesces a child's ACL fromCOALESCE(root_chat_id, parent_chat_id)(
dump.sql:2327-2337); the same LEFT JOIN and explicit column list is copied into 17 queryCTEs in
chats.sql.sqlc.yaml:204maps the view todatabase.Chat.root_chat_id:GetChatFamilyIDsByRootID(chats.sql:362, used bychatstate.SetFamilyArchived,family.go:67-115), auto-archive activity and cascade(
:2924,:2946), aibridgeGetAIBridgeChatCost(aibridge.sql:797).ArchiveChatByID/UnarchiveChatByID(chats.sql:1-130) have no production callers (verify during PR 1).parent_chat_idandroot_chat_idareON DELETE SET NULL. The only deletion path isDeleteOldChats(dbpurge of archived chats byupdated_at,chats.sql:2369); there is noDELETE endpoint.
chatstate.CreateChatrequires at least one initial message and lands inrunning(
chatstate/transitions.go:98-121).CreateChatpublishes a sidebarcreatedwatch event(
chatd.go:1464).httpmw.RequireExperimentWithDevBypassskips the check in dev builds andRequireExperimentreturns 403 (
httpmw/experiments.go:36-58);exp_chats.go:4742-4745shows theapi.Experiments.Enabled+httpapi.ResourceNotFoundpattern.enterprise/audit/table.go:443-491;parent_chat_id/root_chat_idareActionIgnore.codersdk/chats.go:1944,rbac/roles.go:456,:1206).SetFamilyArchivedruns each member throughChatMachine.Updateon the dbauthz store, so cascades are authorised per row.
parent_chat_id:site/src/pages/AgentsPage/AgentsPageLayout.tsx:134,:575,:614-621;site/src/components/ChatConversation/chatHelpers.ts:94-108(cost key, resolved viaroot_chat_id ?? parent_chat_id).Design decisions
D1. Reuse
parent_chat_id; keeproot_chat_idas the subagent-family root (flag on decision 1)Decision 1 (reuse
parent_chat_id/root_chat_id) is viable forparent_chat_idbut needs asemantic migration because "has a parent" currently means "is a subagent". Giving
root_chat_idthe meaning "tree root" would additionally break every family operation listed above (archive
cascade, auto-archive activity, cost aggregation, ACL inheritance would all span the user's whole
tree), and reparenting a shared chat would violate
chat_acl_only_on_root_chatsand then have itsown ACL overridden by the root's empty ACL in
chats_expanded.Chosen variant:
parent_chat_id: immediate parent of any kind. Set on named children (parent is the root oranother named chat) and on subagents (parent is the spawning chat). Unchanged for existing rows.
root_chat_id: unchanged meaning, the nearest non-subagent ancestor of a subagent chat. NULL onthe root and on named chats. Never points at the tree root unless the tree root itself spawned
the subagent. It is not the tree root: downstream projects locate the tree root by
(owner_id, organization_id, kind = 'root')or by walkingparent_chat_id.kind chat_kind NOT NULL DEFAULT 'chat'discriminator, valuesroot,chat,subagent.kind = 'root'row for(owner_id, organization_id), so no per-row tree-root pointer is required. Depth is computedwith a bounded recursive CTE over
parent_chat_id.validateChatTreeParent), not bya composite FK. Every tree query filters by owner and organisation, so a bad pointer can only
truncate a tree, never leak a chat.
Alternatives considered: (a)
root_chat_id= tree root, with all family operations rewritten totarget "chat plus its subagents" via
parent_chat_id(more churn, every ACL CTE changes meaning);(b) a separate
tree_parent_chat_idcolumn (smallest blast radius, but contradicts decision 1 andgives the UI two parent pointers to merge). This variant is raised at the step 3 checkpoint.
D2. Every "is subagent" gate keys on
kindPR 1 replaces each
parent_chat_id IS NULL/ParentChatID.Validgate withkind. With the kindbackfilled from
parent_chat_id, PR 1 is behaviour-neutral (the FK change moved to PR 2 for thisreason). Completion criterion:
rg 'ParentChatID.Valid' coderd/ enterprise/returns onlywire-format copies (debug run context, hook
ChatRef,db2sdkpointer copy, header logging).D3. Root creation is a new idle-create transition
chatstate.CreateIdleChat: inserts the chat with the same initial system messagesCreateChatuses (deployment prompt when configured, detached workspace awareness) and no user message,
status = waiting, no ownership hint, no watch event. The state machine gainsN -> W: CreateIdle.A
Wrow is never selected byGetChatWorkerAcquisitionCandidates; the firstSendMessagefollows the normal
W -> R0path. (Revised at step 6, REVIEW-diff #6: the original "no messages"wording would have let root turns run without the deployment system prompt.) TODO items are left in
ARCHITECTURE.md(not edited beyond TODO markers).D4. Lazy tree materialisation, owner context, advisory lock
chatd.Server.EnsureChatTreeRoot(ctx, ownerID, orgID) (root database.Chat, created bool, err error):GetChatTreeRootStateByOwnerAndOrganizationreturning the root row (ifany) and the count of adoptable chats (
kind = 'chat' AND parent_chat_id IS NULL). If the rootexists and the count is 0, return.
InTx(ReadCommitted);pg_advisory_xact_lock(hashtext('chat_tree:' || owner || org));re-read; create the root with
CreateIdleChatif absent (title constantRoot, model configresolved exactly like
postChatswithout an explicit model, no workspace);AdoptParentlessChatsIntoTreeRootreparents everykind = 'chat' AND parent_chat_id IS NULLchat of that owner in that org, archived included. The UPDATE changes only
parent_chat_id:no
updated_atchange (retention and sidebar order), nosnapshot_versionbump, no pubsub orwatch event. Runner snapshots keep a stale
ParentChatIDuntil their next transition, which issafe once D2 is complete.
chats_one_tree_root_per_owner_org ON chats(owner_id, organization_id) WHERE kind = 'root'is the invariant; the advisory lock serialises creators, so a uniqueviolation is returned as an error, not retried inside the aborted transaction.
All queries run as the acting user.
InsertChatis authorised withWithOwner(owner);AdoptParentlessChatsIntoTreeRoot,GetChatTreeRootStateByOwnerAndOrganization, andGetChatTreeByOwnerAndOrganizationare authorised in dbauthz againstResourceChat.WithOwner(owner).InOrg(org)forActionUpdate/ActionRead. NoAsSystemRestrictedis needed. Reparenting a pinned or shared chat needs no data changes becausethe pin and ACL constraints are rewritten to
kind(D2).If the organisation has no usable model config,
EnsureChatTreeRootreturnsErrChatTreeRootUnavailable;GET .../chats/treethen responds 200 withroot_chat_id: nullandthe owner's parentless chats;
POST /chatsfails on model resolution as it does today, with orwithout
parent_chat_id, so no chain can be created that is not anchored at a root.Audit: the tree handler records
AuditActionCreatefor the root whencreatedis true.Adoption is not audited (no handler-level resource; documented in the PR).
D5. Cascades walk
parent_chat_idrecursively; parent archived implies subtree archivedGetChatFamilyIDsByRootIDis renamedGetChatSubtreeIDsand becomesWITH RECURSIVEoverparent_chat_id(depth bound 6: 5 tree levels plus one subagent level). For a chat without namedchildren this yields exactly the current family.
SetFamilyArchivedkeeps its all-or-nothing rule(a running descendant fails the request) and its
ErrChatNotRootguard changes fromParentChatID.ValidtoKind == subagent.ArchiveChatByID/UnarchiveChatByIDare leftuntouched if confirmed unused (comment updated), otherwise rewritten the same way.
The invariant "an archived chat has no unarchived descendant" is maintained by:
validateChatTreeParentreads the parent withGetChatByIDForUpdateinside the createtransaction (parent-first lock order, matching
SetFamilyArchived, which locks the subtree rootfirst) and rejects
archived = true(400);is archived; the existing rule for subagents extended to named children;
archived stay archived (no resurrection of independently archived chats);
kind = 'chat'candidate is inactive only when its whole recursive subtree isinactive, and the cascade archives the recursive subtree. The root is never a candidate.
Delete cascade (PR 2):
chats_parent_chat_id_fkeyandchats_root_chat_id_fkeybecomeON DELETE CASCADE(a subagent's parent and root are the same row).DeleteOldChatsadditionallyskips rows with any unarchived row in their recursive subtree and its comment is updated. This
also fixes the latent orphaning of subagents when a purged parent's children became apparent
roots. Recorded consequence: a subtree is purged by the parent's retention age.
D6. Experiment
chat-treeChecked with
api.Experiments.Enabled(codersdk.ExperimentChatTree)(no dev bypass), returninghttpapi.ResourceNotFound(404) for the tree route and 400 forparent_chat_idinPOST /chats.POST /chatsrejectsparent_chat_id(400), never touches the tree; tree route 404;no root is created; existing chats stay parentless.
POST /chatscallsEnsureChatTreeRootand defaultsparent_chat_idto the root;tree route active.
D7. Two PRs
feat(coderd): add chat kind discriminatoronscott/chat-tree/1-chat-kind.feat(coderd): add chat tree root, named children, and tree APIonscott/chat-tree/2-chat-tree(base PR 1).Invariants (contract for chat-tree-messaging and chat-tree-ui)
Kind:
kind = 'root': the per(owner_id, organization_id)tree root. Real chat, own transcript andagent, no workspace binding at creation.
parent_chat_id IS NULL,root_chat_id IS NULL.Exactly zero or one per owner per organisation (partial unique index). Created lazily, never
eagerly. Cannot be archived (PATCH archived -> 400
Chat tree root cannot be archived),auto-archive never selects it, therefore never purged. Cannot be pinned (400). Cannot be shared:
PATCH /chats/{chat}/aclon a root is rejected and its ACL stays empty (a shared root would beinvisible to the sharee, since
GET /chatsexcludes roots and the tree is owner-only). Createdwith title
Rootand the standard initial system messages; title generation never runs for it(it runs only from
POST /chats); PATCH title works. It can spawn subagents and receive messageslike any chat.
kind = 'chat': a user chat. With the experiment on,parent_chat_idis the root or anotherkind = 'chat'chat of the same owner and organisation. With the experiment off, or before theowner's tree has been materialised,
parent_chat_id IS NULL(legacy top-level).root_chat_id IS NULL. Pinnable, shareable, auto-archive candidate individually (inactivity measured over itsrecursive subtree). Title generation unchanged. May spawn subagents;
Childrenon the API istherefore no longer always empty for chats with a parent.
kind = 'subagent': spawned by arootorchatchat.parent_chat_id= spawning chat,root_chat_id= spawning chat (unchanged today). Not pinnable, no own ACL (inherits thespawning chat's ACL through
chats_expanded), excluded from the tree and fromGET /chats.Cannot have named children (400
Subagent chats cannot have child chats) and cannot spawnsubagents (unchanged). Schema:
CHECK ((kind = 'subagent') = (root_chat_id IS NOT NULL)),CHECK (kind <> 'subagent' OR parent_chat_id IS NOT NULL),CHECK (kind <> 'root' OR (parent_chat_id IS NULL AND root_chat_id IS NULL)).Tree shape:
rootandchatrows count.Maximum depth 5, so a
chatat depth 5 cannot get named children (400Chat tree depth limit exceeded,codersdk.ChatTreeMaxDepth = 5). Depth and child count arereported only for chats whose ancestor chain ends at a
rootrow (tree response and single GET),only to the owner (a reader granted access through an ACL does not receive them), and omitted for
legacy parentless chats and for subagents.
rootorchatparent owned by the same user in thesame organisation, and only while the parent is not archived. Cross-owner, cross-organisation,
unreadable, or non-existent parents all return the same 400 (no existence oracle). Shared (ACL)
access to a parent does not permit creating children under it. An owner's parent whose ancestor
chain does not end at a root returns a distinct 400 (
Parent chat is not attached to a chat tree).of the moved subtree and ancestor loops, and must lock parent before child.
applies
SetArchived(true)to the whole subtree; if any member isrunning,interrupting, orrequires_actionthe request fails and nothing changes. Unarchiving a chat whose parent isarchived fails (400). Unarchiving a chat unarchives it and its subagents only.
deletes a row whose subtree contains an unarchived chat.
kind = 'chat' AND parent_chat_id IS NULLrows, includingarchived ones, changing nothing but
parent_chat_id. It never touches subagents and neverchanges
root_chat_id. Historical subagents orphaned by an earlier purge (parent NULL) arekind = 'chat'after the backfill and are adopted like any other top-level chat (they alreadyappear in
GET /chatstoday).Capacity and worker pools:
rootandchatchats run in the top-level pool,subagentin thesubagent pool. Turn-status labels, push, summaries, plan-mode paths, and tool filtering treat
rootandchatidentically. AI Gateway attribution:HeaderCoderChatIDisroot_chat_idwhenset, else the chat's own ID;
HeaderCoderSubchatIDis set only for subagents.Subagent tools:
wait_agent,message_agent,interrupt_agentaccept onlykind = 'subagent'targets that are direct children of the calling chat (the ancestor walk stops at the first
non-subagent row);
list_agentslists onlykind = 'subagent'children. The lifecycle hookChatRefgainskindso consumers stop inferring "subagent" fromparent_chat_id.API sketch
Types (
codersdk/chats.go):codersdk.Chat.RootChatIDbecomesroot_chat_idfrom the database, else the chat's own ID(the parent fallback is dropped; for existing subagents the value is unchanged).
Childrenkeeps its current meaning: direct subagent children only (every
GetChildChatsByParentIDscall site passes
kinds = [subagent]:exp_chats.go:516,:1533,subagent.go:1068).Endpoints (registered in
coderd/chat_routes.go, both/api/experimentaland/api/v2mounts, Swagger annotated once with
@Router /api/v2/organizations/{organization}/chats/tree):GET/organizations/{organization}/chats/tree?archived=falsechat-tree(404 otherwise). CallsEnsureChatTreeRootfor the caller, returnsChatTreeResponse.archiveddefaults to false;archived=truereturns only archived rows plus the root. Owner-only; shared chats are not included.codersdk.Client.ChatTree.POST/chatsparent_chat_id. Experiment off: any value -> 400. Experiment on: omitted -> tree root (afterEnsureChatTreeRoot); given -> validated (owner, org, kind not subagent, not archived, depth).GET/chats/{chat}kind,depth,child_chat_count.Children= subagents.GET/chatskind = 'chat'only (excludes root and subagents). Named children appear flat.GET/chats/watchkind; a root creation emits nocreatedevent.PATCH/chats/{chat}archivedallowed onchat(cascade to subtree; unarchive guarded by parent), 400 onrootandsubagent.pin_order400 onrootandsubagent.PATCH/chats/{chat}/aclrootandsubagent.GET/chats/{chat}/costroot_chat_idonly).Internal functions (
coderd/x/chatd):func (p *Server) EnsureChatTreeRoot(ctx, ownerID, orgID uuid.UUID) (database.Chat, bool, error)CreateOptions.ParentChatIDvalidated inCreateChatviavalidateChatTreeParent(ctx, tx, ownerID, orgID, parentID) (depth int, err error); returnsErrChatTreeDepthExceeded,ErrChatTreeParentIsSubagent,ErrChatTreeParentArchived,ErrChatTreeParentMismatch(also used for unreadable and missing parents). The messagingproject's tool and the HTTP handler both call
CreateChatwithParentChatID.func (p *Server) ChatTreeParent(ctx, chat) (database.Chat, bool, error);GetChildChatsByParentIDsgains akindsfilter param.New / changed queries (
coderd/database/queries/chats.sql):GetChatTreeRootStateByOwnerAndOrganization,GetChatTreeByOwnerAndOrganization(recursivefrom the root, with
depthandchild_chat_count,archivedfilter, UNION of parentlesskind = 'chat'rows for the root-unavailable case),AdoptParentlessChatsIntoTreeRoot :execrows,GetChatTreeDepthByID(recursive, bounded; 0 when the chain does not end at a root),InsertChatgainskind,GetChildChatsByParentIDsgainskinds.GetChatFamilyIDsByRootID(renamedGetChatSubtreeIDs), auto-archivecandidate and cascade queries,
DeleteOldChatsguard.kindreplacesparent_chat_id IS NULLin the queries listed under "What the code does today";index expressions and query expressions use the identical form
(kind = 'subagent').Sequencing
PR 1
scott/chat-tree/1-chat-kind(behaviour-neutral):000598_chat_kind:CREATE TYPE chat_kind AS ENUM ('root','chat','subagent');ALTER TABLE chats ADD COLUMN kind chat_kind NOT NULL DEFAULT 'chat';UPDATE chats SET kind = 'subagent' WHERE parent_chat_id IS NOT NULL;UPDATE chats SET root_chat_id = parent_chat_id WHERE parent_chat_id IS NOT NULL AND root_chat_id IS NULL;UPDATE chats SET root_chat_id = NULL WHERE parent_chat_id IS NULL AND root_chat_id IS NOT NULL;DROP VIEW chats_expanded; replacechat_acl_only_on_root_chatswithkind <> 'subagent' OR (acl empty); replacechats_pin_order_parent_checkwithpin_order = 0 OR kind = 'chat'; add the three kind CHECKs; recreateidx_chats_auto_archive_candidateswithkind = 'chat'andidx_chats_worker_acquisition_candidateswith(kind = 'subagent'); recreatechats_expandedwith
c.kindin the column list andLEFT JOIN chats root ON root.id = c.root_chat_id;partial unique index
chats_one_tree_root_per_owner_org.Down:
UPDATE chats SET parent_chat_id = NULL WHERE kind = 'chat';DELETE FROM chats WHERE kind = 'root'; drop view, indexes, checks; drop column; recreate view;restore the old checks and indexes; drop type.
kindinInsertChat(explicit param); the 17 CTEs get thekindcolumn and thejoin
root.id = x.root_chat_id; kind gates in the eight queries above (acquisition rowreturns
kind); telemetryhas_parent->kind = 'subagent'.make gen; audit table:kindActionTrack,parent_chat_idActionTrack(mutable fromPR 2 on).
database.Chat.IsSubChat()->Kind == ChatKindSubagent(modelmethods.go:197);chatstate.CreateChatInput.Kind(transitions.go:29) anddbgen.ChatdefaultingKindfrom
ParentChatID.Valid(dbgen.go:101);subagent.go:1226-1229spawn setsKind = subagent;subagent_catalog.go:264-272validateSubagentSpawnParent;subagent.go:1065list_agentsguard;subagent.go:1685-1718isSubagentDescendantstops at the first non-subagent row;chatd.go:1456root fallback;chatd.go:2061-2096archive guards;chatd.go:3447-3630filterExternalMCPConfigsForTurn,toolAllowedForTurn,filterToolsForTurn,activeToolNamesForTurn,stopAfterPlanTools,stopAfterBehaviorToolstakeisSubagent bool(and
mcp_tool_search.go:35,46,63);chatd.go:4454,:4707label/summary skips;generation_preparer.go:172,:245,:418,:847;agentadmission.go:70;worker.go:211;chatstate/family.go:77;chatstate/errors.go:39doc;chatprovider.go:644-660CoderHeaders(chat id =root_chat_idelse self; subchat only for subagents);auto_archive.go:203;chathooks/trigger.go:83andcodersdk/x/agenthooks/types.go:60ChatRef.Kind;exp_chats.gopostChats(:1394, remove the:1435-1441guard),getChat:1531,getChatCost:1703-1706,patchChat:2317,:2390;exp_chats_acl.go:47,:108;dbauthz.go:7453;db2sdk.go:1895-1914(Kind,RootChatIDfallback),ChatRowsWithChildren. Completion criterion in D2.codersdk.Chat.Kind;ChatKindtype;Childrendoc comment;make genfortypesGenerated.ts. Frontend compatibility edits:AgentsPageLayout.tsx:134,:575,:614-621usekind === "subagent";chatTree.ts:40-43comment.pinned chat) for backfill, CHECKs, and the down migration; dbauthz method tests for changed
queries;
testutil.Fakechat fixtures setKind; sweep of the ~59 test sites that insertchats with
RootChatIDso they setKind(or rely on thedbgendefault);CoderHeaderstest; existing chatd/coderd tests pass.
PR 2
scott/chat-tree/2-chat-tree:ExperimentChatTree = "chat-tree"with display name andExperimentsKnown.000599_chat_tree_cascade: FKsON DELETE CASCADE; index(owner_id, organization_id) WHERE kind = 'chat' AND parent_chat_id IS NULLfor the adoptionfast path. Down restores
SET NULLand drops the index.chatstate.CreateIdleChatand TODO markers inARCHITECTURE.md: "Transitions used by the HTTPendpoints" (CreateIdle), "Execution state transition diagram" (
N --> W: CreateIdle),PATCH /chats/{chat}(root rejects archive, recursive cascade over named descendants,unarchive guard for named children, unarchive does not cascade to named descendants),
"Concurrent agent limiter" (top-level =
kind IN (root, chat)), "Auto-archive loop" (rootnever selected, subtree inactivity), tool list near line 885 (subagent tools restricted to
kind = subagentdirect children).make gen, dbauthz entries and method tests.EnsureChatTreeRoot,validateChatTreeParent(parent lockedFOR UPDATE, archivedrejected),
CreateChatparent handling, cascade guards (rootarchive/pin/ACL rejection,parent-archived unarchive guard, unarchive limited to subagents), auto-archive subtree
inactivity,
DeleteOldChatsguard,message_agent/wait_agent/interrupt_agentdirectsubagent child requirement.
api.Experiments.Enabled, audit root creation),postChatsparent handling,patchChatchanges,getChat/db2sdkdepth/child_chat_count,codersdk.Client.ChatTree,Swagger,
make gen.t.Parallel, unique owners/orgs, no sleeps):EnsureChatTreeRoot: idempotent; N goroutines racing produce one root; adopts archived,pinned, and shared parentless chats without changing
updated_at; leaves subagents and otherowners/orgs untouched; no model config ->
ErrChatTreeRootUnavailable; no watch event.CreateChatwith parent: depth 5 accepted, depth 6 rejected; subagent parent rejected;archived parent rejected; other owner / other org / missing parent return the same 400;
experiment off rejects
parent_chat_id.root archive 400; root pin 400; root ACL patch 400; unarchive child under archived parent
400; unarchive parent leaves independently archived named child archived.
subtree archived as a whole. dbpurge: archived parent with unarchived child (constructed
directly) is skipped; archived subtree purged together.
root_chat_idis the named child; capacitypool classification by kind (existing capacity tests extended);
message_agentfrom the rootto a grandchild subagent rejected.
GET /chatsexcludes root and subagents andChildrenholds subagents only;GET treereturns depth, counts, and honours
archived; experiment off -> 404 and no root row.Checks before handoff:
make gen,make fmt,make lint, targetedgo testforcoderd/database/...(migrations, dbauthz),coderd/x/chatd/...,coderdchat tests,sitetypecheck for the compatibility edits.Testing approach
Real Postgres via
dbtestutil.NewDB. chatd tests throughchattesthelpers andcoderdtestforHTTP. Race test (
make test-race) on theEnsureChatTreeRootconcurrency test.What the later projects must do
chat-tree-messaging:
send_chat_messageon top ofServer.SendMessagewithSendMessageBusyBehavior(
queue|interrupt), resolving targets viaChatTreeParentandGetChildChatsByParentIDs(kinds = [chat]). Restrict to the immediate parent and direct namedchildren unless the orchestrator decides otherwise.
kind = rootis allowed (the root isa real chat and can run turns; this plan allows it).
message_agent/wait_agent/interrupt_agentfor named children; this layerrestricts them to direct subagent children.
user_prompt_submitadmission), and spend attribution use the receiving chat'sowner, same as today.
chat-tree-ui:
GET /organizations/{organization}/chats/treeusingparent_chat_id,kind,depth,child_chat_count; treatroot_chat_id: nullas a flat list. Archivedsubtrees come from the same endpoint with
archived=true; children of very large nodes mayeventually need a paginated
parent:<uuid>search filter, which this layer does not add.parent_chat_idanywhere; usekind. Watch events carrykind.GET /chats?source=shared_with_me.Chat.Childrenof their parent (one level), not in the tree response.Rootuntil the user renames it.
must re-check.
Decisions and constraints (orchestrator, step 3)
parent_chat_idcarries the tree edge;root_chat_idkeeps its existingmeaning (nearest non-subagent ancestor of a subagent, NULL on root and named chats); the tree
root is located by
(owner_id, organization_id, kind = 'root'). Reasoning recorded in theInvariants section:
root_chat_iddrives archive, auto-archive, cost, and ACL familyoperations, which must stay scoped to "a chat plus its subagents"; the messaging and UI
projects must not treat
root_chat_idas the tree root.ON DELETE CASCADEpurging the subtree with the parent's retention age is accepted, giventhe dbpurge guard that skips rows with unarchived descendants.
kindedits inAgentsPageLayout.tsx(discriminator swaps only);the UI project owns everything else.
Root(UI may relabel),EnsureChatTreeRootfrom the tree GETand
POST /chatsonly, unarchive does not resurrect independently archived descendants.REVIEW-plan.mddispositions stand as recorded.large deployments. Assessed and rejected; lazy materialisation stays the primary path.
INSERT INTO chats (owner_id, organization_id, kind, title, status, last_model_config_id, client_type) SELECT DISTINCT ON (owner_id, organization_id) ... FROM chats WHERE kind = 'chat' AND parent_chat_id IS NULL AND NOT EXISTS (root)picking thenewest chat's
last_model_config_id, thenUPDATE chats c SET parent_chat_id = r.id FROM chats r WHERE r.kind = 'root' AND same owner/org AND c.kind = 'chat' AND c.parent_chat_id IS NULL.Indexes needed:
chats_one_tree_root_per_owner_org(already added) for the anti-join and theUPDATE ... FROMjoin; no new index.chats) with 500k parentless chats, 50k subagents,20k owners in one organisation: INSERT 0.66 s (20k roots), UPDATE 9.5 s (500k rows), 10.2 s total
in one transaction; roughly linear (1M chats about 20 s). Lock scope: row locks on every
reparented chat and the unique index for the transaction duration; in a rolling upgrade, old
replicas' chat status and heartbeat writes block for that window.
parent_chat_idis indexed, sothe UPDATE rewrites every row (no HOT updates) and roughly doubles the
chatsheap until vacuum.The only trigger on
chatsfires on retry-state columns and is not involved.(a) with the experiment off,
POST /chatsstill creates parentless chats (attaching them to theroot would move parent assignment outside the experiment), so adoption on read is still needed
when the experiment is later turned on; the eager step only front-loads one batch; (b) every
existing chat gains a visible
parent_chat_idand akind = 'root'row exists for every userwhile the experiment is off, which decision 7 excludes and which forces the remaining legacy
frontend inferences (REVIEW-diff Package v2 UI into coderd with go embed #22) to be fixed in PR 1; (c) a migration cannot seed the
deployment system prompt (site config resolved in Go), so eager roots would need a lazy
first-message seeding path that lazy
CreateIdleChatavoids; (d) the migration must guess amodel config (newest chat's, possibly disabled or deleted), whereas the lazy path resolves the
org default like
POST /chats.EnsureChatTreeRootremains the single path for root creation and adoption;the measured migration is recorded here in case a later project wants to pre-materialise trees
once the experiment is on by default.
Open questions (resolved at step 3, kept for the record)
root_chat_idkeeps the subagent-family meaning) versus the literal decision 1.ON DELETE CASCADEalso applies to subagents of purged chats and purges a subtree by theparent's retention age. Acceptable?
GET /chatsstays flat (kind = 'chat', named children included) so the legacy sidebar keepslisting every user chat; the four frontend compatibility edits are the minimum for it not to
misrender. Alternatively accept degradation and make no frontend edits.
Rootversus leaving it to the UI (titlestill stored).EnsureChatTreeRootis triggered from the tree route andPOST /chatsonly, not fromGET /chats.confirm.
Diff review dispositions
000598_chat_kind.down.sql:6DELETE FROM chats WHERE kind='root'runs while the kind CHECKs still exist and (after 599 down) FKs areSET NULL; a root that spawned a subagent makes the RI action produce a subagent with NULL pointers and the CHECK fires. Reproduced on PG.DROP CONSTRAINTblock above the deletes and delete root subtrees explicitly (root_chat_id IN roots, then roots). Add a root-with-subagent case to the down test.DeleteOldChats+000598CHECKs withSET NULLFKsLIMITbatch triggersSET NULLon the subagent and violateschats_kind_subagent_parent_check; dbpurge fails. PR 1 is not deployable alone.DeleteOldChatsinclude the subagent family indeletable(OR root_chat_id IN (SELECT id FROM deletable)), so parent and subagents delete in one statement. PR 2 then replaces it with the cascade version. Add a dbpurge test for the split-batch shape.chats.sqlGetAutoArchiveInactiveChatCandidatesWITH RECURSIVEin any form, so migration 000599 adds a plpgsql set-returning functionchat_subtree(uuid)and the LATERAL calls it per outer row. Measured on 550k chats with recent activity everywhere (steady state): 5.8 s versus 3.4 s for the pre-change query and 55 s for the top-level CTE.family.goarchive cascade vschattree.gocreatemachine.Updateloop, re-readGetChatSubtreeIDsand process new IDs until the set is stable (all members locked means no in-flight create holds a parent lock). Add an interleaving test with two transactions.auto_archive.go:93-114archivedhas duplicates (metrics, audit rows, digest).archiveOnce; skip candidates already archived in this tick and drop duplicate family members. Assert audit/digest counts inTestWorker_AutoArchiveTree.CreateIdleChat/EnsureChatTreeRootCreateIdleChatInputtake initial system messages;EnsureChatTreeRootpasses the same deployment prompt and detached-awareness messagesCreateChatuses. Status stayswaiting; acquisition ignoreswaiting, so the root is still never acquired. Record the D3 deviation in the PR.exp_chats.gopostChats root creationPOST /chatsis only logged, not audited; plan says root creation is audited.audit.BackgroundAudit[database.Chat](AuditActionCreate,New: root) whencreated; add audit-count assertions toTestChatTree_LazyRootAndAdoption(exactly one create row after the first read, none after the second).exp_chats_tree_test.godbauthz.goAdoptParentlessChatsIntoTreeRootRootChatIDis not checked to be akind='root'chat of the same owner/org; dbauthz is the only layer that can stop a mismatched root pointer.GetChatByID.000598_chat_kind.up.sqlrolling upgradekind='chat'androot_chat_idset, violating the new CHECK until restarted.dbgen.godefaultChatKindParentChatIDis classified subagent and fails the root CHECK; tests must setKindexplicitly.RootChatID.Validonly, matchingCreateChatInput.kind().chats.sqlAutoArchiveInactiveChatsDeleteOldChats :execrowschattree.go:108ResolveModelConfigIDruns inside the transaction while holding the advisory lock and a pooled connection; the resolver uses a second connection.ARCHITECTURE.mdchattree_test.gocreatedwatch event / ownership hint on root creation, interleaving test for #4.chattree.go:171FOR UPDATElock on another owner's chat before the owner check rejects. Momentary; released on rollback.exp_chats_tree.goresolverErrChatTreeRootUnavailable, so a transient failure yields 200 withroot_chat_id: null.exp_chats.gopostChatsparent_chat_idrejection happens after several DB reads.getChatpositiondepthandchild_chat_countof the owner's chat, including archived and unshared siblings.attachChatTreePositiononchat.OwnerID == apiKey.UserID; note in Invariants.chattree.godepth 0Parent chat not found, which is misleading once the owner check passed.ErrChatTreeParentUnanchored-> 400Parent chat is not attached to a chat tree.; keep mismatch for missing/unauthorized/other owner.parent_chat_id-as-subagent inferences remain (ChatTreeNode.tsx:76,ChatSummaryPanel.tsx:36,chatTree.ts:53-62) and will misfire for adopted chats with the experiment on.ChatTreeNode.tsx,ChatSummaryPanel.tsx,chatTree.ts) in PR 1.exp_chats_tree_test.go:225exp_chats_tree_test.goparent_chat_idnil UUID with experiment on (400).exp_chats.gowriteChatArchiveErrorcase writeChatInvalidState(...)is a side-effecting case expression.ifbefore the switch.chatHelpers.ts:97COALESCE(root, parent)precedence.Generated by Coder Agents on behalf of @jscottmiller.