Skip to content

Commit ee255a5

Browse files
authored
Merge branch 'main' into sidebar-unseen-completion-background-shell
2 parents 023bb60 + a5b34b2 commit ee255a5

250 files changed

Lines changed: 12577 additions & 7595 deletions

File tree

Some content is hidden

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

‎.agents/skills/test-t3-app/references/sqlite-fixtures.md‎

Lines changed: 7 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@ Load this reference only when inspecting or seeding local T3 state directly.
44

55
## Select the correct database
66

7-
When `--base-dir` or `--home-dir` is explicit, runtime state lives under `<base-dir>/userdata` and the database path is `<base-dir>/userdata/state.sqlite`. The `<base-dir>/dev` state directory is only the fallback for an implicit development home, preventing an ordinary `vp run dev` from touching production state.
7+
When `--base-dir` or `--home-dir` is explicit, runtime state lives under `<base-dir>/userdata` and the database path is `<base-dir>/userdata/statev2.sqlite`. The `<base-dir>/dev` state directory is only the fallback for an implicit development home, preventing an ordinary `vp run dev` from touching production state.
8+
9+
The server copies the V1 `state.sqlite` into `statev2.sqlite` only when `statev2.sqlite` is missing. After the first start, edits to `state.sqlite` change nothing.
810

911
Start the target runtime once before seeding so all migrations have run. Use an isolated base directory. Stop the server before writes to avoid racing application state or an active projection.
1012

@@ -23,7 +25,7 @@ Inspect current columns before writing a fixture:
2325
```bash
2426
node apps/server/scripts/t3-sqlite-state.ts query \
2527
--base-dir <base-dir> \
26-
--sql "PRAGMA table_info(projection_threads)"
28+
--sql "PRAGMA table_info(orchestration_v2_projection_threads)"
2729
```
2830

2931
Apply a SQL fixture from a file:
@@ -38,21 +40,10 @@ Use one statement per invocation for both `query` and `exec`; the helper wraps w
3840

3941
## Seed projection data carefully
4042

41-
The web UI primarily reads these projection tables:
42-
43-
- `projection_projects`
44-
- `projection_threads`
45-
- `projection_thread_messages`
46-
- `projection_thread_activities`
47-
- `projection_thread_sessions`
48-
- `projection_turns`
49-
- `projection_pending_approvals`
50-
- `projection_thread_proposed_plans`
51-
52-
Inspect `PRAGMA table_info(<table>)` and the current migrations under `apps/server/src/persistence/Migrations/` before constructing inserts. Keep identifiers unique, timestamps as ISO strings, JSON columns valid, and related project/thread/turn IDs consistent.
43+
Clients read projects from `projection_projects` and everything else from the `orchestration_v2_projection_*` tables: threads, runs, messages, turn items, runtime requests, plans, and provider sessions. The older `projection_thread*` tables hold V1 history, which the server imports once per thread at startup; later edits there do not reach the UI.
5344

54-
For a substantial current example, inspect `seedDatabase` in `scripts/mobile-showcase-environment.ts`. Adapt its column set to the target database instead of assuming copied SQL remains current.
45+
Most V2 rows carry a `payload_json` that must decode against the schemas in `packages/contracts/src/orchestrationV2.ts`. The safest start is a row the app wrote itself: create a thread through the UI, copy its rows, and edit them. Keep identifiers unique, timestamps as ISO strings, and related project, thread, and run IDs consistent.
5546

56-
Direct projection writes are appropriate for ephemeral visual states, edge-case counts, long titles, activity lists, and similar UI fixtures. They do not create a coherent orchestration event history. Do not modify `orchestration_events` unless the test specifically exercises projector internals, and do not use direct projection writes to claim backend business behavior works.
47+
Direct projection writes are appropriate for ephemeral visual states, edge-case counts, long titles, long timelines, and similar UI fixtures. They do not create a coherent event history. Leave the event log (`orchestration_events`) unchanged, and do not use direct projection writes to claim backend business behavior works.
5748

5849
Use the app's commands or APIs for behavior tests. Use `node apps/server/src/bin.ts auth ...` for auth state rather than editing `auth_pairing_links` or `auth_sessions`.

‎.github/TRIAGE_EXEMPTIONS.td‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# Explicit contribution-triage exemptions; independent of VOUCHED.td.
22
# Syntax: github:username (one entry per line; no denouncements).
33
# Keep entries sorted alphabetically. Only the trusted upstream main copy applies.
4+
github:bmdavis419
45
github:juliusmarminge
56
github:maria-rcks
7+
github:markflorkowski
68
github:t3dotgg
9+
github:Yash-Singh1

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -487,6 +487,7 @@ jobs:
487487
test,
488488
test_web,
489489
test_server,
490+
transfer-report,
490491
rust,
491492
mobile_native_changes,
492493
mobile_native_static_analysis,

‎.github/workflows/mobile-eas-production.yml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,11 @@ name: Mobile EAS Production
1818
# Store stays a manual App Store Connect step.
1919
# 2. OTA: publish a production-channel update for each platform where at
2020
# least one finished production build matches the current native
21-
# fingerprint. Old-version binaries with a matching fingerprint receive
22-
# it too. When native drift means no binary could install the update,
21+
# fingerprint. Older binaries of the same major version with a matching
22+
# fingerprint receive it too; the major version is part of the
23+
# fingerprint (apps/mobile/fingerprint.config.js), so a new major never
24+
# reaches the previous major's store binaries over the air. When native
25+
# drift means no binary could install the update,
2326
# it is skipped and flagged in the job summary instead of published
2427
# into the void.
2528
# workflow_dispatch remains as a manual override for both modes (e.g. to

‎AGENTS.md‎

Lines changed: 6 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -88,17 +88,8 @@ The most common defect in this repo is a change that works on the path you teste
8888

8989
An empty database is a bad test. Seed your worktree's `.t3` with a copy of real data instead of pointing at live state:
9090

91-
- Copy from `~/.t3/userdata` (the developer's real data, the most realistic test set) or `~/.t3/dev`. Worktree state lives at `<worktree>/.t3/userdata`.
92-
- Snapshot the database with `VACUUM INTO`, which is safe even while a server has the source open and yields one consistent file:
93-
94-
```bash
95-
mkdir -p .t3/userdata
96-
rm -f .t3/userdata/state.sqlite* # VACUUM INTO refuses to overwrite
97-
bun -e "new (require('bun:sqlite').Database)(process.env.HOME + '/.t3/userdata/state.sqlite', { readonly: true }).run(\"VACUUM INTO '.t3/userdata/state.sqlite'\")"
98-
```
99-
100-
A plain `cp` is only safe when no server has the source open, and must bring the `-wal` and `-shm` siblings along. A live file copy is a corrupt copy.
101-
91+
- Run `vp run migrate-dev-db` with your dev server stopped. It rebuilds `<worktree>/.t3/userdata/statev2.sqlite` from a read-only snapshot of `~/.t3/userdata/statev2.sqlite`, the developer's real data. It keeps recent projects and their stopped threads, and drops scheduled tasks, pending work, and auth sessions, so your dev server never runs the developer's agents. Raise `--projects` and `--threads-per-project` for more data.
92+
- Refresh `statev2.sqlite`, not `state.sqlite`. The server copies the V1 `state.sqlite` only when `statev2.sqlite` is missing.
10293
- Bring `secrets` and `settings.json` only if the flow under test needs them.
10394
- Copy in, never symlink. Data flows one way: into your sandbox, never back out.
10495

@@ -108,7 +99,7 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
10899
- Test meaningful logic or observable behavior. Do not render components to static markup to assert props or attributes, or add tests that merely assert callback wiring or mirror the implementation.
109100
- **Do not run repo-wide checks.** No `vp check`, no `vp run -r test`, no `vp run -r typecheck` unless I ask. CI owns the full suite.
110101
- Backend behavior changes ship with focused tests for that behavior.
111-
- The server is event-sourced and its async flows emit typed receipts. Wait on receipts and worker drains, never on sleeps or polling. A test that needs a timeout to pass is wrong.
102+
- The server is event-sourced, and side effects run after the command commits. In tests, drain the effect worker (`OrchestrationEffectWorkerV2.drain`) or await the specific persisted event or `Deferred` that marks the milestone. Never wait on sleeps or polling. A test that needs a timeout to pass is wrong.
112103
- Upon request, user-visible frontend changes should get one integrated pass in a real client: `test-t3-app` for web, `test-t3-mobile` for mobile. The primary agent does this once after integrating. Subagents do not launch their own dev servers. Ask permission before doing computer use or spinning up browsers.
113104

114105
For authorized mobile verification, a missing or outdated native client is a build step, not a blocker. Run `node scripts/mobile-native-client.ts ensure <ios|android> <device-id>` on the simulator host before starting Metro. It checks the local Expo fingerprint and builds/installs when needed. See `test-t3-mobile` for the full workflow.
@@ -120,7 +111,7 @@ For authorized mobile verification, a missing or outdated native client is a bui
120111
- Body: the problem in a sentence or two, then how you fixed it. End with the model and harness that did the work.
121112
- UI changes need before/after images. Motion or timing needs a short video.
122113
- Upload PR evidence to GitHub. Never commit PR-only screenshots or assets such as `.github/pr-assets/`.
123-
- One concern per PR. If the description says "also", split it.
114+
- One request is one PR. Split it only when the maintainer asks. Outside contributions follow the stricter [one problem per PR](CONTRIBUTING.md#one-problem) rule.
124115
- When babysitting: poll checks and comments newer than the last push, verify each bot finding against the source, fix real ones, dismiss false positives with a written reason. Stay quiet when nothing is new. Stop when the bots are green on the latest commit.
125116

126117
## Documentation
@@ -143,9 +134,9 @@ Most code changes do not need an internal documentation change. Agents can read
143134

144135
## How it works
145136

146-
Clients send typed WebSocket requests. The server turns them into _commands_, a pure _decider_ turns commands into persisted _events_, and a _projector_ derives the read model the UI renders. Provider CLIs run as subprocesses; per-provider _adapters_ translate their native protocols into orchestration events. Side effects run in queue-backed _reactors_ that emit _receipts_ when milestones land. Each turn ends with a _checkpoint_, a hidden git ref, so the app can diff and restore.
137+
Clients send typed WebSocket requests. The server turns them into _commands_. The _orchestrator_ (`apps/server/src/orchestration-v2/Orchestrator.ts`) serializes commands and decides _events_ without doing any I/O. The _event sink_ commits those events, the _projections_ the UI reads, the _command receipt_, and _outbox_ effects in one transaction. The _effect worker_ then runs the effects, such as starting a provider turn or capturing a checkpoint, and feeds results back as commands. Provider CLIs run as subprocesses; per-provider _adapters_ translate their native protocols into orchestration events. Each turn ends with a _checkpoint_, a hidden git ref, so the app can diff and restore.
147138

148-
Full glossary with file links: `docs/internals/glossary.md`
139+
Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/internals/glossary.md`
149140

150141
## Where code lives
151142

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,9 @@ Explain their relationship when it is not obvious. An adjacent cleanup, refactor
7070
its own PR unless it is necessary to solve the same problem. A large diff alone does not establish that
7171
the PR contains unrelated work.
7272

73+
This rule is for outside contributions. Maintainers, the logins in
74+
[.github/TRIAGE_EXEMPTIONS.td](.github/TRIAGE_EXEMPTIONS.td), may batch related fixes in one PR.
75+
7376
Follow the [documentation rules](AGENTS.md#documentation). Keep internal docs for decisions and
7477
hard-to-discover constraints. Update user guides when how to use a feature changes; skip descriptions
7578
of obvious controls and cosmetic changes.

‎apps/desktop/scripts/browser-secret-native.test.mjs‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -78,21 +78,19 @@ describe.skipIf(hostPlatform !== "linux")("bundled libsecret helper", () => {
7878
expect(result.stderr.length).toBe(0);
7979
});
8080

81-
for (const [scenario, code] of [
81+
it.each([
8282
["missing", 2],
8383
["empty", 2],
8484
["locked", 3],
8585
["cancelled", 3],
8686
["denied", 3],
8787
["unavailable", 4],
8888
["unloaded", 4],
89-
]) {
90-
it(`reports ${scenario} without emitting a secret`, () => {
91-
const result = run([scenario]);
92-
expect(result.status).toBe(code);
93-
expect(result.stdout.length).toBe(0);
94-
});
95-
}
89+
])("reports %s without emitting a secret", (scenario, code) => {
90+
const result = run([scenario]);
91+
expect(result.status).toBe(code);
92+
expect(result.stdout.length).toBe(0);
93+
});
9694
it("rejects invalid arguments before accessing the keyring", () => {
9795
for (const args of [[], [""], ["chrome", "extra"]]) {
9896
const result = run(args);

‎apps/desktop/src/app/DesktopClerk.test.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -303,8 +303,9 @@ it.effect(
303303
},
304304
);
305305

306-
for (const entry of ["startup", "open-url"] as const) {
307-
it.effect(`receives hosted web sign-in through the desktop ${entry} handler`, () =>
306+
it.effect.each(["startup", "open-url"] as const)(
307+
"receives hosted web sign-in through the desktop %s handler",
308+
(entry) =>
308309
Effect.gen(function* () {
309310
storageMock.mockReturnValue(storageAdapter);
310311
createClerkBridgeMock.mockReturnValue({ cleanup: vi.fn(), isPrimaryInstance: true });
@@ -382,5 +383,4 @@ for (const entry of ["startup", "open-url"] as const) {
382383
),
383384
);
384385
}).pipe(Effect.scoped),
385-
);
386-
}
386+
);

‎apps/desktop/src/app/DesktopLifecycle.test.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -101,8 +101,9 @@ function makeDesktopWindowLayer(
101101
}
102102

103103
describe("DesktopLifecycle", () => {
104-
for (const platform of ["darwin", "win32", "linux"] satisfies ReadonlyArray<NodeJS.Platform>) {
105-
it.effect(`lets the updater's quit event proceed on ${platform}`, () => {
104+
it.effect.each(["darwin", "win32", "linux"] satisfies ReadonlyArray<NodeJS.Platform>)(
105+
"lets the updater's quit event proceed on %s",
106+
(platform) => {
106107
const appListeners = new Map<string, (...args: readonly unknown[]) => void>();
107108
let windowsDestroyed = false;
108109
const environmentLayer = Layer.succeed(DesktopEnvironment.DesktopEnvironment, {
@@ -152,8 +153,8 @@ describe("DesktopLifecycle", () => {
152153
assert.isTrue(yield* Ref.get(state.quitting));
153154
}),
154155
).pipe(Effect.provide(layer));
155-
});
156-
}
156+
},
157+
);
157158

158159
it.effect("destroys windows before waiting for backend shutdown", () =>
159160
Effect.gen(function* () {

‎apps/desktop/src/app/DesktopPreReadyPlatform.test.ts‎

Lines changed: 45 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -81,54 +81,52 @@ describe("DesktopPreReadyPlatform", () => {
8181
);
8282
});
8383

84-
for (const previousEntry of [undefined, 'Exec="/Applications/deleted-previous.AppImage" %U']) {
85-
it.effect(
86-
`prepares a ${previousEntry ? "stale" : "missing"} Linux desktop entry before startup yields`,
87-
() => {
88-
vi.stubEnv("VITE_DEV_SERVER_URL", "");
89-
vi.stubEnv("XDG_DATA_HOME", "/xdg");
90-
vi.stubEnv("APPIMAGE", "/Applications/current.AppImage");
91-
getSwitchValueMock.mockReturnValue("");
92-
let desktopName = "t3code.desktop";
93-
let desktopEntry = previousEntry;
94-
let iconInstalled = false;
95-
copyFileSyncMock.mockImplementation((_source: string, destination: string) => {
96-
iconInstalled = destination === "/xdg/icons/com.t3tools.T3Code.desktop.png";
97-
});
98-
setDesktopNameMock.mockImplementation((name: string) => {
99-
desktopName = name;
100-
});
101-
writeFileSyncMock.mockImplementation((path: string, contents: string) => {
102-
if (path === "/xdg/applications/com.t3tools.T3Code.desktop") desktopEntry = contents;
103-
});
84+
it.effect.each([
85+
{ previousEntry: undefined, label: "missing" },
86+
{ previousEntry: 'Exec="/Applications/deleted-previous.AppImage" %U', label: "stale" },
87+
])("prepares a $label Linux desktop entry before startup yields", ({ previousEntry }) => {
88+
vi.stubEnv("VITE_DEV_SERVER_URL", "");
89+
vi.stubEnv("XDG_DATA_HOME", "/xdg");
90+
vi.stubEnv("APPIMAGE", "/Applications/current.AppImage");
91+
getSwitchValueMock.mockReturnValue("");
92+
let desktopName = "t3code.desktop";
93+
let desktopEntry = previousEntry;
94+
let iconInstalled = false;
95+
copyFileSyncMock.mockImplementation((_source: string, destination: string) => {
96+
iconInstalled = destination === "/xdg/icons/com.t3tools.T3Code.desktop.png";
97+
});
98+
setDesktopNameMock.mockImplementation((name: string) => {
99+
desktopName = name;
100+
});
101+
writeFileSyncMock.mockImplementation((path: string, contents: string) => {
102+
if (path === "/xdg/applications/com.t3tools.T3Code.desktop") desktopEntry = contents;
103+
});
104104

105-
return Effect.scoped(
106-
Effect.gen(function* () {
107-
const portalIdentity = Promise.resolve().then(() => ({
108-
desktopName,
109-
desktopEntry,
110-
iconInstalled,
111-
}));
112-
yield* Layer.build(
113-
DesktopPreReadyPlatform.layer.pipe(
114-
Layer.provide(Layer.succeed(HostProcessPlatform, "linux")),
115-
),
116-
);
117-
const identity = yield* Effect.promise(() => portalIdentity);
118-
assert.equal(identity.desktopName, "com.t3tools.T3Code.desktop");
119-
assert.include(identity.desktopEntry ?? "", 'Exec="/Applications/current.AppImage" %U');
120-
assert.include(identity.desktopEntry ?? "", "Name=T3 Code (Alpha)");
121-
assert.include(identity.desktopEntry ?? "", "MimeType=x-scheme-handler/t3code;");
122-
assert.include(
123-
identity.desktopEntry ?? "",
124-
"Icon=/xdg/icons/com.t3tools.T3Code.desktop.png",
125-
);
126-
assert.isTrue(identity.iconInstalled);
127-
}),
128-
).pipe(Effect.ensuring(Effect.sync(() => vi.unstubAllEnvs())));
129-
},
130-
);
131-
}
105+
return Effect.scoped(
106+
Effect.gen(function* () {
107+
const portalIdentity = Promise.resolve().then(() => ({
108+
desktopName,
109+
desktopEntry,
110+
iconInstalled,
111+
}));
112+
yield* Layer.build(
113+
DesktopPreReadyPlatform.layer.pipe(
114+
Layer.provide(Layer.succeed(HostProcessPlatform, "linux")),
115+
),
116+
);
117+
const identity = yield* Effect.promise(() => portalIdentity);
118+
assert.equal(identity.desktopName, "com.t3tools.T3Code.desktop");
119+
assert.include(identity.desktopEntry ?? "", 'Exec="/Applications/current.AppImage" %U');
120+
assert.include(identity.desktopEntry ?? "", "Name=T3 Code (Alpha)");
121+
assert.include(identity.desktopEntry ?? "", "MimeType=x-scheme-handler/t3code;");
122+
assert.include(
123+
identity.desktopEntry ?? "",
124+
"Icon=/xdg/icons/com.t3tools.T3Code.desktop.png",
125+
);
126+
assert.isTrue(identity.iconInstalled);
127+
}),
128+
).pipe(Effect.ensuring(Effect.sync(() => vi.unstubAllEnvs())));
129+
});
132130

133131
it.effect("keeps startup available when the early desktop entry cannot be written", () => {
134132
getSwitchValueMock.mockReturnValue("");

0 commit comments

Comments
 (0)