Skip to content

feat: model sessions as containers of linear threads - #112

Merged
sanchitrk merged 8 commits into
canaryfrom
feat/thread-data-model
Oct 29, 2026
Merged

sanchitrk merged 8 commits into
canaryfrom
feat/thread-data-model

Conversation

@sanchitrk

Copy link
Copy Markdown
Contributor

A session becomes a container of linear threads: one physical boundary, one event log, one seq space. Every session has exactly one main thread. The only way to branch is to fork a thread.

Storage

  • All old migrations are replaced by one migration, 202610290001_threads, which creates sequence, event, sandbox, project, space, session, thread, entry, part, inbox, document and revision. Existing databases are discarded, not upgraded.
  • CHECKs cover structural rules only. Vocabularies (types, statuses, kinds, delivery, policies) are validated in the row schemas.
  • The event log starts at seq 1, and session.created is the first event of every session.

Harness

  • Session (session/session.ts) is the container. It handles create (with the main thread and its agent document, in one event), link, relink and delete. relink with a threadId sets only that thread's agent.placement.
  • Thread (thread/thread.ts) handles entries and parts, committed_seq, context through the fork line, and fork:
    • The fork point must be a committed entry.
    • The origin re-points to the thread that owns the entry.
    • The cut is the entry's committed_seq.
    • Documents are copied according to their fork policy.
    • before() refills the editor text.
    • It also holds execution state, restarts and titles.
  • Document (document/document.ts) stores full-value revisions. The built-in agent kind (model, thinkingLevel, modelTools, placement) replaces session config. thread.configured writes one revision.
  • Inbox (inbox/, previously session input): items are addressed to a thread and stored as kind + data.
  • Runtime:
    • The Coordinator is keyed by thread, so threads of one session run concurrently.
    • The drain mounts the thread's placement, or the session's space when it has none.
    • agent is read once per request.
    • Recovery resumes running root threads and fails their open drafts as interrupted.
    • interrupt works on one thread or on a whole session.
  • The thread id is passed as aikit's sessionId and as gen_ai.conversation.id.
  • Context assembly drops aborted entries and starts at the newest reset or compaction. The configChange and branchSummary entry types are gone; system and reset are added.

APIs

  • session.* keeps create (returns the main thread's info), link, relink (now takes an optional threadId), delete, interrupt (all threads) and log.
  • Everything else moves to thread.*: list, info, history, queue, configure, fork, prompt, cancel, update, interrupt, message and wait. Payloads are { sessionId, threadId? }; a missing threadId means the main thread.
  • CLI: run --session <id> --thread <id|main>. ACP maps an editor session to the main thread.
  • Plugin SDK: ThreadID is exported from ids, and SharedPluginContext and ToolBefore/ToolAfter gain threadId.
  • Apps (web, widget, the desktop server) show each session as its main thread.

Tests

  • harness/test/thread.test.ts is an end-to-end test that writes artifacts. It covers:
    • the design walkthrough: the fork cut at committed_seq, with agent copied as of the cut
    • forks refused at a draft and at an aborted entry
    • forking an inherited entry re-points the origin
    • before(), and its rejection on main's first entry
    • two threads running concurrently
    • reset in context assembly
    • thread recovery
    • constraint refusals: a second main, two entries per thread per event, two revisions per document per event
  • server.test.ts covers thread.fork, before and session.delete over WebSocket.
  • Existing tests are moved to threads; the copy-on-fork tests are deleted.
  • vp check and vp run typecheck pass.
  • Harness: 550 tests pass.
  • Codework: everything passes except one tui test, which fails because another worktree's server is holding port 7610.
  • The catalog tests need the gitignored models.gen.json.

Not in this PR

  • Subagents beyond the schema: no spawn API, subagent tool, interrupt cascade or subagent recovery.
  • tool_search / tool_unavailable.
  • Inbox items for link/relink.
  • A real thread UI.
  • The TUI's RPC calls are unchanged.

🤖 Generated with Claude Code

sanchitrk and others added 8 commits October 29, 2026 19:48
Replace every migration with one schema: a session holds threads with one
event log, entries carry committed_seq, the inbox addresses a thread, and
documents with full-value revisions hold per-thread state. The built-in
agent document replaces session config; usage, execution and titles move to
the thread. Fork is the only way to branch: it cuts at a committed entry,
re-points the origin to the entry's owner and copies documents by policy.
Runs are keyed by thread, and the server splits into session.* and thread.*.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Walkthrough fork cut and agent copy, fork refusals, inherited origins,
before(), concurrent threads, reset in context assembly, thread recovery
and the structural constraints, each with an artifact.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The widget's RPC mirror follows the thread.* split; the desktop server lists
main threads and the session widget reads and prompts the main thread.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Tests address threads, read sessions through their main thread, and expect
the log to open with session.created. Copy-on-fork tests are gone; server
tests cover fork, before() and session delete.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Address review findings: a delete stops threads a prompt woke after its first
interrupt, and a drain of a deleted thread runs nothing. thread.message counts
inherited prompts, a commit moves the thread's last activity, run --thread
rejects a malformed id, and a stale append seq is covered by a test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… catalog

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sanchitrk
sanchitrk merged commit 64a3527 into canary Oct 29, 2026
2 checks passed
@sanchitrk
sanchitrk deleted the feat/thread-data-model branch October 29, 2026 17:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant