@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 163 lines 9.96 KB
Rendered Raw
1 # Connection runtime
2
3 Web, the desktop renderer, and mobile share one connection owner per environment
4 in `packages/client-runtime`. Platform code supplies storage, credentials, network
5 signals, and application lifecycle events. React views consume the runtime.
6 Keeping retries and session lifetime here prevents competing reconnect loops when
7 several views need the same environment.
8
9 ## One transport retry owner
10
11 The [supervisor](../../packages/client-runtime/src/connection/supervisor.ts) owns
12 transport retry policy; resolving an endpoint and opening an RPC session are single
13 attempts. Transient failures retry with jittered exponential backoff, capped at
14 five minutes, that resets only after a connection stays up. Without jitter, every
15 client of a restarted server reconnects in the same second; with a short cap, a
16 client that can never connect retries all day. Offline states and authentication
17 failures wait for a wakeup instead of spending attempts on unchanged conditions.
18
19 Foregrounding, a network change, an explicit retry, and an offline report probe
20 the established session, and only a failed probe reconnects. Offline reports are
21 often wrong, for example for a loopback server. The OS can kill a suspended
22 socket without a close event, so a probe still unanswered after 500 ms asks the
23 host for its public descriptor over a fresh request, again each second until it
24 answers. If the host answers while the socket delivers no frame, the socket is
25 dead and is replaced, even while the network reports offline: at once on
26 loopback and LAN, and 2.5 seconds after the check starts elsewhere, where one
27 lost packet can stall a live socket. Without that evidence the probe deadline
28 decides: 3 seconds on loopback and LAN routes and after a long mobile
29 suspension, when the data on screen is stale; 15 seconds elsewhere, because a
30 tailnet over DERP or a VPN can be slower than that on a live socket. A long
31 suspension's probe that times out also replaces the socket regardless of the
32 network report. The web and desktop foreground probe skips the fresh request,
33 because a busy host can answer it before a queued probe. Foregrounding also
34 wakes a pending retry immediately. A long suspension restarts an in-flight
35 attempt; a short one leaves it alone.
36
37 The [registry](../../packages/client-runtime/src/connection/registry.ts) scopes
38 connections by environment. An involuntary disconnect retains the registration
39 and cached data. Explicit removal closes the scope and clears credentials,
40 projections, and platform-owned state such as drafts. Cloud-account changes apply
41 to relay registrations; they must not discard directly paired environments.
42
43 ## HTTP authorization
44
45 RPC sessions authenticate at socket upgrade, while HTTP requests need current
46 credentials from the
47 [authorization service](../../packages/client-runtime/src/authorization/service.ts).
48 Replacing a healthy socket for HTTP renewal would interrupt conversations and
49 change the transport generation without a transport failure. Refresh failure
50 belongs to the HTTP operation.
51
52 The server closes a socket when its session is revoked or expires. T3 Connect
53 access tokens last one hour, so the driver renews a live socket's token in its
54 last minute. The server then moves the socket to the newer session for the same
55 DPoP key, subject, and scopes
56 ([`SessionStore.awaitInvalidation`](../../apps/server/src/auth/SessionStore.ts)).
57 If renewal fails, the socket closes at expiry and the supervisor reconnects.
58
59 Session listings must retain unrevoked connected sessions after credential expiry
60 so an open connection does not disappear from connection management. This does
61 not extend the credential's lifetime. New HTTP requests and socket upgrades still
62 require valid credentials.
63
64 ## Transport health and data freshness are separate
65
66 A socket opening is insufficient evidence that the environment is usable. The
67 [RPC session](../../packages/client-runtime/src/rpc/session.ts) waits for the
68 initial server configuration before becoming ready. Shell and thread data then
69 have their own synchronization state. A failed shell subscription can coexist
70 with a healthy connection; labeling that state "reconnecting" promises a
71 transport retry that will never happen.
72
73 Cached projections remain readable offline. They must neither imply a live
74 connection nor overwrite newer live data during a reconnect. Loading and
75 resuming snapshots belongs to the shared state services, so every view agrees
76 on which data is current.
77
78 The shell snapshot loads over HTTP, which needs only the prepared connection, so
79 the [shell state](../../packages/client-runtime/src/state/shell.ts) can ask for
80 it before the socket and the config are ready. Two constraints follow. The live
81 config stays the authority: rows loaded early for a build or with omissions that
82 it does not confirm are replaced, never resumed. And an HTTP answer must never
83 land on rows the socket has moved on: the subscription waits for the answer, and
84 when held rows can resume, it ends the request 3 seconds after the socket is
85 ready. A proxy that drops `/api` without an answer then does not hold the
86 connect for the HTTP timeout.
87
88 Each environment synchronizes at its own time, so a thread list that follows every
89 snapshot moves once per environment on each cold start and resume. Mobile lists read
90 [steady shells](../../packages/client-runtime/src/state/steadyShells.ts): an
91 environment's rows stay as shown until its connection's server snapshot arrives,
92 it is synchronized, or it disconnects, and environments that get there within two
93 seconds of each other show together. Only an environment that is connected or on
94 its first attempt, and still owes its snapshot, is waited for; a retry can take
95 minutes. A move in a list is refused while its rows wait, because its plan would
96 use order keys the server may have replaced. Every other row action looks up the
97 live row before it reads thread state, so an undo plan or a guard never uses a held
98 row. The hold stops only changes the user
99 did not cause: a command that moves or removes a row (settle, snooze, pin, archive,
100 delete, and their reverses) makes that environment's rows follow the live snapshot
101 until it is live. Point reads (a
102 thread's own shell, route checks) keep the live snapshot, where a row the server just
103 sent must not look missing. The decision reads the snapshot's own sequence: a second
104 atom derived from the same shell state can be one update behind the rows. The mobile
105 splash screen also waits, for a bounded time, until every enabled environment has
106 read its cached shell and Home's list has laid out those rows, so the first frame
107 holds all cached rows.
108
109 Shell snapshots can leave rows out when the client asks. Servers that advertise
110 `shellThreadFamilies` leave out idle subagent children: a child stays while it
111 has a live or queued run, a pending request or background work, or a subagent
112 child of its own, so badge and working walks never meet a gap. Servers that also
113 advertise `shellOlderSettled` keep only the 25 newest settled top-level threads
114 (and any tied with the 25th, pinned, snoozed, live, or above a kept child); the
115 snapshot's `olderSettled` names that cut and counts the rest per project. Left-out
116 rows load on demand and merge behind shell rows
117 ([thread families](../../packages/client-runtime/src/state/threadFamilies.ts)):
118 the family a thread view or a queued message mounts holds every active thread
119 sharing the thread's root, so it also brings back an old settled thread opened by
120 link; the Settled shelf reads pages below the cut; searches return the rows of
121 older matches. A missing shell row therefore does not prove a thread is gone:
122 code that deletes data or a worktree on absence must check the family or the
123 server first.
124
125 The Settled count is local Settled rows, minus local rows below the cut, plus the
126 server's counts
127 ([older settled threads](../../packages/client-runtime/src/state/olderSettledThreads.ts)).
128 The counts are re-read when a removal or an old row's arrival or change could
129 move them, so archiving any thread costs one small read. A shelf lists an older
130 row only above the highest page frontier of the environments that can still
131 load, so the merged list stays a correct prefix while a page loads. An
132 environment with no snapshot this session, or a failed page, holds no one back.
133 On-demand reads wait for the session's first authoritative snapshot
134 (`generation > 0`), and each is keyed by generation. A resume that skips that
135 snapshot must still bump `generation` once verified, and may reuse a cached
136 snapshot only when its omissions match what the session asks for.
137
138 [Thread detail](../../packages/client-runtime/src/state/threads.ts) separates
139 subscription lifetime from cache lifetime. Mounted consumers share one live
140 stream, which stops when the last consumer unmounts; hidden mounted routes still
141 count. A registry-local cache retains state and its replay cursor for five idle
142 minutes so back navigation can resume without another snapshot download.
143
144 The desktop app adds one consumer: a
145 [keep-alive](../../apps/web/src/state/threads.ts) mounts every thread whose
146 session is starting or running, in each enabled environment. Opening a running
147 thread then needs no replay. The shell and detail streams are independent, so
148 the shell can report a stop before the detail loads or catches up. A stopped
149 thread stays mounted until its own stream is live and shows the stop, and the
150 stream then closes and saves the settled state.
151 Web and mobile do not keep threads alive.
152
153 Retain state and cursor together only after an update finishes. Cancellation must
154 not advance the cached cursor beyond the applied data, and an old scope must not
155 overwrite its successor's cache. Preserve pagination data on reuse, but clear
156 canceled loading state.
157
158 The [RPC boundary](../../packages/client-runtime/src/rpc/client.ts) resolves
159 requests against the current session at execution time. Durable subscriptions
160 follow replacement sessions. After a transport failure they wait for the
161 supervisor; an expected domain failure may resubscribe on the same healthy
162 session. Reconnection does not automatically replay mutations, whose retry and
163 idempotency rules belong to the operation.