Skip to content

Commit eeca40d

Browse files
juliusmarmingejuliusmarminge
committed
Merge branch 'main' into fuzzy-workspace-entry-search
2 parents ee784bf + db17ff3 commit eeca40d

File tree

243 files changed

+18764
-6744
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

243 files changed

+18764
-6744
lines changed

‎.agents/skills/btca-cli/SKILL.md‎

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎.agents/skills/btca-cli/agents/openai.yaml‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎.docs/architecture.md‎

Lines changed: 125 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,139 @@ T3 Code runs as a **Node.js WebSocket server** that wraps `codex app-server` (JS
55
```
66
┌─────────────────────────────────┐
77
│ Browser (React + Vite) │
8-
│ Connected via WebSocket │
8+
│ wsTransport (state machine) │
9+
│ Typed push decode at boundary │
910
└──────────┬──────────────────────┘
1011
│ ws://localhost:3773
1112
┌──────────▼──────────────────────┐
1213
│ apps/server (Node.js) │
1314
│ WebSocket + HTTP static server │
14-
│ ProviderManager │
15-
│ CodexAppServerManager │
15+
│ ServerPushBus (ordered pushes) │
16+
│ ServerReadiness (startup gate) │
17+
│ OrchestrationEngine │
18+
│ ProviderService │
19+
│ CheckpointReactor │
20+
│ RuntimeReceiptBus │
1621
└──────────┬──────────────────────┘
1722
│ JSON-RPC over stdio
1823
┌──────────▼──────────────────────┐
1924
│ codex app-server │
2025
└─────────────────────────────────┘
2126
```
27+
28+
## Components
29+
30+
- **Browser app**: The React app renders session state, owns the client-side WebSocket transport, and treats typed push events as the boundary between server runtime details and UI state.
31+
32+
- **Server**: `apps/server` is the main coordinator. It serves the web app, accepts WebSocket requests, waits for startup readiness before welcoming clients, and sends all outbound pushes through a single ordered push path.
33+
34+
- **Provider runtime**: `codex app-server` does the actual provider/session work. The server talks to it over JSON-RPC on stdio and translates those runtime events into the app's orchestration model.
35+
36+
- **Background workers**: Long-running async flows such as runtime ingestion, command reaction, and checkpoint processing run as queue-backed workers. This keeps work ordered, reduces timing races, and gives tests a deterministic way to wait for the system to go idle.
37+
38+
- **Runtime signals**: The server emits lightweight typed receipts when important async milestones finish, such as checkpoint capture, diff finalization, or a turn becoming fully quiescent. Tests and orchestration code wait on these signals instead of polling internal state.
39+
40+
## Event Lifecycle
41+
42+
### Startup and client connect
43+
44+
```mermaid
45+
sequenceDiagram
46+
participant Browser
47+
participant Transport as WsTransport
48+
participant Server as wsServer
49+
participant Layers as serverLayers
50+
participant Ready as ServerReadiness
51+
participant Push as ServerPushBus
52+
53+
Browser->>Transport: Load app and open WebSocket
54+
Transport->>Server: Connect
55+
Server->>Layers: Start runtime services
56+
Server->>Ready: Wait for startup barriers
57+
Ready-->>Server: Ready
58+
Server->>Push: Publish server.welcome
59+
Push-->>Transport: Ordered welcome push
60+
Transport-->>Browser: Hydrate initial state
61+
```
62+
63+
1. The browser boots [`WsTransport`][1] and registers typed listeners in [`wsNativeApi`][2].
64+
2. The server accepts the connection in [`wsServer`][3] and brings up the runtime graph defined in [`serverLayers`][7].
65+
3. [`ServerReadiness`][4] waits until the key startup barriers are complete.
66+
4. Once the server is ready, [`wsServer`][3] sends `server.welcome` from the contracts in [`ws.ts`][6] through [`ServerPushBus`][5].
67+
5. The browser receives that ordered push through [`WsTransport`][1], and [`wsNativeApi`][2] uses it to seed local client state.
68+
69+
### User turn flow
70+
71+
```mermaid
72+
sequenceDiagram
73+
participant Browser
74+
participant Transport as WsTransport
75+
participant Server as wsServer
76+
participant Provider as ProviderService
77+
participant Codex as codex app-server
78+
participant Ingest as ProviderRuntimeIngestion
79+
participant Engine as OrchestrationEngine
80+
participant Push as ServerPushBus
81+
82+
Browser->>Transport: Send user action
83+
Transport->>Server: Typed WebSocket request
84+
Server->>Provider: Route request
85+
Provider->>Codex: JSON-RPC over stdio
86+
Codex-->>Ingest: Provider runtime events
87+
Ingest->>Engine: Normalize into orchestration events
88+
Engine-->>Server: Domain events
89+
Server->>Push: Publish orchestration.domainEvent
90+
Push-->>Browser: Typed push
91+
```
92+
93+
1. A user action in the browser becomes a typed request through [`WsTransport`][1] and the browser API layer in [`nativeApi`][12].
94+
2. [`wsServer`][3] decodes that request using the shared WebSocket contracts in [`ws.ts`][6] and routes it to the right service.
95+
3. [`ProviderService`][8] starts or resumes a session and talks to `codex app-server` over JSON-RPC on stdio.
96+
4. Provider-native events are pulled back into the server by [`ProviderRuntimeIngestion`][9], which converts them into orchestration events.
97+
5. [`OrchestrationEngine`][10] persists those events, updates the read model, and exposes them as domain events.
98+
6. [`wsServer`][3] pushes those updates to the browser through [`ServerPushBus`][5] on channels defined in [`orchestration.ts`][11].
99+
100+
### Async completion flow
101+
102+
```mermaid
103+
sequenceDiagram
104+
participant Server as wsServer
105+
participant Worker as Queue-backed workers
106+
participant Cmd as ProviderCommandReactor
107+
participant Checkpoint as CheckpointReactor
108+
participant Receipt as RuntimeReceiptBus
109+
participant Push as ServerPushBus
110+
participant Browser
111+
112+
Server->>Worker: Enqueue follow-up work
113+
Worker->>Cmd: Process provider commands
114+
Worker->>Checkpoint: Process checkpoint tasks
115+
Checkpoint->>Receipt: Publish completion receipt
116+
Cmd-->>Server: Produce orchestration changes
117+
Checkpoint-->>Server: Produce orchestration changes
118+
Server->>Push: Publish resulting state updates
119+
Push-->>Browser: User-visible push
120+
```
121+
122+
1. Some work continues after the initial request returns, especially in [`ProviderRuntimeIngestion`][9], [`ProviderCommandReactor`][13], and [`CheckpointReactor`][14].
123+
2. These flows run as queue-backed workers using [`DrainableWorker`][16], which helps keep side effects ordered and test synchronization deterministic.
124+
3. When a milestone completes, the server emits a typed receipt on [`RuntimeReceiptBus`][15], such as checkpoint completion or turn quiescence.
125+
4. Tests and orchestration code wait on those receipts instead of polling git state, projections, or timers.
126+
5. Any user-visible state changes produced by that async work still go back through [`wsServer`][3] and [`ServerPushBus`][5].
127+
128+
[1]: ../apps/web/src/wsTransport.ts
129+
[2]: ../apps/web/src/wsNativeApi.ts
130+
[3]: ../apps/server/src/wsServer.ts
131+
[4]: ../apps/server/src/wsServer/readiness.ts
132+
[5]: ../apps/server/src/wsServer/pushBus.ts
133+
[6]: ../packages/contracts/src/ws.ts
134+
[7]: ../apps/server/src/serverLayers.ts
135+
[8]: ../apps/server/src/provider/Layers/ProviderService.ts
136+
[9]: ../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
137+
[10]: ../apps/server/src/orchestration/Layers/OrchestrationEngine.ts
138+
[11]: ../packages/contracts/src/orchestration.ts
139+
[12]: ../apps/web/src/nativeApi.ts
140+
[13]: ../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
141+
[14]: ../apps/server/src/orchestration/Layers/CheckpointReactor.ts
142+
[15]: ../apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts
143+
[16]: ../packages/shared/src/DrainableWorker.ts

‎.docs/encyclopedia.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Encyclopedia
2+
3+
This is a living glossary for T3 Code. It explains what common terms mean in this codebase.
4+
5+
## Table of contents
6+
7+
- [Project and workspace](#project-and-workspace)
8+
- [Thread timeline](#thread-timeline)
9+
- [Orchestration](#orchestration)
10+
- [Provider runtime](#provider-runtime)
11+
- [Checkpointing](#checkpointing)
12+
13+
## Concepts
14+
15+
### Project and workspace
16+
17+
#### Project
18+
19+
The top-level workspace record in the app. In [the orchestration contracts][1], a project has a `workspaceRoot`, a title, and one or more threads. See [workspace-layout.md][2].
20+
21+
#### Workspace root
22+
23+
The root filesystem path for a project. In [the orchestration model][1], it is the base directory for branches and optional worktrees. See [workspace-layout.md][2].
24+
25+
#### Worktree
26+
27+
A Git worktree used as an isolated workspace for a thread. If a thread has a `worktreePath` in [the contracts][1], it runs there instead of in the main working tree. Git operations live in [GitCore.ts][3].
28+
29+
### Thread timeline
30+
31+
#### Thread
32+
33+
The main durable unit of conversation and workspace history. In [the orchestration contracts][1], a thread holds messages, activities, checkpoints, and session-related state. See [projector.ts][4].
34+
35+
#### Turn
36+
37+
A single user-to-assistant work cycle inside a thread. It starts with user input and ends when follow-up work like checkpointing settles. See [the contracts][1], [ProviderRuntimeIngestion.ts][5], and [CheckpointReactor.ts][6].
38+
39+
#### Activity
40+
41+
A user-visible log item attached to a thread. In [the contracts][1], activities cover important non-message events like approvals, tool actions, and failures. They are projected into thread state in [projector.ts][4].
42+
43+
### Orchestration
44+
45+
Orchestration is the server-side domain layer that turns runtime activity into stable app state. The main entry point is [OrchestrationEngine.ts][7], with core logic in [decider.ts][8] and [projector.ts][4].
46+
47+
#### Aggregate
48+
49+
The domain object a command or event belongs to. In [the contracts][1], that is usually `project` or `thread`. See [decider.ts][8].
50+
51+
#### Command
52+
53+
A typed request to change domain state. In [the contracts][1], commands are validated in [commandInvariants.ts][9] and turned into events by [decider.ts][8].
54+
Examples include `thread.create`, `thread.turn.start`, and `thread.checkpoint.revert`.
55+
56+
#### Domain Event
57+
58+
A persisted fact that something already happened. In [the contracts][1], events are the source of truth, and [projector.ts][4] shows how they are applied.
59+
Examples include `thread.created`, `thread.message-sent`, and `thread.turn-diff-completed`.
60+
61+
#### Decider
62+
63+
The pure orchestration logic that turns commands plus current state into events. The core implementation is in [decider.ts][8], with preconditions in [commandInvariants.ts][9].
64+
65+
#### Projection
66+
67+
A read-optimized view derived from events. See [projector.ts][4], [ProjectionPipeline.ts][11], and [ProjectionSnapshotQuery.ts][10].
68+
69+
#### Projector
70+
71+
The logic that applies domain events to the read model or projection tables. See [projector.ts][4] and [ProjectionPipeline.ts][11].
72+
73+
#### Read model
74+
75+
The current materialized view of orchestration state. In [the contracts][1], it holds projects, threads, messages, activities, checkpoints, and session state. See [ProjectionSnapshotQuery.ts][10] and [OrchestrationEngine.ts][7].
76+
77+
#### Reactor
78+
79+
A side-effecting service that handles follow-up work after events or runtime signals. Examples include [CheckpointReactor.ts][6], [ProviderCommandReactor.ts][12], and [ProviderRuntimeIngestion.ts][5].
80+
81+
#### Receipt
82+
83+
A lightweight typed runtime signal emitted when an async milestone completes. See [RuntimeReceiptBus.ts][13].
84+
Examples include `checkpoint.baseline.captured`, `checkpoint.diff.finalized`, and `turn.processing.quiesced`, which are emitted by flows such as [CheckpointReactor.ts][6].
85+
86+
#### Quiesced
87+
88+
"Quiesced" means a turn has gone quiet and stable. In [the receipt schema][13], it means the follow-up work has settled, including work in [CheckpointReactor.ts][6].
89+
90+
### Provider runtime
91+
92+
The live backend agent implementation and its event stream. The main service is [ProviderService.ts][14], the adapter contract is [ProviderAdapter.ts][15], and the overview is in [provider-architecture.md][16].
93+
94+
#### Provider
95+
96+
The backend agent runtime that actually performs work. See [ProviderService.ts][14], [ProviderAdapter.ts][15], and [CodexAdapter.ts][17].
97+
98+
#### Session
99+
100+
The live provider-backed runtime attached to a thread. Session shape is in [the orchestration contracts][1], and lifecycle is managed in [ProviderService.ts][14].
101+
102+
#### Runtime mode
103+
104+
The safety/access mode for a thread or session. In [the contracts][1], the main values are `approval-required` and `full-access`. See [runtime-modes.md][18].
105+
106+
#### Interaction mode
107+
108+
The agent interaction style for a thread. In [the contracts][1], the main values are `default` and `plan`. See [runtime-modes.md][18].
109+
110+
#### Assistant delivery mode
111+
112+
Controls how assistant text reaches the thread timeline. In [the contracts][1], `streaming` updates incrementally and `buffered` delivers a completed result. See [ProviderService.ts][14].
113+
114+
#### Snapshot
115+
116+
A point-in-time view of state. The word is used in multiple layers, including orchestration, provider, and checkpointing. See [ProjectionSnapshotQuery.ts][10], [ProviderAdapter.ts][15], and [CheckpointStore.ts][19].
117+
118+
### Checkpointing
119+
120+
Checkpointing captures workspace state over time so the app can diff turns and restore earlier points. The main pieces are [CheckpointStore.ts][19], [CheckpointDiffQuery.ts][20], and [CheckpointReactor.ts][6].
121+
122+
#### Checkpoint
123+
124+
A saved snapshot of a thread workspace at a particular turn. In practice it is a hidden Git ref in [CheckpointStore.ts][19] plus a projected summary from [ProjectionCheckpoints.ts][21]. Capture and lifecycle work happen in [CheckpointReactor.ts][6].
125+
126+
#### Checkpoint ref
127+
128+
The durable identifier for a filesystem checkpoint, stored as a Git ref. It is typed in [the contracts][1], constructed in [Utils.ts][22], and used by [CheckpointStore.ts][19].
129+
130+
#### Checkpoint baseline
131+
132+
The starting checkpoint for diffing a thread timeline. This flow is surfaced through [RuntimeReceiptBus.ts][13], coordinated in [CheckpointReactor.ts][6], and supported by [Utils.ts][22].
133+
134+
#### Checkpoint diff
135+
136+
The patch difference between two checkpoints. Query logic lives in [CheckpointDiffQuery.ts][20], diff parsing lives in [Diffs.ts][23], and finalization is coordinated by [CheckpointReactor.ts][6].
137+
138+
#### Turn diff
139+
140+
The file patch and changed-file summary for one turn. It is usually computed in [CheckpointDiffQuery.ts][20], represented in [the contracts][1], and recorded into thread state by [projector.ts][4].
141+
142+
## Practical Shortcuts
143+
144+
- If you see `requested`, think "intent recorded".
145+
- If you see `completed`, think "result applied".
146+
- If you see `receipt`, think "async milestone signal".
147+
- If you see `checkpoint`, think "workspace snapshot for diff/restore".
148+
- If you see `quiesced`, think "all relevant follow-up work has gone idle".
149+
150+
## Related Docs
151+
152+
- [architecture.md][24]
153+
- [provider-architecture.md][16]
154+
- [runtime-modes.md][18]
155+
- [workspace-layout.md][2]
156+
157+
[1]: ../packages/contracts/src/orchestration.ts
158+
[2]: ./workspace-layout.md
159+
[3]: ../apps/server/src/git/Layers/GitCore.ts
160+
[4]: ../apps/server/src/orchestration/projector.ts
161+
[5]: ../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
162+
[6]: ../apps/server/src/orchestration/Layers/CheckpointReactor.ts
163+
[7]: ../apps/server/src/orchestration/Layers/OrchestrationEngine.ts
164+
[8]: ../apps/server/src/orchestration/decider.ts
165+
[9]: ../apps/server/src/orchestration/commandInvariants.ts
166+
[10]: ../apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
167+
[11]: ../apps/server/src/orchestration/Layers/ProjectionPipeline.ts
168+
[12]: ../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
169+
[13]: ../apps/server/src/orchestration/Services/RuntimeReceiptBus.ts
170+
[14]: ../apps/server/src/provider/Layers/ProviderService.ts
171+
[15]: ../apps/server/src/provider/Services/ProviderAdapter.ts
172+
[16]: ./provider-architecture.md
173+
[17]: ../apps/server/src/provider/Layers/CodexAdapter.ts
174+
[18]: ./runtime-modes.md
175+
[19]: ../apps/server/src/checkpointing/Services/CheckpointStore.ts
176+
[20]: ../apps/server/src/checkpointing/Services/CheckpointDiffQuery.ts
177+
[21]: ../apps/server/src/persistence/Services/ProjectionCheckpoints.ts
178+
[22]: ../apps/server/src/checkpointing/Utils.ts
179+
[23]: ../apps/server/src/checkpointing/Diffs.ts
180+
[24]: ./architecture.md

‎.docs/provider-architecture.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33
The web app communicates with the server via WebSocket using a simple JSON-RPC-style protocol:
44

55
- **Request/Response**: `{ id, method, params }` → `{ id, result }` or `{ id, error }`
6-
- **Push events**: `{ type: "push", channel, data }` for orchestration read-model updates
6+
- **Push events**: typed envelopes with `channel`, `sequence` (monotonic per connection), and channel-specific `data`
7+
8+
Push channels: `server.welcome`, `server.configUpdated`, `terminal.event`, `orchestration.domainEvent`. Payloads are schema-validated at the transport boundary (`wsTransport.ts`). Decode failures produce structured `WsDecodeDiagnostic` with `code`, `reason`, and path info.
79

810
Methods mirror the `NativeApi` interface defined in `@t3tools/contracts`:
911

@@ -12,3 +14,17 @@ Methods mirror the `NativeApi` interface defined in `@t3tools/contracts`:
1214
- `shell.openInEditor`, `server.getConfig`
1315

1416
Codex is the only implemented provider. `claudeCode` is reserved in contracts/UI.
17+
18+
## Client transport
19+
20+
`wsTransport.ts` manages connection state: `connecting` → `open` → `reconnecting` → `closed` → `disposed`. Outbound requests are queued while disconnected and flushed on reconnect. Inbound pushes are decoded and validated at the boundary, then cached per channel. Subscribers can opt into `replayLatest` to receive the last push on subscribe.
21+
22+
## Server-side orchestration layers
23+
24+
Provider runtime events flow through queue-based workers:
25+
26+
1. **ProviderRuntimeIngestion** — consumes provider runtime streams, emits orchestration commands
27+
2. **ProviderCommandReactor** — reacts to orchestration intent events, dispatches provider calls
28+
3. **CheckpointReactor** — captures git checkpoints on turn start/complete, publishes runtime receipts
29+
30+
All three use `DrainableWorker` internally and expose `drain()` for deterministic test synchronization.

0 commit comments

Comments
 (0)