@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 290 lines 10.7 KB
Rendered Raw
1 # Thread Lineage And Context Transfer
2
3 Forking, provider handoff, merge-back, and subagents are separate product features, but they should share one orchestration model. The common primitive is not "fork" and not "summary". It is:
4
5 ```text
6 thread relationship
7 + source point
8 + optional context transfer resolution
9 ```
10
11 The app should preserve lineage cheaply and resolve expensive provider/context work lazily when a run actually needs it.
12
13 ## Product Use Cases
14
15 ### Fork To Explore
16
17 A user forks an existing app thread to explore a tangent without polluting the source thread's context.
18
19 ```text
20 source AppThread
21 -> user forks from stable source point
22 -> new idle AppThread
23 -> no provider chosen yet
24 -> first message chooses provider/model
25 ```
26
27 If the first run on the fork uses the same provider as the source and the provider supports native fork, use the provider-native fork path. If it uses a different provider, materialize portable context at first dispatch.
28
29 ### Continue Same Thread With A Different Agent
30
31 A user continues the same app thread with another provider. This is not a new app thread, but it is still a context transfer.
32
33 ```text
34 AppThread runs 1-5 with Codex
35 user sends run 6 with Claude
36 -> resolve context transfer from Codex-backed source state to Claude
37 -> start Claude provider thread with handoff context + user message
38 ```
39
40 The app thread remains the canonical conversation. Provider-native threads are backing handles with explicit coverage.
41
42 ### Merge A Fork Back Into Its Source
43
44 A user explores deeply in a fork, then brings the result back to the source thread.
45
46 ```text
47 source thread at source point S
48 fork explores runs F1-Fn
49 user sends next message in source thread with "bring this back"
50 -> build delta from S to fork latest stable point
51 -> inject delta context with the source-thread user message
52 ```
53
54 This is not a full source-thread provider switch. It is a targeted context transfer from the fork back to the original thread.
55
56 ### Subagents
57
58 Subagents are the same family of operation with a different creator and lifecycle contract.
59
60 Native subagents:
61
62 - the provider spawns the child through its native capability;
63 - the app observes native child refs/events;
64 - the child is modeled as a child execution node and, when useful, as a related app subthread.
65
66 Cross-provider T3 subagents:
67
68 - the parent agent calls an app-owned tool;
69 - the app creates a child app thread/run with a relationship to the parent;
70 - the child result is transferred back to the parent as a subagent result context transfer.
71
72 The shared model should make user forks and agent-created subthreads feel like the same graph shape with different `createdBy` and lifecycle policy.
73
74 ## Core Concepts
75
76 ### Thread Relationship
77
78 Thread relationship describes why a target thread or run exists relative to another thread.
79
80 ```ts
81 type ThreadRelationshipKind =
82 | "fork"
83 | "provider_handoff"
84 | "merge_back"
85 | "subagent_spawn"
86 | "subagent_result";
87 ```
88
89 Relationships are product-level and provider-neutral. A fork is not the same thing as a provider-native fork. A provider-native fork is one possible resolution strategy for a fork relationship.
90
91 ### Source Point
92
93 Source point describes the exact state being transferred.
94
95 ```ts
96 type ContextSourcePoint = {
97 threadId: ThreadId;
98 runId?: RunId;
99 checkpointId?: CheckpointId;
100 turnItemId?: TurnItemId;
101 providerThreadRef?: NativeThreadRef;
102 providerTurnRef?: NativeTurnRef;
103 };
104 ```
105
106 Stable source points should prefer completed runs/checkpoints. Active runs are harder because provider chunks may still arrive and checkpoints may not be final.
107
108 ### Context Transfer
109
110 Context transfer is the durable operational record that connects source and target. It is cheap to create and may stay unresolved until first use.
111
112 ```ts
113 type ContextTransfer = {
114 id: ContextTransferId;
115 type: ThreadRelationshipKind;
116 sourceThreadId: ThreadId;
117 targetThreadId: ThreadId;
118 sourcePoint: ContextSourcePoint;
119 basePoint?: ContextSourcePoint;
120 sourceProvider?: ProviderKind;
121 targetProvider?: ProviderKind;
122 status:
123 | "pending"
124 | "resolved_native"
125 | "resolved_portable"
126 | "failed"
127 | "consumed"
128 | "superseded";
129 resolution?: ContextTransferResolution;
130 createdBy: "user" | "agent" | "system";
131 createdAt: string;
132 consumedAt?: string;
133 };
134 ```
135
136 `basePoint` is used for delta transfers, especially merge-back. For a fork merge-back, `basePoint` is the original fork source point and `sourcePoint` is the fork's latest stable point.
137
138 ### Context Handoff
139
140 Context handoff is the expensive materialized context artifact. It is created lazily only when native transfer is unavailable or insufficient.
141
142 ```ts
143 type ContextHandoff = {
144 id: ContextHandoffId;
145 transferId: ContextTransferId;
146 kind: "portable_context" | "delta_context" | "checkpoint_context";
147 payload: PortableContextPayload;
148 createdAt: string;
149 };
150 ```
151
152 Context handoffs should be auditable app artifacts, not hidden prompt concatenation.
153
154 ### Resolution Strategy
155
156 Resolution decides how the target provider/thread receives the source context.
157
158 ```ts
159 type ContextTransferResolution =
160 | {
161 strategy: "native_fork";
162 providerThreadRef: NativeThreadRef;
163 }
164 | {
165 strategy: "portable_context";
166 contextHandoffId: ContextHandoffId;
167 }
168 | {
169 strategy: "delta_context";
170 contextHandoffId: ContextHandoffId;
171 }
172 | {
173 strategy: "checkpoint_context";
174 contextHandoffId: ContextHandoffId;
175 };
176 ```
177
178 Same-provider forks should prefer `native_fork` when the source native refs are strong and the adapter supports it. Cross-provider handoff and merge-back usually require a context handoff.
179
180 ## Lazy Resolution
181
182 Fork creation should be cheap:
183
184 ```text
185 thread.fork
186 -> create target AppThread
187 -> record thread relationship / ContextTransfer(status=pending)
188 -> do not create provider session
189 -> do not create provider thread
190 -> do not build portable context
191 ```
192
193 First dispatch on a pending fork resolves the transfer:
194
195 ```text
196 first run on fork chooses provider P
197 -> find pending fork ContextTransfer
198 -> if source provider == P and native fork is supported:
199 resolve native fork
200 else:
201 materialize portable context
202 -> create/resume provider thread
203 -> send handoff/native context + user message
204 ```
205
206 This avoids forcing users to choose an agent at fork time and avoids generating summaries that may never be used.
207
208 ## Runtime Entry Point
209
210 Run startup should have one provider-neutral hook:
211
212 ```ts
213 resolveStartContext({
214 threadId,
215 provider,
216 message,
217 }): StartContextResolution
218 ```
219
220 This hook checks pending context transfers targeting the thread/run and chooses a strategy:
221
222 1. No transfer needed: target provider already has current coverage.
223 2. Native transfer: same provider and adapter supports native fork/resume.
224 3. Portable transfer: build a context handoff and inject it into the run.
225 4. Delta transfer: build the changes between `basePoint` and `sourcePoint`.
226 5. Unsupported: fail explicitly before provider work starts.
227
228 Provider adapters own native details. The orchestrator owns the relationship, source point, durable transfer record, and command receipts.
229
230 For Codex, native `thread/fork` accepts an inclusive `lastTurnId` boundary. When the app source point is a completed provider turn with a native turn reference, the Codex adapter passes that native id so the provider creates the fork at the requested point directly. If no native turn reference is available, the adapter falls back to forking the latest native state and rolling back the fork by the number of later terminal provider turns, using `thread/revert` on paginated history and reporting an explicit failure on legacy history, which Codex 0.156 cannot revert. The orchestrator still passes a provider-neutral source point and source provider-turn history; it does not encode Codex boundary or rollback policy.
231
232 Direct checkpoint rollback also requires paginated Codex history. The V2 adapter checks `historyMode` before rolling back and fails explicitly on legacy history, which Codex 0.156 cannot revert. On paginated history, it pages `thread/turns/list` to find the first removed turn, then sends `thread/revert` with `beforeTurnId`.
233
234 ## Data Ownership
235
236 `AppThread` should store lightweight browsing lineage:
237
238 ```ts
239 type AppThreadLineage = {
240 parentThreadId: ThreadId | null;
241 relationshipToParent: "fork" | "subagent" | null;
242 rootThreadId: ThreadId;
243 // A side chat: a fork shown only inside its parent. The fork planner sets it from `thread.fork`.
244 sideChat?: boolean;
245 };
246 ```
247
248 Operational transfer details should live in `ContextTransfer`, not directly on `AppThread`, because a thread can participate in many transfers:
249
250 - created by fork;
251 - later switched to another provider;
252 - later merged back to its source;
253 - later spawned subagents.
254
255 ## Checkpoint And Active-Run Policy
256
257 The first implementation should prefer stable source points:
258
259 - completed run checkpoint;
260 - explicit checkpoint;
261 - idle provider thread with known coverage.
262
263 Forking or handoff from an active run should either:
264
265 - use the latest completed checkpoint, or
266 - be rejected until active-run semantics are designed.
267
268 Do not silently fork from partially streamed provider state. That weakens correlation and makes replay/recovery difficult.
269
270 ## Current Implementation Boundary
271
272 The first backend slice implements lazy same-provider fork resolution:
273
274 - `thread.fork` creates a target app thread with fork lineage and a pending `ContextTransfer`.
275 - `thread.fork` does not create a provider session, provider thread, provider turn, or portable context artifact.
276 - The first dispatch on the fork resolves the pending transfer. For Codex-to-Codex forks with strong native refs and `thread/fork` support, the orchestrator uses the provider-native fork path and records `resolved_native` then `consumed`.
277 - Cross-provider or otherwise non-native fork transfers materialize a portable `ContextHandoff`
278 lazily on the target thread's first dispatch.
279 - Active source runs are rejected for explicit run/checkpoint forks; `latest_stable` resolves to the latest completed checkpointed run.
280
281 This keeps the runtime aligned with the architecture while making portable context explicit and
282 auditable through `ContextTransfer` and `ContextHandoff` records.
283
284 ## Relationship To Provider Switching
285
286 Provider switching is a context transfer where `sourceThreadId === targetThreadId` and the target provider differs from the current active provider.
287
288 Returning to a prior provider is also a context transfer, usually a delta from the provider's last covered run range to the current app-thread point.
289
290 The [Provider Switching And Context Handoff](./provider-switching-and-context.md) document describes strategy selection for that specific feature. This document defines the broader model shared by provider switching, forks, merge-back, and subagents.