@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 03:37 UTC

main
md 679 lines 22.6 KB
Rendered Raw
1 # Core Graph And Data Model
2
3 ## Overview
4
5 V2 models orchestration as a graph with a small number of durable entity types:
6
7 ```text
8 Project
9 AppThread
10 Run
11 ExecutionNode tree
12 ProviderThread handles
13 Context transfers and handoffs
14 Checkpoints
15 ```
16
17 The central separation is:
18
19 - `AppThread`: the user-visible conversation in T3 Code.
20 - `Run`: a counted user-visible turn on an app thread.
21 - `ExecutionNode`: a unit of provider/runtime work inside a run.
22 - `ProviderThread`: a provider-native conversation handle.
23 - `ProviderSession`: a live or resumable provider process/runtime.
24 - `ContextTransfer`: a provider-neutral relationship/source-point record used by forks, provider switches, merge-back, and subagents.
25 - `ContextHandoff`: a materialized portable context artifact used when native transfer is unavailable or insufficient.
26
27 Provider-specific lifecycle is preserved in provider refs and diagnostic raw-provider logs. App behavior is driven by app-owned ids, V2-native orchestration events, and graph relationships.
28
29 V2 events are durable because they are the app state transition log. Raw provider frames are not durable app state. They may be attached by optional correlation ids such as `rawEventId`, but the canonical durable row is the normalized V2 event.
30
31 Every committed V2 event has a store-assigned monotonically increasing `sequence`. Projection snapshots and websocket streams use that sequence as the cursor boundary:
32
33 ```text
34 read snapshot at sequence N
35 -> stream committed V2 events where sequence > N
36 ```
37
38 The sequence belongs to the stored event envelope, not the provider event and not the domain payload. Provider-native ordering is preserved separately through provider refs and diagnostic logs. Clients should treat the snapshot's `snapshotSequence` as the authoritative cursor and apply only subsequent events with a greater sequence.
39
40 ## Entity Summary
41
42 ```text
43 AppThread
44 id: ThreadId
45 projectId: ProjectId
46 title
47 providerBinding
48 activeProviderThreadId?
49 lineage?
50 status projection
51
52 Run
53 id: RunId
54 threadId: ThreadId
55 ordinal: number
56 status
57 rootNodeId
58 attempts[]
59 providerThreadId
60 contextHandoffId?
61 userMessageId
62 checkpoint?
63
64 ExecutionNode
65 id: NodeId
66 threadId: ThreadId
67 runId: RunId | null
68 parentNodeId: NodeId | null
69 rootNodeId: NodeId
70 kind
71 status
72 providerThreadId?
73 providerTurnId?
74 itemId?
75 countsForRun
76 checkpointScopeId?
77
78 CheckpointScope
79 id: CheckpointScopeId
80 threadId
81 runId?
82 nodeId
83 parentScopeId?
84 kind
85 advancesAppRunCount
86
87 ProviderSession
88 id: ProviderSessionId
89 provider
90 status
91 cwd
92 capabilities
93
94 ProviderThread
95 id: ProviderThreadId
96 providerSessionId?
97 appThreadId?
98 nativeThreadRef?
99 nativeConversationHeadRef?
100 coveredRunRange?
101 contextHandoffIds[]
102 forkSource?
103
104 ContextTransfer
105 id: ContextTransferId
106 type
107 sourceThreadId
108 targetThreadId
109 sourcePoint
110 basePoint?
111 sourceProvider?
112 targetProvider?
113 status
114 resolution?
115
116 ContextHandoff
117 id: ContextHandoffId
118 transferId
119 kind
120 payload
121 status
122
123 ProviderTurn
124 id: ProviderTurnId
125 providerThreadId
126 nativeTurnRef?
127 nodeId
128 runAttemptId?
129 status
130
131 RuntimeRequest
132 id: RuntimeRequestId
133 nodeId
134 providerRequestRef?
135 kind
136 status
137 ```
138
139 ## AppThread
140
141 An `AppThread` is the stable user-facing conversation. It owns messages, runs, checkpoints, and UI state. It does not have to map one-to-one with a provider-native thread forever.
142
143 ```ts
144 type AppThread = {
145 id: ThreadId;
146 projectId: ProjectId;
147 title: string;
148 defaultProvider: ProviderKind;
149 modelSelection: ModelSelection;
150 runtimeMode: RuntimeMode;
151 interactionMode: InteractionMode;
152 branch: string | null;
153 worktreePath: string | null;
154 activeProviderThreadId: ProviderThreadId | null;
155 lineage: AppThreadLineage | null;
156 createdAt: string;
157 updatedAt: string;
158 archivedAt: string | null;
159 deletedAt: string | null;
160 };
161 ```
162
163 `activeProviderThreadId` points to the provider-native conversation currently backing the app thread. Forking, provider migration, or recovery may create new provider threads while preserving the same app thread, depending on the operation.
164
165 `defaultProvider` is only the currently selected default for future runs. Historical runs retain their own provider and provider thread bindings.
166
167 `lineage` is intentionally lightweight browsing metadata. Operational source points, lazy native fork resolution, portable context handoffs, merge-back deltas, and subagent result transfers live in `ContextTransfer` rows because an app thread can participate in more than one transfer over time.
168
169 ```ts
170 type AppThreadLineage = {
171 parentThreadId: ThreadId | null;
172 relationshipToParent: "fork" | "subagent" | null;
173 rootThreadId: ThreadId;
174 };
175 ```
176
177 ## Run
178
179 A `Run` is the counted user-visible turn. This replaces using provider turn ids as the app-level lifecycle boundary.
180
181 ```ts
182 type Run = {
183 id: RunId;
184 threadId: ThreadId;
185 ordinal: number;
186 provider: ProviderKind;
187 providerThreadId: ProviderThreadId | null;
188 userMessageId: MessageId;
189 rootNodeId: NodeId | null;
190 activeAttemptId: RunAttemptId | null;
191 status:
192 | "queued"
193 | "starting"
194 | "running"
195 | "waiting"
196 | "completed"
197 | "interrupted"
198 | "failed"
199 | "cancelled"
200 | "rolled_back";
201 requestedAt: string;
202 startedAt: string | null;
203 completedAt: string | null;
204 checkpointId: CheckpointId | null;
205 contextHandoffId: ContextHandoffId | null;
206 sourcePlanRef?: {
207 threadId: ThreadId;
208 planId: ProposedPlanId;
209 };
210 };
211 ```
212
213 Only a run with `countsForConversation = true` contributes to the user-visible turn count and checkpoint count.
214
215 `providerThreadId` is the provider-native conversation used for this run. This makes mixed-provider app threads explicit: run 1 may be Codex, run 2 may be Claude, and run 3 may return to the original Codex provider thread.
216
217 `contextHandoffId` points to a materialized handoff artifact consumed by this run. A run may also be associated with a broader `ContextTransfer` through the transfer's target/source fields. The handoff is the payload; the transfer is the durable relationship and policy record.
218
219 ## RunAttempt
220
221 A `RunAttempt` represents one provider execution attempt for an app run. Most runs have exactly one attempt. Steering, retries, provider recovery, or provider-switch recovery may create more than one attempt.
222
223 ```ts
224 type RunAttempt = {
225 id: RunAttemptId;
226 runId: RunId;
227 attemptOrdinal: number;
228 rootNodeId: NodeId;
229 provider: ProviderKind;
230 providerThreadId: ProviderThreadId;
231 providerTurnId: ProviderTurnId | null;
232 reason: "initial" | "steering_restart" | "retry" | "provider_recovery";
233 status:
234 | "pending"
235 | "running"
236 | "completed"
237 | "interrupted"
238 | "failed"
239 | "cancelled"
240 | "superseded";
241 startedAt: string | null;
242 completedAt: string | null;
243 };
244 ```
245
246 Run attempts let app-level steering work even for providers that cannot steer an active native turn. The app can interrupt the active provider turn and create a replacement attempt under the same `RunId`.
247
248 Only one attempt is the final selected attempt for run completion and checkpointing. Superseded/interrupted attempts remain in the execution graph for audit/debugging.
249
250 ## ExecutionNode
251
252 An `ExecutionNode` is the generic unit of runtime work. It is the bridge between provider events and app behavior.
253
254 ```ts
255 type ExecutionNode = {
256 id: NodeId;
257 threadId: ThreadId;
258 runId: RunId | null;
259 parentNodeId: NodeId | null;
260 rootNodeId: NodeId;
261 kind:
262 | "root_turn"
263 | "assistant_message"
264 | "reasoning"
265 | "plan"
266 | "todo_list"
267 | "tool_call"
268 | "approval_request"
269 | "user_input_request"
270 | "subagent"
271 | "hook"
272 | "system";
273 status:
274 | "pending"
275 | "running"
276 | "waiting"
277 | "completed"
278 | "interrupted"
279 | "failed"
280 | "cancelled"
281 | "rolled_back";
282 countsForRun: boolean;
283 providerThreadId: ProviderThreadId | null;
284 providerTurnId: ProviderTurnId | null;
285 nativeItemRef: ProviderRef | null;
286 runtimeRequestId: RuntimeRequestId | null;
287 checkpointScopeId: CheckpointScopeId | null;
288 startedAt: string | null;
289 completedAt: string | null;
290 };
291 ```
292
293 The root node of a run is the only node allowed to complete the run. Subagent nodes, tool nodes, approval nodes, and plan nodes may complete independently.
294
295 ## CheckpointScope
296
297 A `CheckpointScope` describes a unit of filesystem state that can be checkpointed. Root runs and child execution nodes can both have checkpoint scopes.
298
299 ```ts
300 type CheckpointScope = {
301 id: CheckpointScopeId;
302 threadId: ThreadId;
303 runId: RunId | null;
304 nodeId: NodeId;
305 parentScopeId: CheckpointScopeId | null;
306 providerThreadId: ProviderThreadId | null;
307 kind: "root_run" | "subagent" | "tool" | "provider_thread" | "manual";
308 ordinalWithinParent: number;
309 advancesAppRunCount: boolean;
310 cwd: string;
311 createdAt: string;
312 };
313 ```
314
315 Root run scopes have `advancesAppRunCount = true`. Child scopes, such as subagents, have `advancesAppRunCount = false` and are nested under the parent run's scope.
316
317 ## ProviderSession
318
319 A `ProviderSession` is a live provider runtime process/session, such as a Codex app-server process or a Claude SDK session.
320
321 ```ts
322 type ProviderSession = {
323 id: ProviderSessionId;
324 provider: ProviderKind;
325 status: "starting" | "ready" | "running" | "waiting" | "stopped" | "error";
326 cwd: string;
327 model: string | null;
328 capabilities: ProviderCapabilities;
329 createdAt: string;
330 updatedAt: string;
331 lastError: string | null;
332 };
333 ```
334
335 A provider session may host one or more provider threads if the provider supports it. If a provider only supports one active conversation per process, V2 still models that as one provider thread attached to the session.
336
337 The session entity is durable metadata for a live-or-recoverable runtime, not the runtime handle itself. The in-memory process/client handle may disappear because the server restarted, an idle reaper released it, or the provider process crashed. In all cases, the app keeps the `ProviderSession`, `ProviderThread`, and native resume refs in durable state, then recreates the live runtime through the normal provider session manager path.
338
339 Provider runtime ids and ordinals must not depend on adapter process memory. If a value is persisted or must survive recovery, it is allocated by the orchestrator/correlation/id services or derived from durable provider refs.
340
341 ## ProviderThread
342
343 A `ProviderThread` is a provider-native conversation handle. It is addressable even when it is nested under a subagent execution node.
344
345 ```ts
346 type ProviderThread = {
347 id: ProviderThreadId;
348 provider: ProviderKind;
349 providerSessionId: ProviderSessionId | null;
350 appThreadId: ThreadId | null;
351 ownerNodeId: NodeId | null;
352 nativeThreadRef: string | null;
353 nativeConversationHeadRef: ProviderRef | null;
354 status: "not_loaded" | "idle" | "active" | "archived" | "closed" | "error";
355 firstRunOrdinal: number | null;
356 lastRunOrdinal: number | null;
357 handoffIds: ContextHandoffId[];
358 forkedFrom: ProviderThreadForkSource | null;
359 createdAt: string;
360 updatedAt: string;
361 };
362 ```
363
364 `appThreadId` is set when the provider thread backs a first-class app thread. `ownerNodeId` is set when the provider thread is nested under an execution node, such as a subagent. A provider thread can later be forked or promoted into a first-class app thread.
365
366 A provider thread may have gaps in its native run coverage. Example: runs 1-5 use Codex provider thread A, runs 6-8 use Claude provider thread B, and run 9 returns to Codex thread A with a handoff summary covering runs 6-8. In that case, Codex thread A remains the same provider thread, but it has an explicit `ContextHandoff` before run 9.
367
368 ## ContextTransfer
369
370 A `ContextTransfer` records a source/target relationship and how context should move between them. It is the shared primitive for user forks, provider switching, merge-back, and subagents.
371
372 ```ts
373 type ContextTransfer = {
374 id: ContextTransferId;
375 type: "fork" | "provider_handoff" | "merge_back" | "subagent_spawn" | "subagent_result";
376 sourceThreadId: ThreadId;
377 targetThreadId: ThreadId;
378 sourcePoint: ContextSourcePoint;
379 basePoint: ContextSourcePoint | null;
380 sourceProvider: ProviderKind | null;
381 targetProvider: ProviderKind | null;
382 status:
383 | "pending"
384 | "resolved_native"
385 | "resolved_portable"
386 | "failed"
387 | "consumed"
388 | "superseded";
389 resolution: ContextTransferResolution | null;
390 createdBy: "user" | "agent" | "system";
391 createdAt: string;
392 consumedAt: string | null;
393 };
394 ```
395
396 ```ts
397 type ContextSourcePoint = {
398 threadId: ThreadId;
399 runId: RunId | null;
400 checkpointId: CheckpointId | null;
401 turnItemId: TurnItemId | null;
402 providerThreadRef: NativeThreadRef | null;
403 providerTurnRef: NativeTurnRef | null;
404 };
405
406 type ContextTransferResolution =
407 | { strategy: "native_fork"; providerThreadRef: NativeThreadRef }
408 | { strategy: "portable_context"; contextHandoffId: ContextHandoffId }
409 | { strategy: "delta_context"; contextHandoffId: ContextHandoffId }
410 | { strategy: "checkpoint_context"; contextHandoffId: ContextHandoffId };
411 ```
412
413 Creating a transfer should be cheap. Expensive context handoffs are materialized lazily when the target run starts and the selected provider is known.
414
415 ## ContextHandoff
416
417 A `ContextHandoff` is a first-class artifact created when portable provider context must be bridged. It is most common when changing providers between runs, but it also applies when provider resume fails and a replacement provider thread must be seeded from app history.
418
419 In the broader transfer model, `ContextTransfer` records source, target, and lifecycle. `ContextHandoff` is the materialized payload consumed by a run when native transfer cannot satisfy the relationship.
420
421 ```ts
422 type ContextHandoff = {
423 id: ContextHandoffId;
424 transferId: ContextTransferId;
425 threadId: ThreadId;
426 targetRunId: RunId;
427 fromProviderThreadIds: ProviderThreadId[];
428 toProviderThreadId: ProviderThreadId;
429 coveredRunOrdinals: {
430 from: number;
431 to: number;
432 };
433 strategy:
434 | "delta_since_target_last_seen"
435 | "full_thread_summary"
436 | "checkpoint_summary"
437 | "manual_context";
438 status: "pending" | "ready" | "failed" | "superseded";
439 summaryMessageId: MessageId | null;
440 summaryText: string;
441 createdByProvider: ProviderKind | null;
442 createdAt: string;
443 updatedAt: string;
444 };
445 ```
446
447 The handoff is not just prompt text. It is part of the graph and can be inspected, regenerated, superseded, or audited.
448
449 The preferred return-to-provider strategy is `delta_since_target_last_seen`: resume the previous provider thread and summarize only the runs that happened while that provider was inactive. Use `full_thread_summary` when resume fails, provider settings are incompatible, or the accumulated handoffs would create poor context quality.
450
451 ## ProviderTurn
452
453 A `ProviderTurn` is the normalized handle for a provider-native turn.
454
455 ```ts
456 type ProviderTurn = {
457 id: ProviderTurnId;
458 providerThreadId: ProviderThreadId;
459 nodeId: NodeId;
460 runAttemptId: RunAttemptId | null;
461 nativeTurnRef: string | null;
462 ordinal: number;
463 status: "pending" | "running" | "completed" | "interrupted" | "failed" | "cancelled";
464 startedAt: string | null;
465 completedAt: string | null;
466 };
467 ```
468
469 Codex has strong native turn ids. Weaker providers may only have ordinals. Both map into `ProviderTurnId`.
470
471 ## RuntimeRequest
472
473 Requests represent provider-originated callbacks that require app/user response.
474
475 ```ts
476 type RuntimeRequest = {
477 id: RuntimeRequestId;
478 nodeId: NodeId;
479 providerTurnId: ProviderTurnId | null;
480 nativeRequestRef: string | null;
481 kind:
482 | "command"
483 | "file-read"
484 | "file-change"
485 | "dynamic_tool_call"
486 | "user_input"
487 | "auth_refresh";
488 status: "pending" | "resolved" | "expired" | "cancelled";
489 responseCapability:
490 | { type: "live"; providerSessionId: ProviderSessionId }
491 | { type: "not_resumable"; reason: string };
492 createdAt: string;
493 resolvedAt: string | null;
494 };
495 ```
496
497 The permission kinds are the same canonical domain values used by V1 `ProviderRequestKind`.
498 Adapters map provider-native callback names such as Codex `item/commandExecution/requestApproval`
499 and Claude tool permission names into these app-level values.
500
501 Requests may remain visible after restart, but they are only respondable if their `responseCapability` is live.
502
503 ## Messages
504
505 Messages are part of the conversation projection, not the raw provider graph. They link back to runs and nodes when possible.
506
507 ```ts
508 type ConversationMessage = {
509 id: MessageId;
510 threadId: ThreadId;
511 runId: RunId | null;
512 nodeId: NodeId | null;
513 role: "user" | "assistant" | "system";
514 text: string;
515 attachments: Attachment[];
516 streaming: boolean;
517 createdAt: string;
518 updatedAt: string;
519 };
520 ```
521
522 Provider message chunks are collected through items/content events and projected into messages. The projection may hide child/subagent messages by default while preserving them in the graph.
523
524 ## Plans, Questions, And Todo Lists
525
526 V2 treats these as structured turn items or execution nodes.
527
528 ```ts
529 type PlanArtifact = {
530 id: PlanId;
531 threadId: ThreadId;
532 runId: RunId | null;
533 nodeId: NodeId;
534 kind: "proposed_plan" | "todo_list" | "questions";
535 status: "draft" | "active" | "completed" | "superseded";
536 markdown?: string;
537 steps?: Array<{ id: string; text: string; status: "pending" | "running" | "completed" }>;
538 questions?: UserInputQuestion[];
539 };
540 ```
541
542 Codex `turn/plan/updated` maps to a `todo_list` artifact. Plan-mode final plan items map to `proposed_plan`. User-input question requests map to `questions` plus a `RuntimeRequest`.
543
544 ## Checkpoint
545
546 Checkpoints attach to checkpoint scopes. A root run checkpoint is the user-visible conversation checkpoint. A child checkpoint records nested filesystem state for a subagent, tool, or provider thread without advancing the parent run count.
547
548 ```ts
549 type Checkpoint = {
550 id: CheckpointId;
551 threadId: ThreadId;
552 scopeId: CheckpointScopeId;
553 runId: RunId | null;
554 nodeId: NodeId;
555 parentCheckpointId: CheckpointId | null;
556 ordinalWithinScope: number;
557 appRunOrdinal: number | null;
558 ref: string;
559 status: "ready" | "missing" | "error" | "stale";
560 files: CheckpointFileSummary[];
561 capturedAt: string;
562 };
563 ```
564
565 A child/subagent provider turn can create a child checkpoint. It does not create an app-run checkpoint unless it is running as a first-class app run in a forked/promoted thread.
566
567 ## Raw Provider Diagnostics
568
569 Raw provider diagnostics are append-only evidence for debugging, support, and replay fixture generation. They should be written to bounded rotating log files, not treated as canonical durable SQLite state.
570
571 ```ts
572 type RawProviderEvent = {
573 id: RawEventId;
574 provider: ProviderKind;
575 providerSessionId: ProviderSessionId;
576 sequence: number;
577 direction: "incoming" | "outgoing";
578 messageKind: "request" | "response" | "notification" | "error";
579 method: string | null;
580 jsonRpcId: string | number | null;
581 payload: unknown;
582 observedAt: string;
583 };
584 ```
585
586 No domain behavior should depend on parsing historic UI events if raw provider diagnostics are available. Production behavior should depend on normalized orchestration events/entities and provider refs. Raw provider frames are evidence and replay input, not the source of truth for normal app state.
587
588 Normalized V2 entities should preserve enough correlation metadata to explain and route behavior:
589
590 - provider kind.
591 - provider session/thread/turn refs.
592 - provider item/request refs when available.
593 - native id strength.
594 - diagnostic log location or raw frame reference when useful.
595
596 The replay framework can use raw provider transcripts as input without requiring production SQLite to store every raw frame.
597
598 ## Projections
599
600 V2 should expose separate projections:
601
602 - Thread shell: fast sidebar list.
603 - Thread detail: messages, runs, activities, checkpoints, plans.
604 - Execution graph: debug/developer view of nodes and provider refs.
605 - Provider sessions: live runtime/process state.
606 - Pending requests: actionable approvals/user input.
607
608 The UI can remain simple while the graph remains precise.
609
610 Projection streaming should use the existing app snapshot-plus-cursor contract. A thread-detail subscription should return a projection snapshot at sequence `N`, then stream only events after `N`. The frontend should not receive events already reflected in the snapshot. Reconnects may reset from a fresh snapshot instead of replaying local client state; the fresh snapshot and its `snapshotSequence` become the new cursor boundary.
611
612 ## Turn Item Projection
613
614 The frontend should not reconstruct display order by merging `messages`, `plans`, checkpoints, approvals, and activities itself. V2 exposes an ordered `turnItems` projection for thread detail rendering.
615
616 `turnItems` are projection records, not the canonical source of truth. The canonical graph remains normalized in runs, attempts, nodes, requests, messages, plans, and checkpoints. Provider-native item refs live directly on nodes and turn items where correlation is needed.
617
618 Forked threads also expose a derived `visibleTurnItems` projection. `turnItems` remains the canonical
619 items emitted on that app thread. `visibleTurnItems` is the user-visible ordered read model: it may
620 reference inherited source items through the fork source point, include synthetic lifecycle markers
621 such as "forked from conversation", and then continue with local target-thread items. This keeps
622 storage normalized while giving thread detail views and tests one backend-owned surface to assert.
623
624 Known common tools should have structured item variants so the frontend can render stable custom components without parsing provider text:
625
626 ```ts
627 type TurnItem =
628 | UserMessage
629 | AssistantMessage
630 | Reasoning
631 | Plan
632 | FileChange
633 | CommandExecution
634 | FileSearch
635 | WebSearch
636 | ApprovalRequest
637 | Checkpoint
638 | Compaction
639 | Handoff
640 | Fork
641 | DynamicTool;
642 ```
643
644 Examples:
645
646 ```ts
647 type FileChange = {
648 type: "file_change";
649 fileName: string;
650 additions?: number;
651 deletions?: number;
652 diffStr?: string;
653 oldStr?: string;
654 newStr?: string;
655 };
656
657 type CommandExecution = {
658 type: "command_execution";
659 input: string;
660 status: TurnItemStatus;
661 output?: string;
662 exitCode?: number;
663 };
664
665 type DynamicTool = {
666 type: "dynamic_tool";
667 toolName: string | null;
668 input: unknown;
669 output?: unknown;
670 };
671 ```
672
673 Compaction, handoff, and fork are orchestration lifecycle items, not dynamic tools:
674
675 - `compaction`: one item can transition from `running` with title like "Compacting context..." to `completed` with title like "Compacted context".
676 - `handoff`: records the context bridge from one or more source provider threads/providers to a target provider thread/provider.
677 - `fork`: records that the user or system created a new app thread from a run, node, or provider thread.
678
679 The UI can render known variants with deterministic components and render `dynamic_tool` as expandable JSON input/output. Each turn item keeps refs back to `runId`, `nodeId`, `providerTurnId`, and `nativeItemRef` so debug views can jump from the display stream back into the graph and provider logs.