@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 178 lines 12.6 KB
Rendered Raw
1 # Performance regression checks
2
3 The v2 transport has a focused regression command:
4
5 ```bash
6 vp run test:perf:v2-wire
7 ```
8
9 It exercises the real v2 projection and client reducers. This matters because the older
10 built-app benchmark fixtures seed v1 orchestration events; running those fixtures against a v2
11 client can produce reassuring timings while missing the active transport path.
12
13 The v2 checks pin these invariants:
14
15 - Cold opens and history pages stop at about 1 MiB of encoded rows. A window that holds a user
16 turn also stops at 10 user turns (20 on older pages) or 500 rows, so ordinary turns stay whole.
17 Any other window, including the inside of one turn longer than 500 rows, stops at 75 rows. The
18 snapshot query applies the same rule before it decodes payloads. Clients can opt into deferring
19 large work groups until expansion. Messages and items outside those groups remain in normal
20 history paging. Required control records and
21 the at-least-one-row rule can exceed the byte target; it is not a hard cap.
22 - The bounded snapshot does not retain the full duplicate conversation-message table. Messages of
23 a run that is still in progress are the exception: all of them accompany the window.
24 - Older activity is fetched in bounded HTTP pages and merged without disturbing the live scroll
25 window.
26 - Clients with confirmed history paging opt into socket snapshot fallbacks that use the same
27 bounded recent-history window and carry the cursor needed to fetch older history. Older clients
28 and WebSocket-only starts retain the compatible full-snapshot fallback.
29 - Snapshot queries bound timeline reads per fork ancestor, not total rows: dependency and
30 control records still accompany the window. Smaller socket frames alone do not establish a
31 whole-server memory reduction.
32 - Resume catch-up checks the original 1 MiB persisted-payload budget before decoding, then
33 replays at most 128 thread events and 1 MiB of projected event JSON before falling back to a
34 snapshot. Raw JSON bytes are not a heap-memory cap. Raising this budget merely because output
35 projects small can increase server allocations on repeated large tool updates.
36 - Raw command output, dynamic-tool result bodies, and inline file-change bodies are omitted at
37 the wire boundary, including small outputs. Explicit failure flags and bounded result IDs
38 preserve status and grouped action counts without shipping those bodies. Reasoning text,
39 command lines, and search results ship when their work group loads. Subagent prompts and results
40 and checkpoint control records still accompany the initial window.
41 Persisted events remain complete; the existing diff endpoints still provide file content when
42 requested.
43 Explicit cross-environment transcript exports preserve full tool bodies so the destination
44 agent can read the context. The export rejects timeline JSON above the file attachment limit
45 before sending it, and before decoding any row when the tool output text alone is over that
46 limit; the client still applies its attachment limit to the complete file.
47 - Live command output reaches a client only through `orchestration.subscribeCommandOutput`, which
48 an expanded command row opens and closes with itself. Raw output deltas are never orchestration
49 events: adapters send them to the
50 [command output hub](../../apps/server/src/orchestration-v2/CommandOutputHub.ts) ahead of
51 ingestion, which keeps one bounded tail per running command and throttles each subscriber. Do not
52 route output deltas through `turn_item.updated`: a busy command would flood the event store and
53 block ingestion for every other thread.
54 - The initial shell contains active navigation rows only. Archived rows use the dedicated archive
55 query, and transcript message bodies stay in thread detail regardless of message size.
56 - Shell resume sends deltas plus compact repository-enrichment metadata, not another full project
57 and thread snapshot. A cursor at the head sequence always resumes, even below the pruned
58 boundary, so a client that just loaded the HTTP snapshot never downloads it again over the
59 socket. That client also names the snapshot's project identities, and a server whose
60 identities did not change since resends only the roots that resolved to no identity.
61 - Auto, steer, and restart sends resolve delivery from authoritative state inside the
62 server's per-thread dispatch lock. Model selection and identified-checkpoint rollback also
63 dispatch without first fetching a full thread projection when the server advertises support.
64 Older servers retain projection-based validation. Explicit start sends already skipped that
65 read, so this saving does not apply to every client send path.
66
67 When changing projection schemas, paging, shell synchronization, or thread state, run this command
68 alongside the focused package typechecks and a real-client pass on every affected surface. The
69 transport performance fixtures validate contract encoding and compare pre-compression RPC JSON
70 for the same synthetic workload, preserving historical application-object counts separately.
71 These are neither compressed WebSocket captures nor measurements of server RSS, and command
72 fixtures exclude unrelated settings calls and subscription events. Payload budgets belong in
73 these tests so regressions fail locally. The transfer budget integration test
74 (`apps/server/integration/transferBudgetV2.integration.test.ts`) sends the opt-ins current clients
75 send. Its opt-in objects are typed `Required` against the contracts, so an opt-in added to a
76 contract fails typecheck until the test sends it; give a fixture the data the opt-in saves. The
77 test caps decoded bytes and rows for a 900-row agent turn in both states: while the turn runs (the
78 bounded snapshot and one older page) and after it finishes (the deferred cold open over HTTP and
79 over the socket alone, and the first page of its deferred work). It caps the socket bytes of three
80 resumes that must not send a snapshot: a thread after one ordinary turn, an idle thread, and a
81 shell cursor too old to replay. It caps the cold-connect shell for a sidebar of settled threads and
82 idle subagents, and the subscription a client opens from that snapshot with its project identities.
83 It caps both answers of the HTTP shell route to a client that holds rows and names their cursor: the
84 few bytes that keep them, and the snapshot that replaces rows too old to replay. It also caps the
85 bytes and
86 the node, subagent, plan, provider turn and checkpoint counts of the bounded snapshot for a thread
87 of 40 finished runs behind one working run, so finished runs cannot ride along with a window. The
88 working run has a ready context handoff, so its history cannot ride along either.
89
90 CI prints every row in the job summary. The pull request comment compares the budgeted rows with
91 `main`, lists the rows that changed or failed, and names each ceiling a pull request raises. A row
92 added to `scenarioRows` in `TransferBudgetReport.integration.ts` reaches the pass/fail check, the
93 summary and the comment.
94
95 The server config has its own budget in `apps/server/src/ws.test.ts`. A client that asks for
96 catalog digests and status deltas gets the provider list of its first config in under 1 KiB, for a
97 provider with 250 slash commands and 200 skills. The lists load with the first cwd snapshot, and a
98 machine refresh sends back an empty provider list.
99
100 ## Event store and startup
101
102 Sequence cursors must seek an index rather than scan retained history. The application sequence
103 index contains project events and v2 thread events; the per-thread sequence index contains only v2
104 thread events. Legacy-only and unknown threads must return zero without scanning other threads.
105 Catch-up queries keep sequence ranges and optional thread or command predicates indexable.
106
107 Startup selects recovery candidates from current projection state before reading full thread
108 projections. Candidate selection includes queued runs, pending runtime requests, live provider
109 sessions, background work, and unfinished delegated deliveries. Archived threads still participate
110 where recovery requires them. Completed thread history is not loaded merely to discover that no
111 work remains.
112
113 Projection verification decodes canonical rows in bounded pages, including shared provider records
114 and fork ancestry. Rebuild replays event pages through a fixed sequence within its transaction;
115 it must not collect the entire event log before projecting it.
116
117 The focused regression coverage lives in `OrchestrationEventStore.sequence.test.ts`,
118 `ProjectionRecovery.test.ts`, and the provider runtime recovery tests under `apps/server/src`.
119
120 ## Background work and navigation
121
122 The settlement worker reads active, unpinned threads without explicit settlement overrides from
123 `ProjectionStore.getSettlementCandidates`. It reads the latest run and user-message timestamps,
124 rejects active runs and pending requests, and checks background work using the same derivation as
125 the shell. It does not load archived histories, fork ancestry, transcript counts, or provider
126 sessions. The orchestrator still validates the current thread before applying settlement.
127
128 Read receipts use `ProjectionStore.getThread` to load only canonical thread metadata. A visit
129 advances `lastVisitedAt` monotonically without changing `updatedAt` or decoding history. Shell
130 queries read item counts from a per-thread, per-run table that turn-item triggers keep exact, and
131 use a partial index for nonterminal background items, including idle items. Latest user-message
132 reads use an index ordered by update time.
133
134 A projection read that orders messages by their first user or assistant turn item groups those
135 items by `$.messageId` through a partial index on that expression (migration 94), so it does not
136 parse every message item's payload; the index's expression and `WHERE` must stay identical to the
137 query's. Migration 94 scans the turn-item table once on first start; a message item whose payload
138 is not valid JSON is left out of the index. Each message-item write re-parses the old and new
139 payload for the index, so its cost grows with the payload.
140
141 Command palette results keep live VCS and linked pull-request queries leased to the visible
142 viewport, including a small overscan region. Cached badges remain available while leases are
143 released. Local Git status reads skip divergence calculations; callers that need ahead/behind
144 counts keep the full status path. Cached fetch failures share the existing backoff and log only
145 the actual failed attempt. Unchanged desktop environment bootstrap reads retain their array
146 identity so polling does not invalidate subscribers.
147
148 Local trace records and provider event logs use asynchronous, serialized file writes and rotation.
149 Batching synchronous appends still stalls the server event loop on slow storage, especially on
150 Windows. While a trace write is slow, producers keep up to one trace file of records, so the spans
151 that time a stall survive it; records drop only while the disk stays stuck. Provider logging
152 retains backpressure. Shutdown drains accepted writes before closing their scope.
153
154 Relay awareness queues one pending publication per thread and retains a follow-up when the thread
155 changes during a send. Transcript deltas and tool output do not enqueue awareness work. Run,
156 request, and relevant thread metadata events do. Configuration is checked before shell reads, and
157 connection changes invalidate published identities so relinking can publish unchanged state.
158 Failed publications retry the latest state up to five times with exponential delays. A new
159 relevant event resets the budget; successful publication, disabling, or unlinking cancels retries.
160 After the budget is exhausted, publication waits for another relevant event instead of generating
161 continuous traffic during an outage.
162
163 Focused coverage: `ProjectionSettlement.test.ts`, `ThreadSettlementService.test.ts`,
164 `runtimeLayer.test.ts`, `AgentAwarenessRelay.test.ts`, `GitVcsDriverCore.test.ts`, and
165 `desktopLocal.test.ts`.
166
167 ## Mobile looping animations
168
169 `apps/mobile/package.json` sets Reanimated's `DISABLE_COMMIT_PAUSING_MECHANISM` so keyboard avoiding
170 animates on iOS. Reanimated documents that flag as safe only alongside React Native's
171 `preventShadowTreeCommitExhaustion`, which defaults to off and needs React Native built from source,
172 so our builds run without it. Reanimated commits each animation frame to the shadow tree, and
173 without commit pausing those commits can starve React's: the JS thread keeps retrying its commit,
174 the screen freezes, and back does nothing. Release builds retry forever; dev builds abort with
175 `ShadowTree.cpp: assertion failed (attempts < 1024)`. Looping animations that stay on screen while
176 heavy content renders should use React Native's `Animated` with `useNativeDriver: true`, which
177 updates views without commits, not Reanimated's `withRepeat`. The running-thread shimmer in
178 `thread-work-log.tsx` is the example.