Skip to content

Commit 391a759

Browse files
feat(mobile): give agents one install command with cache telemetry
`vp run mobile:install <ios|android> [device]` targets the only booted simulator or connected Android device, prints short progress and one JSON line, sends build output to a log it names, and prints expected errors with the next command instead of a stack trace. It computes the native fingerprint once unless it builds, and installs on physical Android phones (same APK per ABI, adb reverse for Metro). Installs report local/remote/executed/failed with the build time they saved through the task-cache telemetry, and the Worker records each artifact's build duration and tags native requests with hit/miss. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 4a82af4 commit 391a759

7 files changed

Lines changed: 283 additions & 71 deletions

File tree

‎.agents/skills/test-t3-mobile/SKILL.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,15 @@ when inspecting or seeding SQLite. Stop the test server before fixture writes.
3131
From the checkout being tested on the selected device host, run:
3232

3333
```bash
34-
node scripts/mobile-native-client.ts ensure <ios|android> <device-id>
34+
vp run mobile:install <ios|android> <device-id>
3535
```
3636

37-
This reuses a matching native client or builds and installs one. Authorized
38-
mobile verification includes that build step unless the user prohibits it.
37+
This installs the dev client for the checkout's native fingerprint: from the
38+
device, the local cache, or the shared cache in seconds, building once only
39+
when no machine has that fingerprint yet (5-15 minutes, logged to the file it
40+
names). The device id may be omitted when exactly one device is booted. It
41+
prints one JSON line; on failure it names the next command. Authorized mobile
42+
verification includes that step unless the user prohibits it.
3943

4044
Start `vp run dev:client` from `apps/mobile`, or reuse a healthy Metro belonging
4145
to this checkout. Open its printed development-client URL with AgentDevice

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
134134

135135
- 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.
136136

137-
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.
137+
For authorized mobile verification, a missing or outdated native client is an install step, not a blocker. Run `vp run mobile:install <ios|android> [device-id]` on the device host before starting Metro; it targets the only booted simulator or connected Android device when the id is omitted. It installs the dev client for this checkout's native fingerprint from the shared cache in seconds and builds only when no machine has built it yet, so prefer it over `expo run:*`, `xcodebuild`, or `gradlew`, which rebuild from scratch. Its stdout is one JSON line; build output goes to the log it names. See `test-t3-mobile` for the full workflow.
138138

139139
## Pull requests
140140

‎apps/mobile/README.md‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -22,25 +22,27 @@ repository-root `.env` or `.env.local`, not an `apps/mobile/.env` file. See
2222

2323
## Development
2424

25-
For simulator/emulator development, select and boot a device, then ensure its native client matches
26-
this checkout before starting Metro:
25+
For simulator, emulator, or Android phone development, boot or connect a device, then install the
26+
native client that matches this checkout before starting Metro:
2727

2828
```bash
29-
node ../../scripts/mobile-native-client.ts ensure ios <simulator-udid>
30-
# Or: node ../../scripts/mobile-native-client.ts ensure android <emulator-serial>
29+
vp run mobile:install ios [simulator-udid]
30+
# Or: vp run mobile:install android [emulator-or-phone-serial]
3131
vp run dev:client
3232
```
3333

34-
The helper compares a local Expo fingerprint and the installed binary with its last install
35-
record. Missing, stale, or unverified clients are installed from a build for that fingerprint,
36-
looked up in `~/.cache/t3code/native-clients/artifacts`, then the shared task cache, and built only
37-
when neither has it. One iOS simulator build serves every iPhone and iPad simulator, and one APK
38-
per emulator ABI (x86_64 or arm64-v8a) serves every emulator of that ABI. Builds are shared back when your task-cache login
39-
(`bash infra/task-cache/install.sh`) can write. `T3_NATIVE_CLIENT_CACHE=read` skips the upload and
40-
`off` skips the shared cache.
41-
42-
Use `check` instead of `ensure` for a read-only decision: exit 0 means compatible, 2 means an install
43-
is needed, and 1 means an operational error. Run it on the simulator host; no EAS login is required.
34+
The device argument can be omitted when exactly one device is booted or connected. The helper
35+
compares this checkout's Expo fingerprint and the installed binary with its last install record,
36+
and reuses a matching client. Otherwise it installs the build for that fingerprint from
37+
`~/.cache/t3code/native-clients/artifacts`, then the shared task cache, and builds only when
38+
neither has it. One iOS simulator build serves every iPhone and iPad simulator, and one APK per
39+
ABI (x86_64 or arm64-v8a) serves every emulator and phone of that ABI. Build output goes to the
40+
log file it prints (`T3_NATIVE_CLIENT_VERBOSE=1` streams it instead). Builds are shared back when
41+
your task-cache login (`bash infra/task-cache/install.sh`) can write. `T3_NATIVE_CLIENT_CACHE=read`
42+
skips the upload and `off` skips the shared cache. Physical iPhones still use `vp run ios:dev`.
43+
44+
For a read-only decision, run `node ../../scripts/mobile-native-client.ts check <ios|android>
45+
[device]`: exit 0 means compatible, 2 means an install is needed, and 1 means an operational error.
4446
An externally installed client is unverified until the helper installs it once.
4547

4648
Start Metro for an already verified dev client:

‎infra/task-cache/src/NativeClients.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ it.effect("serves a writer's multipart upload to readers with its digest", () =>
9393
const created = yield* request("/uploads", {
9494
name: "julius",
9595
method: "POST",
96-
headers: { "x-t3-digest": digest },
96+
headers: { "x-t3-digest": digest, "x-t3-build-ms": "540000" },
9797
});
9898
const { uploadId } = (yield* Effect.promise(() => created.json())) as { uploadId: string };
9999
const parts = [];
@@ -117,6 +117,7 @@ it.effect("serves a writer's multipart upload to readers with its digest", () =>
117117
const download = yield* request("", { name: "ci-reader", method: "GET" });
118118
expect(download.status).toBe(200);
119119
expect(download.headers.get("x-t3-digest")).toBe(digest);
120+
expect(download.headers.get("x-t3-build-ms")).toBe("540000");
120121
expect(yield* Effect.promise(() => download.text())).toBe("native client");
121122

122123
const again = yield* request("/uploads", {

‎infra/task-cache/src/NativeClients.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -112,24 +112,34 @@ const make = Effect.gen(function* () {
112112

113113
if (operation === "download") {
114114
const object = yield* r2(() => bindings.CLIENTS.get(key));
115+
yield* Effect.annotateCurrentSpan({ "native.result": object ? "hit" : "miss" });
115116
if (!object) return yield* new NativeClientsError({ status: 404, reason: "missing" });
116117
return new Response(object.body as unknown as ReadableStream, {
117118
headers: {
118119
"Content-Type": "application/octet-stream",
119120
"Content-Length": String(object.size),
120121
"Cache-Control": "no-store",
121122
"X-T3-Digest": object.customMetadata?.digest ?? "",
123+
"X-T3-Build-Ms": object.customMetadata?.buildMs ?? "0",
122124
},
123125
});
124126
}
125127
if (operation === "create") {
126128
const digest = request.headers.get("x-t3-digest") ?? "";
127129
if (!digestPattern.test(digest))
128130
return yield* new NativeClientsError({ status: 400, reason: "invalid_digest" });
129-
if (yield* r2(() => bindings.CLIENTS.head(key))) return Response.json({ exists: true });
131+
if (yield* r2(() => bindings.CLIENTS.head(key))) {
132+
yield* Effect.annotateCurrentSpan({ "native.result": "exists" });
133+
return Response.json({ exists: true });
134+
}
135+
const buildMs = request.headers.get("x-t3-build-ms") ?? "";
130136
const upload = yield* r2(() =>
131137
bindings.CLIENTS.createMultipartUpload(key, {
132-
customMetadata: { digest, writer: developer! },
138+
customMetadata: {
139+
digest,
140+
writer: developer!,
141+
buildMs: /^\d{1,10}$/.test(buildMs) ? buildMs : "0",
142+
},
133143
}),
134144
);
135145
return Response.json({ uploadId: upload.uploadId });
@@ -154,6 +164,7 @@ const make = Effect.gen(function* () {
154164
Effect.mapError(() => new NativeClientsError({ status: 400, reason: "invalid_parts" })),
155165
);
156166
yield* r2(() => upload.complete([...body.parts]));
167+
yield* Effect.annotateCurrentSpan({ "native.result": "stored" });
157168
return new Response(null, { status: 204 });
158169
},
159170
Effect.catchTags({

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
"knip:check": "knip --include files,dependencies --no-config-hints && knip --workspace apps/server --workspace apps/desktop --workspace apps/web --workspace packages/client-runtime --workspace packages/contracts --workspace packages/effect-acp --workspace packages/effect-codex-app-server --workspace packages/shared --workspace packages/ssh --workspace packages/tailscale --workspace packages/provider-core --workspace packages/provider-acp --workspace packages/provider-acp-registry --workspace packages/provider-testing --workspace packages/provider-pi --workspace packages/provider-muse --workspace packages/provider-opencode --workspace packages/provider-cursor --workspace packages/provider-grok --workspace packages/source-control-core --workspace packages/source-control-definitions --workspace packages/source-control-azure-devops --workspace packages/source-control-bitbucket --workspace packages/source-control-forgejo --workspace packages/source-control-gitcafe --workspace packages/source-control-github --workspace packages/source-control-gitlab --workspace packages/source-control-testing --exports --preprocessor ./scripts/knip-schemas.ts --no-config-hints",
3333
"knip:production": "knip --production --preprocessor ./scripts/knip-schemas.ts",
3434
"lint:mobile": "node scripts/mobile-native-static-check.ts",
35+
"mobile:install": "node scripts/mobile-native-client.ts ensure",
3536
"test": "vp run -r test",
3637
"test:cached": "node scripts/test-cached.ts",
3738
"test:perf:v2-wire": "vp test run apps/server/src/orchestration-v2/WireProjection.test.ts apps/server/src/orchestration-v2/threadHistoryPaging.test.ts apps/server/src/orchestration-v2/ThreadStream.test.ts apps/server/src/orchestration-v2/ThreadTransportPerformance.test.ts apps/server/src/orchestration-v2/ShellStream.test.ts apps/server/src/orchestration-v2/CommandPolicy.test.ts apps/server/src/orchestration-v2/runtimeLayer.test.ts apps/server/src/ws.test.ts packages/contracts/src/orchestrationV2.test.ts packages/client-runtime/src/operations/commands.test.ts packages/client-runtime/src/operations/commands.performance.test.ts packages/client-runtime/src/state/boundedThreadSnapshotHttp.test.ts packages/client-runtime/src/state/threadHistoryController.test.ts packages/client-runtime/src/state/threadHistoryMerge.test.ts packages/client-runtime/src/state/threads-sync.test.ts packages/client-runtime/src/state/shellReducer.test.ts",

0 commit comments

Comments
 (0)