@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 133 lines 8.79 KB
Rendered Raw
1 # Architecture
2
3 T3 Code keeps execution in the environment that owns the workspace. Web, desktop, and mobile
4 clients control it over authenticated RPC. A remote client must never substitute its own filesystem,
5 provider credentials, or machine state for the environment's. The desktop app bundles a server,
6 but its renderer follows the same boundary.
7
8 ## Ownership boundaries
9
10 Provider processes, terminals, Git, and project files belong to the server. Shared connection and
11 domain state belongs in `packages/client-runtime`; clients supply platform services and UI.
12 Keeping that logic shared prevents reconnect and multi-environment behavior from diverging between
13 web and mobile. See [connection runtime](./connection-runtime.md) and
14 [remote environments](./remote.md).
15
16 The [RPC contract](../../packages/contracts/src/rpc.ts) is the boundary between independently
17 versioned clients and servers. Subscriptions send the state a client needs, so a client viewing one
18 thread does not pay for every thread's history. Authentication of a socket does not authorize every
19 method on it. See [environment auth](./environment-auth.md).
20
21 ### Pull request linking compatibility
22
23 Every protocol-2 environment advertises `threadPullRequests`. Once an environment's server config
24 has loaded, clients use persisted `pullRequests[]`, multi-link commands, stack UI, and reverse thread
25 lookup. Before that, they hide linking actions.
26
27 Environments keep advertising `threadPullRequestLinking`, accepting legacy metadata commands, and
28 emitting the derived `linkedPullRequest` field, because older clients still read them. That
29 hostless field includes only links in the thread project's own repository. Retain the legacy wire
30 fields, projection column, and replay support.
31
32 Provider-specific behavior belongs behind an adapter. Orchestration works with normalized commands
33 and events, so adding a provider should not require branches throughout the domain or clients.
34 See [provider constraints](./providers.md).
35
36 ## Settings ownership
37
38 Client preferences stay in the current client; environment defaults and project overrides stay
39 on their owning server. The web and desktop settings target is URL state, resolved against current
40 connections and project membership. An unavailable target must not fall back to another environment.
41 **All environments** is an explicit bulk edit of connected, loaded servers, not a durable global
42 default or a promise to synchronize offline or future environments. Project-group targets similarly
43 select known environment-local checkouts; the group itself does not store inherited defaults.
44
45 ## Durable intent and side effects
46
47 Orchestration state is decided as events, and projections are the source of truth once they apply
48 them. The [v2 orchestrator](../../apps/server/src/orchestration-v2/Orchestrator.ts) serializes commands and
49 decides events without performing provider or filesystem work.
50 [EventSink](../../apps/server/src/orchestration-v2/EventSink.ts) commits events, persisted projections,
51 the accepted command receipt, and outbox effects in one database transaction. Subscribers receive
52 events after that commit. This keeps command retries idempotent and prevents a persisted projection
53 from getting ahead of the event log.
54
55 The [effect worker](../../apps/server/src/orchestration-v2/EffectWorker.ts) performs side effects
56 after intent has been recorded, then feeds results back into orchestration. A command acknowledgement
57 therefore means the intent committed, not that the provider, checkpoint, or other follow-up work
58 finished. Keep external I/O out of command decisions and the database transaction. Effects tied to
59 a lost provider process cannot simply replay; recovery retires them before admitting new work.
60
61 The event log only keeps what live readers need: about a day of history for reconnect replay and
62 command-id retries.
63 [ProjectionMaintenance](../../apps/server/src/orchestration-v2/ProjectionMaintenance.ts) deletes
64 older events the projections cover, so projections cannot be rebuilt from the log. It keeps each
65 stream's newest event (high-water marks, stream versions, snapshot sequences), `thread.created`
66 (the legacy importer's marker), every `running` run update (Codex usage history reads the first
67 of each attempt), and prompt anchors that retained subagent rows reference. A client whose cursor
68 is below both its thread's newest event and the recorded pruned-through sequence missed pruned
69 events, so it resumes from a snapshot; an idle thread's cursor resumes without one. Resumes
70 recheck that sequence after reading the replay, since a pass can prune during the read. V2 command
71 receipts stay for idempotency: a retry older than the retained history is still deduplicated,
72 but its replay comes back without the pruned events. Receipts of imported legacy commands are
73 removed once their threads are imported.
74
75 Retained events must remain decodable on replay. Changing a schema affects old environments at
76 startup as well as live RPC traffic. Compatibility work must account for stored history, not just
77 what the newest client sends.
78
79 ## Turn completion and checkpoints
80
81 A provider turn ending and its follow-up work settling are separate milestones. Orchestration
82 records provider turn and run state independently from
83 [run finalization](../../apps/server/src/orchestration-v2/RunFinalizationService.ts). A late
84 checkpoint or diff must not extend the recorded provider duration or keep the client showing
85 provider work as active. PR discovery after completion also checks that the checkout still matches
86 the thread's non-default branch and that a newer run is not active.
87
88 [Checkpoints](../../apps/server/src/checkpointing/CheckpointStore.ts) use hidden Git refs to
89 capture workspace state without adding commits to the user's branch. A revert must coordinate
90 workspace state with the provider conversation. A provider that cannot roll back its conversation
91 must reject that operation before changing the filesystem.
92
93 Thread settlement is server-owned. The
94 [settlement service](../../apps/server/src/orchestration-v2/ThreadSettlementService.ts) evaluates PR
95 and inactivity settings without a connected client. Merge notifications invalidate cached PR state
96 and trigger a check. A merge outside T3, such as an agent running `gh pr merge`, sends no
97 notification, so the [PR sync reactor](../../apps/server/src/orchestration-v2/PullRequestSyncReactor.ts)
98 re-reads a thread's open links when a run that ran a merge or close command ends. Each forge's
99 definition names its CLI's commands in `changeRequestCloseCommand`. The guarded
100 `thread.auto-settle` command rejects newer activity, explicit settlement overrides, and live or
101 blocked work. It records the activity timestamp for stable
102 sorting and detaches idle provider sessions. Clients render the persisted result; they do not
103 derive settlement from their own clocks or PR caches.
104
105 ## Waiting for asynchronous work
106
107 Tests use [drainable workers](../../packages/shared/src/DrainableWorker.ts) to wait until both the
108 queue and its current item have finished. An empty queue alone does not prove the worker is idle.
109
110 V2 tests also drain the effect worker or await a specific persisted event or receipt. Test signals
111 are separate from the durable command receipts that make dispatch idempotent. Production behavior
112 must use persisted state and events, not test instrumentation or assumptions about elapsed time.
113
114 The Electron shell acquires `DesktopPreReadyPlatform.layer` synchronously before asynchronous
115 services. On Linux this sets the desktop-entry identity and global-shortcut portal flags before
116 Chromium initializes its portal connection. Setting the identity later in `DesktopAppIdentity`
117 is too late: Chromium caches the first registration, including failures. The identity must match
118 the installed entry managed by `DesktopLinuxUrlHandler`. Pre-ready setup also refreshes that entry's
119 `Exec` path before portal registration: AppImage updates can remove the previous executable, which
120 makes the old entry invalid even though its filename is correct. The later URL handler avoids
121 rewriting an identical entry while the portal may be reading it. On Wayland, Electron's synchronous
122 shortcut-registration result only confirms submission; it does not confirm desktop consent or
123 an active binding.
124
125 Native modules never load in the Electron main process on the startup path, and the two the
126 snapshot feature keeps are isolated: `@crowecawcaw/xa11y` runs only in forked Node-mode children
127 (`SnapShotAccessibilityWorker`, `RegionSnapShotWorker`) and a worker thread, and `ffi-rs` loads
128 lazily inside `WindowsForeground.ts` for a handful of Win32 calls. macOS window lookup shells out
129 to `osascript` instead of a native addon. A crash or stall in any of these must not take the app
130 down, so new native capability goes in a child with a deadline, not an `import` in main.
131
132 See the [glossary](./glossary.md) for shared terms and the
133 [development runbook](../operations/development.md) for setup and checks.