The best way to control Claude Code, Codex and more from any computer or phone
fix(server): agents drive simulators through the device tools instead of ssh (#25661)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Gabriel De Andrade committed
Oct 28, 2026 at 13:28 UTC
d07c0a7c7b91b0b40146546cbc7ab2bb91ff228d
26 files changed
+2280
-214
apps/server/src/device/AgentDeviceShim.ts
+286
-32
@@ -6,49 +6,303 @@ import * as FileSystem from "effect/FileSystem";
6
import * as Path from "effect/Path";
7
8
const SHIM_DIR = "device/bin";
9
+const TARGETS_DIR = "device/targets";
10
+const STALE_RUNTIME =
11
+ "This agent-device command is out of date because T3 Code moved or updated its runtime. Call device_open again for a fresh one.";
12
10
-export const ensureAgentDeviceShim = Effect.fn("AgentDeviceShim.ensure")(function* (input: {
11
- readonly entryPath: string;
12
- readonly stateDir: string;
13
-}) {
14
- const { entryPath } = input;
15
- const fs = yield* FileSystem.FileSystem;
16
- const path = yield* Path.Path;
17
- const platform = yield* HostProcess.Platform;
18
- const node = yield* resolveNodeExecutable("Device automation");
19
- const shimDir = path.join(input.stateDir, SHIM_DIR);
20
- yield* fs.makeDirectory(shimDir, { recursive: true });
21
- const launcherPath = path.join(shimDir, "agent-device-launcher.mjs");
22
- yield* fs.writeFileString(
23
- launcherPath,
24
- `import { spawn } from "node:child_process";
13
+const quoteShell = (value: string) => "'" + value.replaceAll("'", "'\"'\"'") + "'";
14
+
15
+/** agent-device 0.21.31's flags that take a value, so the launcher can find the command past them. */
16
+const VALUE_FLAGS: ReadonlyArray<string> = [
17
+ "--activity",
18
+ "--all",
19
+ "--android-device-allowlist",
20
+ "--app",
21
+ "--appium-version",
22
+ "--artifact",
23
+ "--artifacts-dir",
24
+ "--aws-app-arn",
25
+ "--aws-device-arn",
26
+ "--aws-interaction-mode",
27
+ "--aws-project-arn",
28
+ "--aws-region",
29
+ "-b",
30
+ "--baseline",
31
+ "--bearer-token",
32
+ "--bundle-url",
33
+ "--button",
34
+ "--config",
35
+ "--count",
36
+ "--crop-on",
37
+ "--custom-network",
38
+ "-d",
39
+ "--daemon-auth-token",
40
+ "--daemon-base-url",
41
+ "--daemon-server-mode",
42
+ "--daemon-transport",
43
+ "--delay-ms",
44
+ "--depth",
45
+ "--device",
46
+ "--device-orientation",
47
+ "--dsym",
48
+ "--duration-ms",
49
+ "--fps",
50
+ "--from",
51
+ "--geo-location",
52
+ "--github-actions-artifact",
53
+ "--header",
54
+ "--hold-ms",
55
+ "--host",
56
+ "--in-app",
57
+ "--include",
58
+ "--interval-ms",
59
+ "--ios-simulator-device-set",
60
+ "--ios-xctest-derived-data-path",
61
+ "--ios-xctest-env-dir",
62
+ "--ios-xctestrun-file",
63
+ "--jitter-px",
64
+ "--keyframes",
65
+ "--kind",
66
+ "--language",
67
+ "--launch-args",
68
+ "--launch-console",
69
+ "--launch-url",
70
+ "--lease-backend",
71
+ "--lease-id",
72
+ "--level",
73
+ "--listen-host",
74
+ "--locale",
75
+ "--max-passes",
76
+ "--max-steps",
77
+ "--metro-host",
78
+ "--metro-kind",
79
+ "--metro-port",
80
+ "--network-profile",
81
+ "--on-error",
82
+ "--os-version",
83
+ "--out",
84
+ "--pattern",
85
+ "--pause-ms",
86
+ "--pixel-density",
87
+ "--pixels",
88
+ "--plan-digest",
89
+ "--platform",
90
+ "--pointer-count",
91
+ "--port",
92
+ "--probe-timeout-ms",
93
+ "--project-root",
94
+ "--provider",
95
+ "--provider-app",
96
+ "--provider-appium-version",
97
+ "--provider-build",
98
+ "--provider-custom-network",
99
+ "--provider-device-orientation",
100
+ "--provider-device-type",
101
+ "--provider-geo-location",
102
+ "--provider-language",
103
+ "--provider-locale",
104
+ "--provider-network-profile",
105
+ "--provider-os-version",
106
+ "--provider-project",
107
+ "--provider-session",
108
+ "--provider-session-name",
109
+ "--provider-timezone",
110
+ "--proxy-base-url",
111
+ "--public-base-url",
112
+ "--quality",
113
+ "--record-as",
114
+ "--remote-config",
115
+ "--reporter",
116
+ "--report-junit",
117
+ "--retention-ms",
118
+ "--retries",
119
+ "--run-id",
120
+ "--runtime-file",
121
+ "-s",
122
+ "--scale",
123
+ "--scope",
124
+ "--search-path",
125
+ "--serial",
126
+ "--session",
127
+ "--session-isolation",
128
+ "--session-lock",
129
+ "--settle-quiet",
130
+ "--shard-all",
131
+ "--shard-split",
132
+ "--startup-timeout-ms",
133
+ "--state-dir",
134
+ "--status-host",
135
+ "--steps",
136
+ "--steps-file",
137
+ "--surface",
138
+ "--system",
139
+ "--target",
140
+ "--target-app",
141
+ "--template",
142
+ "--tenant",
143
+ "--threshold",
144
+ "--timeout",
145
+ "--timezone",
146
+ "--udid",
147
+ "--until",
148
+ "--wait",
149
+];
150
+
151
+// Help gets no bound flags (agent-device reads --config even for help); only args before `--` are flags.
152
+// agent-device 0.21.31 refuses some bound flags per command; connect/disconnect/auth/daemon would
153
+// replace T3's connection; device status reads this machine's claims. It reports a sandboxed shell and a
154
+// dropped tunnel alike, so check first, at --daemon-base-url if given, as agent-device prefers it.
155
+const launcherSource = (node: string, entryPath: string, boundArgs: ReadonlyArray<string>) =>
156
+ `import { spawn } from "node:child_process";
157
+import { existsSync, readFileSync } from "node:fs";
158
+import { connect } from "node:net";
159
+const entry = ${JSON.stringify(entryPath)};
160
+const bound = ${JSON.stringify(boundArgs)};
161
+const refused = new Map([["cdp", ["--platform", "--udid", "--config", "--session"]], ["connection", ["--platform", "--udid"]]]);
162
+const managed = ["connect", "disconnect", "auth", "daemon"];
163
const args = process.argv.slice(2);
26
-const informational = args.length === 1 && ["help", "--help", "-h", "--version", "version"].includes(args[0]);
27
-const hasValue = flag => { const index = args.indexOf(flag); return index >= 0 && !!args[index + 1] && !args[index + 1].startsWith("--"); };
28
-if (!informational && !(hasValue("--config") && hasValue("--session"))) {
29
- console.error("Call device_open first and include its --config and --session flags.");
164
+const end = args.indexOf("--");
165
+const options = end < 0 ? args : args.slice(0, end);
166
+const valued = new Set(${JSON.stringify(VALUE_FLAGS)});
167
+let name = "";
168
+for (let index = 0; index < args.length; index++) {
169
+ const arg = args[index];
170
+ if (arg === "--") { name = args[index + 1] ?? ""; break; }
171
+ if (!arg.startsWith("-")) { name = arg; break; }
172
+ if (!arg.includes("=") && valued.has(arg)) index++;
173
+}
174
+const informational = args.length === 0 || ["help", "--help", "-h", "--version", "version"].includes(args[0]) || options.includes("--help") || options.includes("-h");
175
+if (!informational && managed.includes(name)) {
176
+ console.error("T3 Code manages this command's connection to the device, so \`" + name + "\` is not available through it.");
177
process.exit(1);
178
}
179
+if (!informational && name === "device") {
180
+ console.error("\`device status\` reads this machine's device claims, not those on the device's host, so it is not available through this command. Quote the DEVICE_IN_USE error instead.");
181
+ process.exit(1);
182
+}
183
+const skip = refused.get(name) ?? [];
184
+if (!informational) for (let index = 0; index + 1 < bound.length; index += 2) if (!skip.includes(bound[index]) && !options.some(arg => arg === bound[index] || arg.startsWith(bound[index] + "="))) options.push(bound[index], bound[index + 1]);
185
+const command = end < 0 ? options : [...options, ...args.slice(end)];
186
+const hasValue = flag => { const index = options.indexOf(flag); return options.some(arg => arg.startsWith(flag + "=") && arg.length > flag.length + 1) || (index >= 0 && !!options[index + 1] && !options[index + 1].startsWith("--")); };
187
+if (!informational && !skip.includes("--session") && !(hasValue("--config") && hasValue("--session"))) {
188
+ console.error("Call device_open first and run the agent-device command it returns.");
189
+ process.exit(1);
190
+}
191
+if (!existsSync(entry)) {
192
+ console.error(${JSON.stringify(STALE_RUNTIME)});
193
+ process.exit(1);
194
+}
195
+const valueOf = flag => { const inline = options.find(arg => arg.startsWith(flag + "=")); if (inline) return inline.slice(flag.length + 1); const index = options.indexOf(flag); return index >= 0 ? options[index + 1] : undefined; };
196
+const endpoint = () => { try { const url = new URL(valueOf("--daemon-base-url") ?? JSON.parse(readFileSync(valueOf("--config"), "utf8")).daemonBaseUrl); return ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname) && url.port ? url : undefined; } catch { return undefined; } };
197
+const local = informational || refused.has(name) ? undefined : endpoint();
198
+if (local) {
199
+ const failure = await new Promise(resolve => {
200
+ const socket = connect({ host: local.hostname.replace(/^\\[|\\]$/g, ""), port: Number(local.port) });
201
+ socket.setTimeout(3000, () => { socket.destroy(); resolve("ETIMEDOUT"); });
202
+ socket.once("connect", () => { socket.destroy(); resolve(undefined); });
203
+ socket.once("error", error => resolve(error.code ?? "ERROR"));
204
+ });
205
+ if (failure === "EPERM" || failure === "EACCES") {
206
+ console.error("This shell cannot reach T3 Code's device connection at " + local.host + " (connect " + failure + "): a network sandbox is blocking localhost. Run this command again with network access, outside the sandbox.");
207
+ process.exit(1);
208
+ }
209
+ if (failure) {
210
+ console.error("T3 Code's device connection at " + local.host + " is not reachable from this shell (connect " + failure + "). Call device_open again to reconnect; if that succeeds and this repeats, this shell runs in a network sandbox, so run the command with network access, outside the sandbox.");
211
+ process.exit(1);
212
+ }
213
+}
214
const env = { ...process.env, ELECTRON_RUN_AS_NODE: "1" };
215
delete env.AGENT_DEVICE_DAEMON_BASE_URL;
216
delete env.AGENT_DEVICE_DAEMON_AUTH_TOKEN;
217
delete env.AGENT_DEVICE_CONFIG;
36
-const child = spawn(${JSON.stringify(node)}, [${JSON.stringify(entryPath)}, ...args], { stdio: "inherit", env });
218
+const child = spawn(${JSON.stringify(node)}, [entry, ...command], { stdio: "inherit", env });
219
child.on("error", error => { console.error(error.message); process.exitCode = 1; });
220
child.on("exit", code => { process.exitCode = code ?? 1; });
39
-`,
40
- );
221
+`;
222
+
223
+/** Writes a launcher into `dir` and returns the executable agents run. */
224
+const writeLauncher = Effect.fn("AgentDeviceShim.writeLauncher")(function* (input: {
225
+ readonly dir: string;
226
+ readonly entryPath: string;
227
+ readonly boundArgs: ReadonlyArray<string>;
228
+}) {
229
+ const fs = yield* FileSystem.FileSystem;
230
+ const path = yield* Path.Path;
231
+ const platform = yield* HostProcess.Platform;
232
+ const node = yield* resolveNodeExecutable("Device automation");
233
+ yield* fs.makeDirectory(input.dir, { recursive: true });
234
+ const launcherPath = path.join(input.dir, "agent-device-launcher.mjs");
235
+ yield* fs.writeFileString(launcherPath, launcherSource(node, input.entryPath, input.boundArgs));
236
if (platform === "win32") {
42
- const script = `@echo off\r\nsetlocal EnableExtensions DisableDelayedExpansion\r\nset "ELECTRON_RUN_AS_NODE=1"\r\n"${node}" "${launcherPath}" %*\r\n`;
43
- yield* fs.writeFileString(path.join(shimDir, "agent-device.cmd"), script);
44
- } else {
45
- const command = [node, launcherPath]
46
- .map((value) => "'" + value.replaceAll("'", "'\"'\"'") + "'")
47
- .join(" ");
48
- const script = `#!/bin/sh\nexport ELECTRON_RUN_AS_NODE=1\nexec ${command} "$@"\n`;
49
- const shimPath = path.join(shimDir, "agent-device");
50
- yield* fs.writeFileString(shimPath, script);
51
- yield* fs.chmod(shimPath, 0o755);
237
+ const script = `@echo off\r\nsetlocal EnableExtensions DisableDelayedExpansion\r\nif not exist "${node}" (echo ${STALE_RUNTIME} 1>&2 & exit /b 1)\r\nset "ELECTRON_RUN_AS_NODE=1"\r\n"${node}" "${launcherPath}" %*\r\n`;
238
+ const scriptPath = path.join(input.dir, "agent-device.cmd");
239
+ yield* fs.writeFileString(scriptPath, script);
240
+ return scriptPath;
241
}
242
+ const script = `#!/bin/sh\n[ -x ${quoteShell(node)} ] || { echo ${quoteShell(STALE_RUNTIME)} >&2; exit 1; }\nexport ELECTRON_RUN_AS_NODE=1\nexec ${quoteShell(node)} ${quoteShell(launcherPath)} "$@"\n`;
243
+ const scriptPath = path.join(input.dir, "agent-device");
244
+ yield* fs.writeFileString(scriptPath, script);
245
+ yield* fs.chmod(scriptPath, 0o755);
246
+ return scriptPath;
247
+});
248
+
249
+/** The unbound launcher: every call needs the device's target flags. */
250
+export const ensureAgentDeviceShim = Effect.fn("AgentDeviceShim.ensure")(function* (input: {
251
+ readonly entryPath: string;
252
+ readonly stateDir: string;
253
+}) {
254
+ const path = yield* Path.Path;
255
+ const shimDir = path.join(input.stateDir, SHIM_DIR);
256
+ yield* writeLauncher({ dir: shimDir, entryPath: input.entryPath, boundArgs: [] });
257
return shimDir;
258
});
259
+
260
+/**
261
+ * A launcher for one agent-device session with its target flags built in, so
262
+ * agents pass none, and a shell that does not word-split a variable cannot mangle them.
263
+ */
264
+export const bindAgentDeviceLauncher = Effect.fn("AgentDeviceShim.bind")(function* (input: {
265
+ readonly entryPath: string;
266
+ readonly stateDir: string;
267
+ readonly session: string;
268
+ readonly targetArgs: ReadonlyArray<string>;
269
+}) {
270
+ const path = yield* Path.Path;
271
+ return yield* writeLauncher({
272
+ dir: path.join(input.stateDir, TARGETS_DIR, input.session),
273
+ entryPath: input.entryPath,
274
+ boundArgs: input.targetArgs,
275
+ });
276
+});
277
+
278
+/** Removes the bound launchers of agent-device sessions not in `live`. */
279
+export const pruneAgentDeviceLaunchers = Effect.fn("AgentDeviceShim.prune")(function* (input: {
280
+ readonly stateDir: string;
281
+ readonly live: ReadonlySet<string>;
282
+}) {
283
+ const fs = yield* FileSystem.FileSystem;
284
+ const path = yield* Path.Path;
285
+ const dir = path.join(input.stateDir, TARGETS_DIR);
286
+ const sessions = yield* fs.readDirectory(dir).pipe(Effect.orElseSucceed(() => []));
287
+ yield* Effect.forEach(
288
+ sessions.filter((session) => !input.live.has(session)),
289
+ (session) => fs.remove(path.join(dir, session), { recursive: true, force: true }),
290
+ { discard: true },
291
+ ).pipe(Effect.ignore);
292
+});
293
+
294
+export type AgentDeviceCloseOutcome = "closed" | "no-session" | "failed" | "timed-out";
295
+
296
+/** What a launcher's `close` did; only a failure or timeout can leave the device claimed. */
297
+export const agentDeviceCloseOutcome = (result: {
298
+ readonly code: number | null;
299
+ readonly stderr: string;
300
+ readonly timedOut: boolean;
301
+}): AgentDeviceCloseOutcome =>
302
+ result.timedOut
303
+ ? "timed-out"
304
+ : result.code === 0
305
+ ? "closed"
306
+ : result.stderr.includes("SESSION_NOT_FOUND")
307
+ ? "no-session"
308
+ : "failed";
apps/server/src/device/AgentDeviceTarget.test.ts
+336
-5
@@ -2,12 +2,18 @@
2
import * as HostProcess from "@t3tools/shared/HostProcess";
3
import { describe, expect, it } from "@effect/vitest";
4
import * as NodeChildProcess from "node:child_process";
5
+import * as NodeNet from "node:net";
6
import * as NodeUtil from "node:util";
7
import * as NodeServices from "@effect/platform-node/NodeServices";
8
import * as Effect from "effect/Effect";
9
import * as FileSystem from "effect/FileSystem";
10
import * as Path from "effect/Path";
10
-import { ensureAgentDeviceShim } from "./AgentDeviceShim.ts";
11
+import {
12
+ agentDeviceCloseOutcome,
13
+ bindAgentDeviceLauncher,
14
+ ensureAgentDeviceShim,
15
+ pruneAgentDeviceLaunchers,
16
+} from "./AgentDeviceShim.ts";
17
import {
18
agentDeviceConfigPath,
19
agentDeviceSession,
@@ -16,6 +22,18 @@ import {
22
23
const exec = NodeUtil.promisify(NodeChildProcess.execFile);
24
25
+/** A loopback port that accepts connections until the scope closes, like T3's device connection. */
26
+const listeningPort = Effect.acquireRelease(
27
+ Effect.promise(
28
+ () =>
29
+ new Promise<NodeNet.Server>((resolve) => {
30
+ const server = NodeNet.createServer((socket) => socket.destroy());
31
+ server.listen(0, "127.0.0.1", () => resolve(server));
32
+ }),
33
+ ),
34
+ (server) => Effect.promise(() => new Promise<void>((resolve) => server.close(() => resolve()))),
35
+).pipe(Effect.map((server) => (server.address() as NodeNet.AddressInfo).port));
36
+
37
describe("host-bound agent commands", () => {
38
it.effect.skipIf(HostProcess.Platform.defaultValue() === "win32")(
39
"runs both desktop hops as Node with a stripped environment, preserving arguments and exit code",
@@ -67,6 +85,318 @@ exec '${process.execPath.replaceAll("'", "'\"'\"'")}' "$@"
85
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
86
);
87
88
+ it.effect("binds one device's flags into its launcher and leaves help alone", () =>
89
+ Effect.gen(function* () {
90
+ const fs = yield* FileSystem.FileSystem;
91
+ const path = yield* Path.Path;
92
+ const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-device-bound-" });
93
+ const entryPath = path.join(dir, "cli.mjs");
94
+ yield* fs.writeFileString(entryPath, "console.log(JSON.stringify(process.argv.slice(2)));");
95
+ const target = [
96
+ "--platform",
97
+ "ios",
98
+ "--udid",
99
+ "UDID-1",
100
+ "--config",
101
+ "/h.json",
102
+ "--session",
103
+ "t3-a",
104
+ ];
105
+ const command = yield* bindAgentDeviceLauncher({
106
+ entryPath,
107
+ stateDir: dir,
108
+ session: "t3-a",
109
+ targetArgs: target,
110
+ });
111
+ const shared = yield* ensureAgentDeviceShim({ entryPath, stateDir: dir });
112
+ const launch = (launcher: string, args: ReadonlyArray<string>) =>
113
+ exec(process.execPath, [path.join(launcher, "agent-device-launcher.mjs"), ...args]).then(
114
+ (result) => JSON.parse(result.stdout),
115
+ );
116
+ const bound = path.dirname(command);
117
+ expect(yield* Effect.promise(() => launch(bound, ["snapshot", "-i"]))).toEqual([
118
+ "snapshot",
119
+ "-i",
120
+ ...target,
121
+ ]);
122
+ // A flag the agent passes itself wins over the bound one.
123
+ expect(yield* Effect.promise(() => launch(bound, ["open", "--session", "mine"]))).toEqual([
124
+ "open",
125
+ "--session",
126
+ "mine",
127
+ "--platform",
128
+ "ios",
129
+ "--udid",
130
+ "UDID-1",
131
+ "--config",
132
+ "/h.json",
133
+ ]);
134
+ expect(yield* Effect.promise(() => launch(bound, ["snapshot", "--session=mine"]))).toEqual([
135
+ "snapshot",
136
+ "--session=mine",
137
+ "--platform",
138
+ "ios",
139
+ "--udid",
140
+ "UDID-1",
141
+ "--config",
142
+ "/h.json",
143
+ ]);
144
+ // After `--` everything is text: no help, no overrides, and bound flags go before it.
145
+ for (const text of [["--help"], ["literal text", "--session", "mine"]]) {
146
+ expect(yield* Effect.promise(() => launch(bound, ["fill", "@e5", "--", ...text]))).toEqual([
147
+ "fill",
148
+ "@e5",
149
+ ...target,
150
+ "--",
151
+ ...text,
152
+ ]);
153
+ }
154
+ expect(
155
+ yield* Effect.promise(() =>
156
+ launch(shared, ["snapshot", "--config=/h.json", "--session=t3-a"]),
157
+ ),
158
+ ).toEqual(["snapshot", "--config=/h.json", "--session=t3-a"]);
159
+ yield* Effect.promise(() =>
160
+ expect(
161
+ launch(shared, ["fill", "@e5", "--", "--config", "/h.json", "--session", "t3-a"]),
162
+ ).rejects.toThrow("Call device_open first"),
163
+ );
164
+ for (const args of [["help", "gesture"], ["open", "--help"], ["record", "-h"], []]) {
165
+ expect(yield* Effect.promise(() => launch(bound, args))).toEqual(args);
166
+ expect(yield* Effect.promise(() => launch(shared, args))).toEqual(args);
167
+ }
168
+ yield* fs.remove(entryPath);
169
+ yield* Effect.promise(() =>
170
+ expect(launch(bound, ["snapshot"])).rejects.toThrow("Call device_open again"),
171
+ );
172
+ }).pipe(
173
+ Effect.scoped,
174
+ Effect.provideService(HostProcess.IsExecutable, false),
175
+ Effect.provideService(HostProcess.ExecutablePath, process.execPath),
176
+ Effect.provide(NodeServices.layer),
177
+ ),
178
+ );
179
+
180
+ it.effect("passes each command only the bound flags agent-device accepts for it", () =>
181
+ Effect.gen(function* () {
182
+ const fs = yield* FileSystem.FileSystem;
183
+ const path = yield* Path.Path;
184
+ const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-device-commands-" });
185
+ const entryPath = path.join(dir, "cli.mjs");
186
+ yield* fs.writeFileString(entryPath, "console.log(JSON.stringify(process.argv.slice(2)));");
187
+ const command = yield* bindAgentDeviceLauncher({
188
+ entryPath,
189
+ stateDir: dir,
190
+ session: "t3-a",
191
+ targetArgs: [
192
+ "--platform",
193
+ "ios",
194
+ "--udid",
195
+ "UDID-1",
196
+ "--config",
197
+ "/h.json",
198
+ "--session",
199
+ "t3-a",
200
+ ],
201
+ });
202
+ const launch = (args: ReadonlyArray<string>) =>
203
+ exec(process.execPath, [
204
+ path.join(path.dirname(command), "agent-device-launcher.mjs"),
205
+ ...args,
206
+ ]).then((result) => JSON.parse(result.stdout));
207
+ // agent-device 0.21.31 rejects these flags with "unknown option" or "not supported for command".
208
+ const cdp = ["cdp", "target", "list", "--url", "http://127.0.0.1:8081"];
209
+ expect(yield* Effect.promise(() => launch(cdp))).toEqual(cdp);
210
+ expect(yield* Effect.promise(() => launch(["connection"]))).toEqual([
211
+ "connection",
212
+ "--config",
213
+ "/h.json",
214
+ "--session",
215
+ "t3-a",
216
+ ]);
217
+ // The command is found past leading flags and their values, in either form.
218
+ for (const config of [["--config", "/o.json"], ["--config=/o.json"]]) {
219
+ expect(yield* Effect.promise(() => launch([...config, "connection"]))).toEqual([
220
+ ...config,
221
+ "connection",
222
+ "--session",
223
+ "t3-a",
224
+ ]);
225
+ // device status reads claims on the machine it runs on, which is not the device's host.
226
+ yield* Effect.promise(() =>
227
+ expect(launch([...config, "device", "status"])).rejects.toThrow(
228
+ "`device status` reads this machine's device claims, not those on the device's host",
229
+ ),
230
+ );
231
+ }
232
+ expect(yield* Effect.promise(() => launch(["--json", ...cdp]))).toEqual(["--json", ...cdp]);
233
+ for (const managed of [
234
+ ["connect"],
235
+ ["disconnect"],
236
+ ["auth", "status"],
237
+ ["daemon", "stop"],
238
+ ["--config", "/o.json", "auth", "status"],
239
+ ["--", "connect"],
240
+ ]) {
241
+ yield* Effect.promise(() =>
242
+ expect(launch(managed)).rejects.toThrow(
243
+ `T3 Code manages this command's connection to the device, so \`${managed.find((arg) => ["connect", "disconnect", "auth", "daemon"].includes(arg))}\` is not available through it.`,
244
+ ),
245
+ );
246
+ }
247
+ }).pipe(
248
+ Effect.scoped,
249
+ Effect.provideService(HostProcess.IsExecutable, false),
250
+ Effect.provideService(HostProcess.ExecutablePath, process.execPath),
251
+ Effect.provide(NodeServices.layer),
252
+ ),
253
+ );
254
+
255
+ it("tells a released session from a close that failed or timed out", () => {
256
+ const result = (code: number | null, stderr = "", timedOut = false) => ({
257
+ stdout: "",
258
+ stderr,
259
+ code,
260
+ timedOut,
261
+ });
262
+ expect(agentDeviceCloseOutcome(result(0))).toBe("closed");
263
+ // A session that never ran `open` has nothing to release.
264
+ expect(
265
+ agentDeviceCloseOutcome(
266
+ result(1, "Error (SESSION_NOT_FOUND): No active session. Run open first."),
267
+ ),
268
+ ).toBe("no-session");
269
+ expect(
270
+ agentDeviceCloseOutcome(result(1, "Error (COMMAND_FAILED): Remote daemon is unavailable")),
271
+ ).toBe("failed");
272
+ expect(agentDeviceCloseOutcome(result(null, "", true))).toBe("timed-out");
273
+ });
274
+
275
+ it.live("stops before agent-device when T3's device connection is down", () =>
276
+ Effect.gen(function* () {
277
+ const fs = yield* FileSystem.FileSystem;
278
+ const path = yield* Path.Path;
279
+ const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-device-endpoint-" });
280
+ const entryPath = path.join(dir, "cli.mjs");
281
+ yield* fs.writeFileString(entryPath, "console.log(JSON.stringify(process.argv.slice(2)));");
282
+ const configPath = path.join(dir, "host.json");
283
+ // A port that was just free: nothing listens on it, so a connect is refused.
284
+ const port = yield* Effect.promise(
285
+ () =>
286
+ new Promise<number>((resolve) => {
287
+ const server = NodeNet.createServer();
288
+ server.listen(0, "127.0.0.1", () => {
289
+ const address = server.address() as NodeNet.AddressInfo;
290
+ server.close(() => resolve(address.port));
291
+ });
292
+ }),
293
+ );
294
+ yield* writeAgentDeviceConfig(configPath, {
295
+ baseUrl: `http://127.0.0.1:${port}`,
296
+ token: "secret",
297
+ });
298
+ const command = yield* bindAgentDeviceLauncher({
299
+ entryPath,
300
+ stateDir: dir,
301
+ session: "t3-a",
302
+ targetArgs: ["--config", configPath, "--session", "t3-a"],
303
+ });
304
+ const launch = (args: ReadonlyArray<string>) =>
305
+ exec(process.execPath, [
306
+ path.join(path.dirname(command), "agent-device-launcher.mjs"),
307
+ ...args,
308
+ ]);
309
+ yield* Effect.promise(() =>
310
+ expect(launch(["screenshot", "/tmp/shot.png"])).rejects.toMatchObject({
311
+ code: 1,
312
+ stdout: "",
313
+ stderr: `T3 Code's device connection at 127.0.0.1:${port} is not reachable from this shell (connect ECONNREFUSED). Call device_open again to reconnect; if that succeeds and this repeats, this shell runs in a network sandbox, so run the command with network access, outside the sandbox.\n`,
314
+ }),
315
+ );
316
+ // An explicit --daemon-base-url wins over the config, as it does in agent-device.
317
+ const override = `http://127.0.0.1:${yield* listeningPort}`;
318
+ for (const flag of [["--daemon-base-url", override], [`--daemon-base-url=${override}`]]) {
319
+ expect(
320
+ JSON.parse(
321
+ (yield* Effect.promise(() => launch(["screenshot", "/tmp/shot.png", ...flag]))).stdout,
322
+ ),
323
+ ).toEqual([
324
+ "screenshot",
325
+ "/tmp/shot.png",
326
+ ...flag,
327
+ "--config",
328
+ configPath,
329
+ "--session",
330
+ "t3-a",
331
+ ]);
332
+ }
333
+ // cdp talks to Metro, not to T3's connection, so it still runs.
334
+ expect(
335
+ JSON.parse((yield* Effect.promise(() => launch(["cdp", "target", "list"]))).stdout),
336
+ ).toEqual(["cdp", "target", "list"]);
337
+ }).pipe(
338
+ Effect.scoped,
339
+ Effect.provideService(HostProcess.IsExecutable, false),
340
+ Effect.provideService(HostProcess.ExecutablePath, process.execPath),
341
+ Effect.provide(NodeServices.layer),
342
+ ),
343
+ );
344
+
345
+ it.effect("prunes the launchers of ended sessions and keeps the shared one", () =>
346
+ Effect.gen(function* () {
347
+ const fs = yield* FileSystem.FileSystem;
348
+ const path = yield* Path.Path;
349
+ const stateDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-device-prune-" });
350
+ const entryPath = path.join(stateDir, "cli.mjs");
351
+ const shared = yield* ensureAgentDeviceShim({ entryPath, stateDir });
352
+ const bind = (session: string) =>
353
+ bindAgentDeviceLauncher({ entryPath, stateDir, session, targetArgs: [] });
354
+ const kept = yield* bind("t3-open");
355
+ const ended = yield* bind("t3-closed");
356
+ yield* pruneAgentDeviceLaunchers({ stateDir, live: new Set(["t3-open"]) });
357
+ expect(yield* fs.exists(kept)).toBe(true);
358
+ expect(yield* fs.exists(path.dirname(ended))).toBe(false);
359
+ expect(yield* fs.exists(shared)).toBe(true);
360
+ yield* pruneAgentDeviceLaunchers({ stateDir, live: new Set() });
361
+ expect(yield* fs.readDirectory(path.join(stateDir, "device", "targets"))).toEqual([]);
362
+ }).pipe(
363
+ Effect.scoped,
364
+ Effect.provideService(HostProcess.IsExecutable, false),
365
+ Effect.provideService(HostProcess.ExecutablePath, process.execPath),
366
+ Effect.provide(NodeServices.layer),
367
+ ),
368
+ );
369
+
370
+ it.effect.skipIf(HostProcess.Platform.defaultValue() === "win32")(
371
+ "tells the agent to reopen the device when the runtime it was bound to is gone",
372
+ () =>
373
+ Effect.gen(function* () {
374
+ const fs = yield* FileSystem.FileSystem;
375
+ const path = yield* Path.Path;
376
+ const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-device-stale-" });
377
+ const runtime = path.join(dir, "old-node");
378
+ yield* fs.writeFileString(runtime, "#!/bin/sh\nexit 0\n");
379
+ yield* fs.chmod(runtime, 0o755);
380
+ const command = yield* bindAgentDeviceLauncher({
381
+ entryPath: path.join(dir, "cli.mjs"),
382
+ stateDir: dir,
383
+ session: "t3-a",
384
+ targetArgs: ["--config", "/h.json", "--session", "t3-a"],
385
+ }).pipe(Effect.provideService(HostProcess.ExecutablePath, runtime));
386
+ yield* fs.remove(runtime);
387
+ yield* Effect.promise(() =>
388
+ expect(exec(command, ["snapshot"])).rejects.toMatchObject({
389
+ code: 1,
390
+ stderr: expect.stringContaining("Call device_open again"),
391
+ }),
392
+ );
393
+ }).pipe(
394
+ Effect.scoped,
395
+ Effect.provideService(HostProcess.IsExecutable, false),
396
+ Effect.provide(NodeServices.layer),
397
+ ),
398
+ );
399
+
400
it.effect("runs two hosts concurrently and only updates the reconnected host", () =>
401
Effect.gen(function* () {
402
const fs = yield* FileSystem.FileSystem;
@@ -90,9 +420,10 @@ if (process.env.AGENT_DEVICE_DAEMON_BASE_URL) process.exit(2);`,
420
const files = yield* Effect.forEach(["mini", "android"], (host) =>
421
agentDeviceConfigPath(dir, host, path),
422
);
423
+ const ports = [yield* listeningPort, yield* listeningPort, yield* listeningPort];
424
for (const [index, file] of files.entries())
425
yield* writeAgentDeviceConfig(file, {
95
- baseUrl: `http://127.0.0.1:${1000 + index}`,
426
+ baseUrl: `http://127.0.0.1:${ports[index]}`,
427
token: `token-${index}`,
428
});
429
const invoke = (file: string) =>
@@ -109,12 +440,12 @@ if (process.env.AGENT_DEVICE_DAEMON_BASE_URL) process.exit(2);`,
440
{ env: { ...process.env, AGENT_DEVICE_DAEMON_BASE_URL: "http://wrong-host" } },
441
).then((result) => JSON.parse(result.stdout));
442
expect(yield* Effect.promise(() => Promise.all(files.map(invoke)))).toEqual([
112
- { daemonBaseUrl: "http://127.0.0.1:1000", daemonAuthToken: "token-0" },
113
- { daemonBaseUrl: "http://127.0.0.1:1001", daemonAuthToken: "token-1" },
443
+ { daemonBaseUrl: `http://127.0.0.1:${ports[0]}`, daemonAuthToken: "token-0" },
444
+ { daemonBaseUrl: `http://127.0.0.1:${ports[1]}`, daemonAuthToken: "token-1" },
445
]);
446
const second = yield* fs.readFileString(files[1]!);
447
yield* writeAgentDeviceConfig(files[0]!, {
117
- baseUrl: "http://127.0.0.1:2000",
448
+ baseUrl: `http://127.0.0.1:${ports[2]}`,
449
token: "new",
450
});
451
expect((yield* Effect.promise(() => invoke(files[0]!))).daemonAuthToken).toBe("new");
apps/server/src/device/DeviceService.test.ts
+285
-6
@@ -19,6 +19,8 @@ import * as Deferred from "effect/Deferred";
19
import * as Fiber from "effect/Fiber";
20
import * as FileSystem from "effect/FileSystem";
21
import * as Layer from "effect/Layer";
22
+import * as Option from "effect/Option";
23
+import * as PubSub from "effect/PubSub";
24
import * as Queue from "effect/Queue";
25
import * as Ref from "effect/Ref";
26
import * as Schema from "effect/Schema";
@@ -34,6 +36,7 @@ import { makeDeviceHubOperations } from "./DeviceHubOperations.ts";
36
import { NodeRuntimeUnavailableError } from "@t3tools/shared/nodeRuntime";
37
38
import * as DeviceService from "./DeviceService.ts";
39
+import { agentDeviceSession } from "./AgentDeviceTarget.ts";
40
41
const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
42
const decodeBootError = Schema.decodeUnknownSync(Schema.fromJsonString(DeviceBootError));
@@ -603,7 +606,7 @@ it.effect("keeps shutdown successful when subsequent discovery fails", () =>
606
);
607
608
it.effect.each(["shutdown", "close"] as const)(
606
- "%s releases iOS capture so reopening uses a fresh session",
609
+ "%s releases iOS capture and the session's launcher so reopening uses a fresh session",
610
(operation) =>
611
Effect.gen(function* () {
612
const deviceId = DeviceId.make("11111111-1111-1111-1111-111111111111");
@@ -680,19 +683,107 @@ it.effect.each(["shutdown", "close"] as const)(
683
stopAgent: Effect.void,
684
stop: Effect.void,
685
};
683
- const service = yield* DeviceService.makeWithHosts(new Map([[host.id, host]])).pipe(
684
- Effect.provide(NodeCrypto.layer),
685
- );
686
+ const launchers = new Set(["t3-from-a-previous-run"]);
687
+ const released: Array<[string, boolean]> = [];
688
+ // Whether the device was still on when each session was released.
689
+ const releasedWhileBooted: Array<boolean> = [];
690
+ let pauseBind: { entered: Deferred.Deferred<void>; proceed: Deferred.Deferred<void> } | null =
691
+ null;
692
+ const service = yield* DeviceService.makeWithHosts(
693
+ new Map([[host.id, host]]),
694
+ undefined,
695
+ undefined,
696
+ undefined,
697
+ {
698
+ bind: ({ session }) =>
699
+ Effect.gen(function* () {
700
+ if (pauseBind) {
701
+ yield* Deferred.succeed(pauseBind.entered, undefined);
702
+ yield* Deferred.await(pauseBind.proceed);
703
+ }
704
+ launchers.add(session);
705
+ return session;
706
+ }),
707
+ prune: (live) =>
708
+ Effect.sync(() => {
709
+ for (const session of launchers) if (!live.has(session)) launchers.delete(session);
710
+ }),
711
+ // Records whether the launcher still existed, since its close runs through it.
712
+ release: (launcher) =>
713
+ Effect.sync(() => {
714
+ released.push([launcher, launchers.has(launcher)]);
715
+ releasedWhileBooted.push(booted);
716
+ }),
717
+ },
718
+ ).pipe(Effect.provide(NodeCrypto.layer));
719
+ expect(launchers).toEqual(new Set());
720
const input = { threadId, deviceId, platform: "ios" as const };
687
- yield* service.open(input);
721
+ const other = { ...input, threadId: ThreadId.make("capture-recovery-other") };
722
+ const target = (thread: ThreadId) => ({
723
+ threadId: thread,
724
+ hostId: LOCAL_DEVICE_HOST_ID,
725
+ deviceId,
726
+ });
727
+ const bind = Effect.fnUntraced(function* (open: typeof input) {
728
+ yield* service.open(open);
729
+ yield* service.agentLauncher({ ...target(open.threadId), targetArgs: [] });
730
+ return yield* agentDeviceSession(open.threadId, LOCAL_DEVICE_HOST_ID, deviceId);
731
+ }, Effect.provide(NodeCrypto.layer));
732
+ const session = yield* bind(input);
733
+ yield* bind(other);
734
expect(capture).toBe(1);
735
+ expect(launchers.size).toBe(2);
736
if (operation === "shutdown") yield* service.shutdown(input);
737
else yield* service.close({ threadId, deviceId, shutdown: true });
738
expect(capture).toBeNull();
739
expect((yield* service.state).sessions).toEqual([]);
693
- yield* service.open(input);
740
+ expect(launchers).toEqual(new Set());
741
+ // Retiring a session ends its agent-device session too, which releases the device claim.
742
+ // Powering the device off retires the other thread's session on it as well.
743
+ const firstOther = yield* agentDeviceSession(
744
+ other.threadId,
745
+ LOCAL_DEVICE_HOST_ID,
746
+ deviceId,
747
+ ).pipe(Effect.provide(NodeCrypto.layer));
748
+ expect(new Set(released.map(([launcher]) => launcher))).toEqual(
749
+ new Set([session, firstOther]),
750
+ );
751
+ expect(released.every(([, existed]) => existed)).toBe(true);
752
+ // agent-device can close the session's app only while the device is on.
753
+ expect(releasedWhileBooted).toEqual([true, true]);
754
+ // A device_open that was still preparing when the close landed.
755
+ expect(yield* service.agentLauncher({ ...target(threadId), targetArgs: [] })).toEqual(
756
+ Option.none(),
757
+ );
758
+ expect(launchers).toEqual(new Set());
759
+ expect(yield* bind(input)).toBe(session);
760
+ // Reopening the same device ends nothing.
761
+ expect(released).toHaveLength(2);
762
expect(capture).toBe(2);
763
expect((yield* service.state).sessions).toHaveLength(1);
764
+ const otherSession = yield* bind(other);
765
+ yield* service.close({ threadId: other.threadId });
766
+ expect(launchers).toEqual(new Set([session]));
767
+ expect(released.slice(2)).toEqual([[otherSession, true]]);
768
+ expect(otherSession).not.toBe(session);
769
+ // A caller interrupted after retirement committed, while a bind holds the launcher lock.
770
+ pauseBind = { entered: yield* Deferred.make<void>(), proceed: yield* Deferred.make<void>() };
771
+ const binding = yield* Effect.forkChild(
772
+ service.agentLauncher({ ...target(threadId), targetArgs: [] }),
773
+ );
774
+ yield* Deferred.await(pauseBind.entered);
775
+ const updates = yield* service.subscribe;
776
+ const retiring = yield* Effect.forkChild(
777
+ operation === "shutdown" ? service.shutdown(input) : service.close({ threadId }),
778
+ );
779
+ expect((yield* PubSub.take(updates)).sessions).toEqual([]);
780
+ // list writes through the same state lock, so the retirement has committed.
781
+ expect((yield* service.list).sessions).toEqual([]);
782
+ yield* Effect.sync(() => retiring.interruptUnsafe());
783
+ yield* Deferred.succeed(pauseBind.proceed, undefined);
784
+ yield* Fiber.join(binding);
785
+ yield* Fiber.await(retiring);
786
+ expect(launchers).toEqual(new Set());
787
}).pipe(Effect.provide(ServerSettings.layerTest({ enableDeviceSupport: true })), Effect.scoped),
788
);
789
@@ -1150,3 +1241,191 @@ it.effect("a failed tool update reports npm's exit code but not its output", ()
1241
Effect.scoped,
1242
),
1243
);
1244
+
1245
+describe("locating a device id across hosts", () => {
1246
+ const threadId = ThreadId.make("thread-locate");
1247
+ const thisMachine = { id: LOCAL_DEVICE_HOST_ID, label: "This machine" };
1248
+ const macMini = { id: "mac-mini", label: "Mac Mini" };
1249
+ const listingHost = (
1250
+ host: { readonly id: string; readonly label: string },
1251
+ ids: ReadonlyArray<string>,
1252
+ ): DeviceHost.DeviceHost["Service"] => {
1253
+ const devices = ids.map((id) => ({
1254
+ id,
1255
+ name: id,
1256
+ platform: id.startsWith("Pixel") ? ("android" as const) : ("ios" as const),
1257
+ version: "test",
1258
+ booted: true,
1259
+ physical: false,
1260
+ }));
1261
+ const ready: DeviceHost.DeviceHostReady = {
1262
+ nodePath: process.execPath,
1263
+ hub: { origin: "http://device.test" },
1264
+ devices: {
1265
+ list: Effect.succeed({ devices, detail: undefined }),
1266
+ boot: (device) => Effect.succeed(device.id),
1267
+ attach: () => Effect.void,
1268
+ shutdown: () => Effect.void,
1269
+ screenshot: () => Effect.succeed(new Uint8Array()),
1270
+ },
1271
+ // Opening an emulator checks its host for ffmpeg's H.264 encoder.
1272
+ run: () => Effect.succeed({ code: 0, stdout: " V....D libx264", stderr: "" }),
1273
+ helpers: { serveSimAxSettings: null, serveSimCli: null },
1274
+ };
1275
+ return {
1276
+ ...host,
1277
+ summary: Effect.succeed({
1278
+ ...host,
1279
+ kind: host.id === LOCAL_DEVICE_HOST_ID ? "local" : "ssh",
1280
+ platforms: [
1281
+ { platform: "ios", available: true },
1282
+ { platform: "android", available: true },
1283
+ ],
1284
+ hubInstalled: true,
1285
+ agentDeviceInstalled: false,
1286
+ }),
1287
+ platformAvailability: (platform) => Effect.succeed({ platform, available: true }),
1288
+ ensureReady: () => Effect.succeed(ready),
1289
+ ensureAgentReady: () => Effect.die("Agent access is not used in this test"),
1290
+ current: Effect.succeed(ready),
1291
+ stopAgent: Effect.void,
1292
+ stop: Effect.void,
1293
+ };
1294
+ };
1295
+ // An Android AVD name, like Pixel_10 here, can exist on two hosts.
1296
+ const withTwoHosts = <A, E>(
1297
+ test: (service: DeviceService.DeviceService["Service"]) => Effect.Effect<A, E>,
1298
+ ) =>
1299
+ Effect.gen(function* () {
1300
+ const service = yield* DeviceService.makeWithHosts(
1301
+ new Map([
1302
+ [thisMachine.id, listingHost(thisMachine, ["Pixel_10"])],
1303
+ [macMini.id, listingHost(macMini, ["MAC-UDID", "Pixel_10"])],
1304
+ ]),
1305
+ ).pipe(Effect.provide(NodeCrypto.layer));
1306
+ yield* service.list;
1307
+ return yield* test(service);
1308
+ }).pipe(Effect.provide(ServerSettings.layerTest({ enableDeviceSupport: true })), Effect.scoped);
1309
+ const open = (
1310
+ service: DeviceService.DeviceService["Service"],
1311
+ hostId: string,
1312
+ deviceId: string,
1313
+ thread = threadId,
1314
+ ) =>
1315
+ service.open({
1316
+ threadId: thread,
1317
+ hostId,
1318
+ deviceId: DeviceId.make(deviceId),
1319
+ platform: deviceId.startsWith("Pixel") ? "android" : "ios",
1320
+ });
1321
+
1322
+ it.effect("finds a device id that exists only on another host", () =>
1323
+ withTwoHosts((service) =>
1324
+ Effect.gen(function* () {
1325
+ const located = yield* service.locateDevice({ deviceId: DeviceId.make("MAC-UDID") });
1326
+ expect(Option.getOrUndefined(located)).toMatchObject({
1327
+ hostId: "mac-mini",
1328
+ id: "MAC-UDID",
1329
+ });
1330
+ }),
1331
+ ),
1332
+ );
1333
+
1334
+ it.effect("refuses a device id that exists on two hosts and names both", () =>
1335
+ withTwoHosts((service) =>
1336
+ Effect.gen(function* () {
1337
+ const error = yield* service
1338
+ .locateDevice({ deviceId: DeviceId.make("Pixel_10") })
1339
+ .pipe(Effect.flip);
1340
+ expect(error).toMatchObject({ _tag: "DeviceHostAmbiguousError", deviceId: "Pixel_10" });
1341
+ expect(error.hosts).toHaveLength(2);
1342
+ expect(error.hosts).toEqual(expect.arrayContaining([thisMachine, macMini]));
1343
+ }),
1344
+ ),
1345
+ );
1346
+
1347
+ it.effect("keeps an explicit hostId and says which host has the device", () =>
1348
+ withTwoHosts((service) =>
1349
+ Effect.gen(function* () {
1350
+ const error = yield* service
1351
+ .locateDevice({ deviceId: DeviceId.make("MAC-UDID"), hostId: LOCAL_DEVICE_HOST_ID })
1352
+ .pipe(Effect.flip);
1353
+ expect(error).toMatchObject({
1354
+ _tag: "DeviceOnOtherHostError",
1355
+ deviceId: "MAC-UDID",
1356
+ host: thisMachine,
1357
+ hosts: [macMini],
1358
+ });
1359
+ const onMac = yield* service.locateDevice({
1360
+ deviceId: DeviceId.make("Pixel_10"),
1361
+ hostId: "mac-mini",
1362
+ });
1363
+ expect(Option.getOrUndefined(onMac)).toMatchObject({ hostId: "mac-mini", id: "Pixel_10" });
1364
+ }),
1365
+ ),
1366
+ );
1367
+
1368
+ it.effect("finds nothing for a device id that no host lists", () =>
1369
+ withTwoHosts((service) =>
1370
+ Effect.gen(function* () {
1371
+ const deviceId = DeviceId.make("Pixel_9");
1372
+ expect(yield* service.locateDevice({ deviceId })).toEqual(Option.none());
1373
+ expect(yield* service.locateDevice({ deviceId, hostId: "mac-mini" })).toEqual(
1374
+ Option.none(),
1375
+ );
1376
+ expect(yield* service.locateDevice({ deviceId, hostId: "unknown-host" })).toEqual(
1377
+ Option.none(),
1378
+ );
1379
+ }),
1380
+ ),
1381
+ );
1382
+
1383
+ it.effect("finds an open device by id on whichever host it is on", () =>
1384
+ withTwoHosts((service) =>
1385
+ Effect.gen(function* () {
1386
+ yield* open(service, "mac-mini", "MAC-UDID");
1387
+ const deviceId = DeviceId.make("MAC-UDID");
1388
+ expect(
1389
+ Option.getOrUndefined(yield* service.locateSession({ threadId, deviceId })),
1390
+ ).toMatchObject({ threadId, hostId: "mac-mini", deviceId });
1391
+ const error = yield* service
1392
+ .locateSession({ threadId, deviceId, hostId: LOCAL_DEVICE_HOST_ID })
1393
+ .pipe(Effect.flip);
1394
+ expect(error).toMatchObject({
1395
+ _tag: "DeviceOnOtherHostError",
1396
+ host: thisMachine,
1397
+ hosts: [macMini],
1398
+ });
1399
+ }),
1400
+ ),
1401
+ );
1402
+
1403
+ it.effect("refuses an id open on two hosts unless the hostId picks one", () =>
1404
+ withTwoHosts((service) =>
1405
+ Effect.gen(function* () {
1406
+ yield* open(service, LOCAL_DEVICE_HOST_ID, "Pixel_10");
1407
+ yield* open(service, "mac-mini", "Pixel_10");
1408
+ const deviceId = DeviceId.make("Pixel_10");
1409
+ const error = yield* service.locateSession({ threadId, deviceId }).pipe(Effect.flip);
1410
+ expect(error).toMatchObject({ _tag: "DeviceHostAmbiguousError", deviceId });
1411
+ expect(error.hosts).toEqual(expect.arrayContaining([thisMachine, macMini]));
1412
+ const onMac = yield* service.locateSession({ threadId, deviceId, hostId: "mac-mini" });
1413
+ expect(Option.getOrUndefined(onMac)).toMatchObject({ hostId: "mac-mini", deviceId });
1414
+ }),
1415
+ ),
1416
+ );
1417
+
1418
+ it.effect("finds no session for a device this thread has not opened", () =>
1419
+ withTwoHosts((service) =>
1420
+ Effect.gen(function* () {
1421
+ const deviceId = DeviceId.make("MAC-UDID");
1422
+ expect(yield* service.locateSession({ threadId, deviceId })).toEqual(Option.none());
1423
+ yield* open(service, "mac-mini", "MAC-UDID", ThreadId.make("thread-other"));
1424
+ expect(yield* service.locateSession({ threadId, deviceId })).toEqual(Option.none());
1425
+ expect(
1426
+ yield* service.locateSession({ threadId, deviceId, hostId: LOCAL_DEVICE_HOST_ID }),
1427
+ ).toEqual(Option.none());
1428
+ }),
1429
+ ),
1430
+ );
1431
+});
apps/server/src/device/DeviceService.ts
+310
-37
@@ -5,8 +5,8 @@ import {
5
type DeviceDetail,
6
type DeviceDetailInput,
7
type DeviceError,
8
- type DeviceHostId,
9
- type DeviceId,
8
+ DeviceHostId,
9
+ DeviceId,
10
DeviceHostUnavailableError,
11
DeviceNotFoundError,
12
DeviceOperationError,
@@ -33,6 +33,12 @@ import * as FileSystem from "effect/FileSystem";
33
import { resolveNodeExecutable, nodeRuntimeUnavailableMessage } from "@t3tools/shared/nodeRuntime";
34
import * as Path from "effect/Path";
35
import { ensureAgentDevice, ensureDeviceHub } from "./DeviceToolchain.ts";
36
+import {
37
+ agentDeviceCloseOutcome,
38
+ bindAgentDeviceLauncher,
39
+ ensureAgentDeviceShim,
40
+ pruneAgentDeviceLaunchers,
41
+} from "./AgentDeviceShim.ts";
42
import * as ServerConfig from "../config.ts";
43
import {
44
agentDeviceConfigPath,
@@ -44,7 +50,9 @@ import * as Crypto from "effect/Crypto";
50
import * as DateTime from "effect/DateTime";
51
import * as Effect from "effect/Effect";
52
import * as Layer from "effect/Layer";
53
+import * as Option from "effect/Option";
54
import * as PubSub from "effect/PubSub";
55
+import * as Schema from "effect/Schema";
56
import * as Scope from "effect/Scope";
57
import * as Semaphore from "effect/Semaphore";
58
import * as Stream from "effect/Stream";
@@ -101,10 +109,30 @@ export interface DeviceAgentReadiness extends DeviceReadiness {
109
readonly agentDevice: DeviceHost.AgentDeviceEndpoint | null;
110
}
111
112
+const DeviceHostName = Schema.Struct({ id: DeviceHostId, label: Schema.optional(Schema.String) });
113
+const hostName = (host: typeof DeviceHostName.Type) => host.label ?? `host ${host.id}`;
114
+
115
+export class DeviceHostAmbiguousError extends Schema.TaggedError<DeviceHostAmbiguousError>()(
116
+ "DeviceHostAmbiguousError",
117
+ { deviceId: DeviceId, hosts: Schema.Array(DeviceHostName) },
118
+) {
119
+ override get message(): string {
120
+ return `Device ${this.deviceId} is on more than one host: ${this.hosts.map(hostName).join(", ")}.`;
121
+ }
122
+}
123
+
124
+export class DeviceOnOtherHostError extends Schema.TaggedError<DeviceOnOtherHostError>()(
125
+ "DeviceOnOtherHostError",
126
+ { deviceId: DeviceId, host: DeviceHostName, hosts: Schema.Array(DeviceHostName) },
127
+) {
128
+ override get message(): string {
129
+ return `Device ${this.deviceId} is not on ${hostName(this.host)}. It is on ${this.hosts.map(hostName).join(", ")}.`;
130
+ }
131
+}
132
+
133
export class DeviceService extends Context.Service<
134
DeviceService,
135
{
107
- readonly agentCli: Effect.Effect<string, DeviceError>;
136
readonly testHost: (
137
config: SshDeviceHostConfig,
138
) => Effect.Effect<DeviceHostSummary, DeviceError>;
@@ -121,9 +149,23 @@ export class DeviceService extends Context.Service<
149
hostId: DeviceHostId;
150
deviceId: DeviceId;
151
}) => Effect.Effect<
124
- { readonly agentDeviceId: string; readonly args: ReadonlyArray<string> },
152
+ {
153
+ readonly agentDeviceId: string;
154
+ readonly session: string;
155
+ readonly args: ReadonlyArray<string>;
156
+ },
157
DeviceError
158
>;
159
+ /**
160
+ * The command agents run for one agent-device session; it is removed when the session ends.
161
+ * None when the session closed before it could be bound.
162
+ */
163
+ readonly agentLauncher: (input: {
164
+ readonly threadId: ThreadId;
165
+ readonly hostId: DeviceHostId;
166
+ readonly deviceId: DeviceId;
167
+ readonly targetArgs: ReadonlyArray<string>;
168
+ }) => Effect.Effect<Option.Option<string>, DeviceError>;
169
readonly state: Effect.Effect<DeviceServiceState>;
170
readonly subscribe: Effect.Effect<PubSub.Subscription<DeviceServiceState>, never, Scope.Scope>;
171
readonly configure: (
@@ -145,6 +187,27 @@ export class DeviceService extends Context.Service<
187
readonly hostId?: DeviceHostId | undefined;
188
readonly deviceId: DeviceId;
189
}) => Effect.Effect<DeviceScreenshot, DeviceError>;
190
+ /**
191
+ * The device an id names in the last listing. Ids are unique per host, not across hosts (an
192
+ * Android AVD name can exist on two), so a hostId decides, and without one the id has to be
193
+ * on a single host.
194
+ */
195
+ readonly locateDevice: (input: {
196
+ readonly hostId?: DeviceHostId | undefined;
197
+ readonly deviceId: DeviceId;
198
+ }) => Effect.Effect<
199
+ Option.Option<DeviceSummary>,
200
+ DeviceHostAmbiguousError | DeviceOnOtherHostError
201
+ >;
202
+ /** As `locateDevice`, among the devices a thread has open. */
203
+ readonly locateSession: (input: {
204
+ readonly threadId: ThreadId;
205
+ readonly hostId?: DeviceHostId | undefined;
206
+ readonly deviceId: DeviceId;
207
+ }) => Effect.Effect<
208
+ Option.Option<DeviceSession>,
209
+ DeviceHostAmbiguousError | DeviceOnOtherHostError
210
+ >;
211
readonly readiness: (hostId?: DeviceHostId) => Effect.Effect<DeviceReadiness, DeviceError>;
212
readonly readinessIfSupported: (
213
hostId?: DeviceHostId,
@@ -161,6 +224,17 @@ interface ServiceState {
224
readonly state: DeviceServiceState;
225
}
226
227
+export interface AgentDeviceLaunchers {
228
+ readonly bind: (input: {
229
+ readonly session: string;
230
+ readonly targetArgs: ReadonlyArray<string>;
231
+ }) => Effect.Effect<string, DeviceError>;
232
+ /** Removes every launcher whose session is not in `live`. */
233
+ readonly prune: (live: ReadonlySet<string>) => Effect.Effect<void>;
234
+ /** Ends the agent-device session behind a launcher, which releases its claim on the device. */
235
+ readonly release?: (launcher: string) => Effect.Effect<void>;
236
+}
237
+
238
export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function* (
239
hosts: ReadonlyMap<DeviceHostId, DeviceHost.DeviceHost["Service"]>,
240
testHost: DeviceService["Service"]["testHost"] = (host) =>
@@ -183,6 +257,7 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
257
}),
258
),
259
installTool?: (tool: "hub" | "agent") => Effect.Effect<unknown, DeviceError>,
260
+ launchers?: AgentDeviceLaunchers,
261
) {
262
const settings = yield* ServerSettings.ServerSettingsService;
263
const crypto = yield* Crypto.Crypto;
@@ -221,11 +296,46 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
296
},
297
});
298
299
+ const launcherLock = yield* Semaphore.make(1);
300
+ /** Launchers bound since startup, by agent-device session. */
301
+ const boundLaunchers = new Map<string, string>();
302
+ // Binding and pruning read sessions under the lock, so neither acts on a session list the other has outdated.
303
+ // A retired session's agent-device session ends before its launcher goes, and a reopen of the same
304
+ // device waits for the lock, so the close cannot end the reopened session.
305
+ const pruneLaunchers = launcherLock.withPermit(
306
+ Effect.gen(function* () {
307
+ if (!launchers) return;
308
+ const { state } = yield* SynchronizedRef.get(stateRef);
309
+ const live = new Set(
310
+ yield* Effect.forEach(state.sessions, (session) =>
311
+ agentDeviceSession(session.threadId, session.hostId, session.deviceId),
312
+ ).pipe(Effect.provideService(Crypto.Crypto, crypto)),
313
+ );
314
+ const retired = [...boundLaunchers].filter(([session]) => !live.has(session));
315
+ for (const [session] of retired) boundLaunchers.delete(session);
316
+ const release = launchers.release;
317
+ if (release)
318
+ yield* Effect.forEach(retired, ([, launcher]) => release(launcher), {
319
+ concurrency: "unbounded",
320
+ discard: true,
321
+ });
322
+ yield* launchers.prune(live);
323
+ }),
324
+ );
325
+
326
+ // Uninterruptible so a committed retirement always prunes, even if its caller is cancelled.
327
const publish = (update: (state: DeviceServiceState) => DeviceServiceState) =>
225
- SynchronizedRef.updateAndGetEffect(stateRef, ({ state }) => {
328
+ SynchronizedRef.modifyEffect(stateRef, ({ state }) => {
329
const next = { ...update(state), revision: state.revision + 1 };
227
- return PubSub.publish(statePubSub, next).pipe(Effect.as({ state: next }));
228
- }).pipe(Effect.map(({ state }) => state));
330
+ const retired = state.sessions.some((session) => !next.sessions.includes(session));
331
+ return PubSub.publish(statePubSub, next).pipe(
332
+ Effect.as([{ next, retired }, { state: next }] as const),
333
+ );
334
+ }).pipe(
335
+ Effect.tap(({ retired }) => (retired ? pruneLaunchers : Effect.void)),
336
+ Effect.map(({ next }) => next),
337
+ Effect.uninterruptible,
338
+ );
339
340
const resolveHost = Effect.fn("DeviceService.resolveHost")(function* (
341
hostId: DeviceHostId | undefined,
@@ -727,9 +837,16 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
837
(input.deviceId === undefined || session.deviceId === input.deviceId),
838
);
839
if (closing.length === 0) return;
840
+ // Powering off ends every session on the device, so all of them retire, and release, while it is on.
841
+ const ending = (session: DeviceSession) =>
842
+ closing.includes(session) ||
843
+ (input.shutdown === true &&
844
+ closing.some(
845
+ (closed) => closed.hostId === session.hostId && closed.deviceId === session.deviceId,
846
+ ));
847
yield* publish((current) => ({
848
...current,
732
- sessions: current.sessions.filter((session) => !closing.includes(session)),
849
+ sessions: current.sessions.filter((session) => !ending(session)),
850
}));
851
if (input.shutdown) {
852
yield* Effect.forEach(
@@ -741,16 +858,18 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
858
},
859
);
860
861
+ // Sessions retire before the power-off, while their agent-device sessions can still close the app;
862
+ // agent-device keeps a claim whose app close fails.
863
const shutdown: DeviceService["Service"]["shutdown"] = Effect.fn("DeviceService.shutdown")(
864
function* (input) {
865
const host = yield* resolveHost(input.hostId);
747
- yield* shutdownDevice(host.id, input.deviceId, input.platform);
866
yield* publish((current) => ({
867
...current,
868
sessions: current.sessions.filter(
869
(session) => !(session.hostId === host.id && session.deviceId === input.deviceId),
870
),
871
}));
872
+ yield* shutdownDevice(host.id, input.deviceId, input.platform);
873
},
874
);
875
@@ -801,6 +920,64 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
920
Effect.map(({ state }) => state.sessions.filter((session) => session.threadId === threadId)),
921
);
922
923
+ const locate = <T extends { readonly hostId: DeviceHostId }>(
924
+ state: DeviceServiceState,
925
+ input: { readonly hostId?: DeviceHostId | undefined; readonly deviceId: DeviceId },
926
+ matches: ReadonlyArray<T>,
927
+ ): Effect.Effect<Option.Option<T>, DeviceHostAmbiguousError | DeviceOnOtherHostError> => {
928
+ const named = (id: DeviceHostId) => ({
929
+ id,
930
+ label: state.hosts.find((host) => host.id === id)?.label,
931
+ });
932
+ const onHost = matches.filter(
933
+ (match) => input.hostId === undefined || match.hostId === input.hostId,
934
+ );
935
+ const hostIds = [...new Set(onHost.map((match) => match.hostId))];
936
+ if (hostIds.length === 1) return Effect.succeedSome(onHost.at(-1)!);
937
+ if (hostIds.length > 1) {
938
+ return Effect.fail(
939
+ new DeviceHostAmbiguousError({ deviceId: input.deviceId, hosts: hostIds.map(named) }),
940
+ );
941
+ }
942
+ const elsewhere = [...new Set(matches.map((match) => match.hostId))];
943
+ return input.hostId !== undefined && elsewhere.length > 0
944
+ ? Effect.fail(
945
+ new DeviceOnOtherHostError({
946
+ deviceId: input.deviceId,
947
+ host: named(input.hostId),
948
+ hosts: elsewhere.map(named),
949
+ }),
950
+ )
951
+ : Effect.succeedNone;
952
+ };
953
+
954
+ const locateDevice: DeviceService["Service"]["locateDevice"] = Effect.fn(
955
+ "DeviceService.locateDevice",
956
+ )(function* (input) {
957
+ const { state } = yield* SynchronizedRef.get(stateRef);
958
+ return yield* locate(
959
+ state,
960
+ input,
961
+ state.devices.filter((device) => device.id === input.deviceId),
962
+ );
963
+ });
964
+
965
+ const locateSession: DeviceService["Service"]["locateSession"] = Effect.fn(
966
+ "DeviceService.locateSession",
967
+ )(function* (input) {
968
+ const { state } = yield* SynchronizedRef.get(stateRef);
969
+ return yield* locate(
970
+ state,
971
+ input,
972
+ state.sessions.filter(
973
+ (session) => session.threadId === input.threadId && session.deviceId === input.deviceId,
974
+ ),
975
+ );
976
+ });
977
+
978
+ // Sessions live in memory, so this removes every launcher a previous run left behind.
979
+ yield* pruneLaunchers;
980
+
981
return {
982
...DeviceService.of({
983
testHost,
@@ -827,12 +1004,6 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
1004
}),
1005
);
1006
}),
830
- agentCli: Effect.fail(
831
- new DeviceHostUnavailableError({
832
- hostId: LOCAL_DEVICE_HOST_ID,
833
- reason: "Agent CLI installation is unavailable in this device service.",
834
- }),
835
- ),
1007
agentTarget: Effect.fn("DeviceService.agentTarget")(function* (input) {
1008
const host = yield* resolveHost(input.hostId);
1009
const ready = yield* agentReadinessIfSupported(input.hostId);
@@ -875,7 +1046,39 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
1046
input.hostId,
1047
input.deviceId,
1048
).pipe(Effect.provideService(Crypto.Crypto, crypto));
878
- return { agentDeviceId, args: ["--config", configPath, "--session", session] };
1049
+ return { agentDeviceId, session, args: ["--config", configPath, "--session", session] };
1050
+ }),
1051
+ agentLauncher: Effect.fn("DeviceService.agentLauncher")(function* ({
1052
+ targetArgs,
1053
+ ...target
1054
+ }) {
1055
+ if (!launchers)
1056
+ return yield* new DeviceHostUnavailableError({
1057
+ hostId: target.hostId,
1058
+ reason: "Agent launchers are unavailable in this device service.",
1059
+ });
1060
+ const session = yield* agentDeviceSession(
1061
+ target.threadId,
1062
+ target.hostId,
1063
+ target.deviceId,
1064
+ ).pipe(Effect.provideService(Crypto.Crypto, crypto));
1065
+ return yield* launcherLock.withPermit(
1066
+ Effect.gen(function* () {
1067
+ const { state } = yield* SynchronizedRef.get(stateRef);
1068
+ if (
1069
+ !state.sessions.some(
1070
+ (live) =>
1071
+ live.threadId === target.threadId &&
1072
+ live.hostId === target.hostId &&
1073
+ live.deviceId === target.deviceId,
1074
+ )
1075
+ )
1076
+ return Option.none();
1077
+ const launcher = yield* launchers.bind({ session, targetArgs });
1078
+ boundLaunchers.set(session, launcher);
1079
+ return Option.some(launcher);
1080
+ }),
1081
+ );
1082
}),
1083
state: SynchronizedRef.get(stateRef).pipe(Effect.map(({ state }) => state)),
1084
subscribe: PubSub.subscribe(statePubSub),
@@ -887,6 +1090,8 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
1090
detail,
1091
action,
1092
screenshot,
1093
+ locateDevice,
1094
+ locateSession,
1095
readiness,
1096
readinessIfSupported,
1097
agentReadinessIfSupported,
@@ -952,6 +1157,94 @@ export const make = Effect.gen(function* () {
1157
}),
1158
),
1159
);
1160
+ const agentCli = resolveNodeExecutable("Device automation").pipe(
1161
+ Effect.andThen(ensureAgentDevice(config.baseDir)),
1162
+ Effect.provideService(FileSystem.FileSystem, fs),
1163
+ Effect.provideService(Path.Path, path),
1164
+ Effect.provideService(ProcessRunner.ProcessRunner, runner),
1165
+ Effect.map((tool) => tool.entryPath),
1166
+ Effect.mapError((error) =>
1167
+ error._tag === "NodeRuntimeUnavailableError"
1168
+ ? new DeviceHostUnavailableError({
1169
+ hostId: LOCAL_DEVICE_HOST_ID,
1170
+ hostLabel: LOCAL_DEVICE_HOST_LABEL,
1171
+ reason: nodeRuntimeUnavailableMessage("Device automation"),
1172
+ cause: error,
1173
+ })
1174
+ : new DeviceOperationError({
1175
+ operation: "install agent CLI",
1176
+ reason: "command_failed",
1177
+ cause: error,
1178
+ }),
1179
+ ),
1180
+ );
1181
+ const launchers: AgentDeviceLaunchers = {
1182
+ bind: Effect.fn("DeviceService.bindLauncher")(
1183
+ function* (input) {
1184
+ const entryPath = yield* agentCli;
1185
+ // The unbound launcher stays current for agents that still call it with flags.
1186
+ yield* ensureAgentDeviceShim({ entryPath, stateDir: config.stateDir });
1187
+ return yield* bindAgentDeviceLauncher({ entryPath, stateDir: config.stateDir, ...input });
1188
+ },
1189
+ Effect.provideService(FileSystem.FileSystem, fs),
1190
+ Effect.provideService(Path.Path, path),
1191
+ Effect.catchTags({
1192
+ NodeRuntimeUnavailableError: (cause) =>
1193
+ Effect.fail(
1194
+ new DeviceHostUnavailableError({
1195
+ hostId: LOCAL_DEVICE_HOST_ID,
1196
+ hostLabel: LOCAL_DEVICE_HOST_LABEL,
1197
+ reason: nodeRuntimeUnavailableMessage("Device automation"),
1198
+ cause,
1199
+ }),
1200
+ ),
1201
+ PlatformError: (cause) =>
1202
+ Effect.fail(
1203
+ new DeviceHostUnavailableError({
1204
+ hostId: LOCAL_DEVICE_HOST_ID,
1205
+ hostLabel: LOCAL_DEVICE_HOST_LABEL,
1206
+ reason: "Could not prepare the agent-device launcher.",
1207
+ cause,
1208
+ }),
1209
+ ),
1210
+ }),
1211
+ ),
1212
+ prune: (live) =>
1213
+ pruneAgentDeviceLaunchers({ stateDir: config.stateDir, live }).pipe(
1214
+ Effect.provideService(FileSystem.FileSystem, fs),
1215
+ Effect.provideService(Path.Path, path),
1216
+ ),
1217
+ // Best effort: an unreachable host fails fast in the launcher's connection check, and the
1218
+ // launcher goes either way. Only a failed or timed-out close can leave the device claimed.
1219
+ release: (launcher) =>
1220
+ resolveNodeExecutable("Device automation").pipe(
1221
+ Effect.flatMap((node) =>
1222
+ runner.run({
1223
+ command: node,
1224
+ args: [path.join(path.dirname(launcher), "agent-device-launcher.mjs"), "close"],
1225
+ env: { ...process.env, ELECTRON_RUN_AS_NODE: "1" },
1226
+ timeout: "15 seconds",
1227
+ timeoutBehavior: "timedOutResult",
1228
+ }),
1229
+ ),
1230
+ Effect.provideService(FileSystem.FileSystem, fs),
1231
+ Effect.provideService(Path.Path, path),
1232
+ Effect.flatMap((result) => {
1233
+ const outcome = agentDeviceCloseOutcome(result);
1234
+ return outcome === "failed" || outcome === "timed-out"
1235
+ ? Effect.logWarning("Could not end the agent-device session", {
1236
+ launcher,
1237
+ outcome,
1238
+ stderr: result.stderr.slice(-500),
1239
+ })
1240
+ : Effect.void;
1241
+ }),
1242
+ Effect.tapError((cause) =>
1243
+ Effect.logWarning("Could not end the agent-device session", { launcher, cause }),
1244
+ ),
1245
+ Effect.ignore,
1246
+ ),
1247
+ };
1248
const probeContext =
1249
yield* Effect.context<Effect.Services<ReturnType<typeof SshDeviceHost.probe>>>();
1250
const localTargetContext =
@@ -991,6 +1284,7 @@ export const make = Effect.gen(function* () {
1284
}),
1285
),
1286
),
1287
+ launchers,
1288
);
1289
const hostContext =
1290
yield* Effect.context<Effect.Services<ReturnType<typeof SshDeviceHost.make>>>();
@@ -1132,27 +1426,6 @@ export const make = Effect.gen(function* () {
1426
return {
1427
...service,
1428
easAccount,
1135
- agentCli: resolveNodeExecutable("Device automation").pipe(
1136
- Effect.andThen(ensureAgentDevice(config.baseDir)),
1137
- Effect.provideService(FileSystem.FileSystem, fs),
1138
- Effect.provideService(Path.Path, path),
1139
- Effect.provideService(ProcessRunner.ProcessRunner, runner),
1140
- Effect.map((tool) => tool.entryPath),
1141
- Effect.mapError((error) =>
1142
- error._tag === "NodeRuntimeUnavailableError"
1143
- ? new DeviceHostUnavailableError({
1144
- hostId: LOCAL_DEVICE_HOST_ID,
1145
- hostLabel: LOCAL_DEVICE_HOST_LABEL,
1146
- reason: nodeRuntimeUnavailableMessage("Device automation"),
1147
- cause: error,
1148
- })
1149
- : new DeviceOperationError({
1150
- operation: "install agent CLI",
1151
- reason: "command_failed",
1152
- cause: error,
1153
- }),
1154
- ),
1155
- ),
1429
};
1430
});
1431
apps/server/src/mcp/McpDeviceToolkit.test.ts
+388
-16
@@ -1,4 +1,4 @@
1
-import { expect, it } from "@effect/vitest";
1
+import { describe, expect, it } from "@effect/vitest";
2
import * as NodeServices from "@effect/platform-node/NodeServices";
3
import {
4
DeviceHostUnavailableError,
@@ -9,6 +9,7 @@ import {
9
} from "@t3tools/contracts";
10
import * as Effect from "effect/Effect";
11
import * as Layer from "effect/Layer";
12
+import * as Option from "effect/Option";
13
import { McpSchema, McpServer } from "effect/ai";
14
15
import * as ServerConfig from "../config.ts";
@@ -104,6 +105,13 @@ const layerProjectsMock = Layer.mock(ProjectService.ProjectService)({
105
getById: () => Effect.succeedNone,
106
});
107
108
+const openSession = {
109
+ threadId,
110
+ hostId: "local",
111
+ deviceId: DeviceId.make("UDID-1"),
112
+ platform: "ios" as const,
113
+ openedAt: "2026-09-08T00:00:00.000Z",
114
+};
115
const layerDeviceServiceMock = Layer.mock(DeviceService.DeviceService)({
116
state: Effect.succeed(state),
117
list: Effect.succeed(state),
@@ -117,30 +125,25 @@ const layerDeviceServiceMock = Layer.mock(DeviceService.DeviceService)({
125
openedAt: "2026-09-08T00:00:00.000Z",
126
}),
127
120
- sessionsForThread: (id) =>
128
+ sessionsForThread: (id) => Effect.succeed(id === threadId ? [openSession] : []),
129
+ locateSession: (input) =>
130
Effect.succeed(
122
- id === threadId
123
- ? [
124
- {
125
- threadId,
126
- hostId: "local",
127
- deviceId: DeviceId.make("UDID-1"),
128
- platform: "ios" as const,
129
- openedAt: "2026-09-08T00:00:00.000Z",
130
- },
131
- ]
132
- : [],
131
+ input.threadId === threadId && input.deviceId === openSession.deviceId
132
+ ? Option.some(openSession)
133
+ : Option.none(),
134
),
135
screenshot: () => Effect.succeed({ device, png }),
136
close: () => Effect.void,
136
- agentCli: Effect.succeed("/cli"),
137
testHost: () => Effect.die("not used"),
138
// As for an EAS device, agent-device knows the device by a different id than T3.
139
agentTarget: () =>
140
Effect.succeed({
141
agentDeviceId: "SIM-UDID",
142
+ session: "thread-device",
143
args: ["--config", "/host.json", "--session", "thread-device"],
144
}),
145
+ agentLauncher: ({ targetArgs }) =>
146
+ Effect.succeedSome(`/state/device/targets/thread-device/${targetArgs.join("_")}/agent-device`),
147
});
148
149
const layerTest = McpHttpServer.layerDeviceToolkit.pipe(
@@ -166,8 +169,31 @@ it.effect("registers the device tools and returns the screenshot as image conten
169
.callTool({ name: "device_open", arguments: { platform: "ios" } })
170
.pipe(callWith(["device"]), Effect.provideService(McpSchema.McpServerClient, client));
171
expect(opened.isError).toBe(false);
169
- const openedContent = opened.structuredContent as { quickStart: string };
170
- expect(openedContent.quickStart).toContain("--udid SIM-UDID");
172
+ const openedContent = opened.structuredContent as {
173
+ agentDevice: { command: string; targetArgs: ReadonlyArray<string>; session: string };
174
+ quickStart: string;
175
+ };
176
+ // Callers that pass the target flags, like test-t3-mobile's pair-client.sh, keep working.
177
+ expect(openedContent.agentDevice).toMatchObject({
178
+ targetArgs: [
179
+ "--platform",
180
+ "ios",
181
+ "--udid",
182
+ "SIM-UDID",
183
+ "--config",
184
+ "/host.json",
185
+ "--session",
186
+ "thread-device",
187
+ ],
188
+ session: "thread-device",
189
+ });
190
+ expect(openedContent.quickStart).toContain(
191
+ `${openedContent.agentDevice.command} snapshot -i`,
192
+ );
193
+ // The launcher selects the device by agent-device's id for it, not T3's.
194
+ expect(openedContent.agentDevice.command).toBe(
195
+ "/state/device/targets/thread-device/--platform_ios_--udid_SIM-UDID_--config_/host.json_--session_thread-device/agent-device",
196
+ );
197
198
const shot = yield* server
199
.callTool({ name: "device_screenshot", arguments: { deviceId: "UDID-1" } })
@@ -188,6 +214,14 @@ it.effect("registers the device tools and returns the screenshot as image conten
214
.callTool({ name: "device_list", arguments: {} })
215
.pipe(callWith(["preview"]), Effect.provideService(McpSchema.McpServerClient, client));
216
expect(denied.isError).toBe(true);
217
+ // The agent can't see Settings, and a running session keeps the capabilities it started with,
218
+ // so the error says where the user turns access on and when it applies.
219
+ expect(denied.content).toEqual([
220
+ {
221
+ type: "text",
222
+ text: "Agent device access is turned off for this environment. Ask the user to turn on Agent device access in Settings > Integrations > Devices; it applies when the agent session next starts, such as in a new thread.",
223
+ },
224
+ ]);
225
}),
226
).pipe(Effect.provide(layerTest)),
227
);
@@ -234,3 +268,341 @@ it.effect("rejects unavailable agent access before booting or opening a device",
268
),
269
);
270
});
271
+
272
+describe("device targeting across hosts", () => {
273
+ const macHost = {
274
+ id: "mac-mini",
275
+ kind: "ssh" as const,
276
+ label: "Mac Mini",
277
+ platforms: [
278
+ { platform: "ios" as const, available: true },
279
+ { platform: "android" as const, available: true },
280
+ ],
281
+ hubInstalled: true,
282
+ agentDeviceInstalled: true,
283
+ };
284
+ const macIphone = { ...device, hostId: "mac-mini", id: "MAC-UDID" };
285
+ const localPixel = {
286
+ hostId: "local",
287
+ id: "Pixel_10",
288
+ platform: "android" as const,
289
+ name: "Pixel 10",
290
+ version: "Android 16",
291
+ booted: false,
292
+ physical: false,
293
+ };
294
+ const macPixel = { ...localPixel, hostId: "mac-mini" };
295
+ const multiHostState = {
296
+ ...state,
297
+ hosts: [...state.hosts, macHost],
298
+ hostStatuses: {
299
+ local: { status: "ready" as const },
300
+ "mac-mini": { status: "ready" as const },
301
+ },
302
+ devices: [device, macIphone, localPixel, macPixel],
303
+ };
304
+ const session = (hostId: string, deviceId: string, platform: "ios" | "android") => ({
305
+ threadId,
306
+ hostId,
307
+ deviceId: DeviceId.make(deviceId),
308
+ platform,
309
+ openedAt: "2026-09-08T00:00:00.000Z",
310
+ });
311
+ const thisMachine = { id: "local", label: "This machine" };
312
+ const macMini = { id: macHost.id, label: macHost.label };
313
+ // DeviceService's lookup errors; DeviceService.test.ts covers when each arises.
314
+ const onTwoHosts = new DeviceService.DeviceHostAmbiguousError({
315
+ deviceId: DeviceId.make("Pixel_10"),
316
+ hosts: [thisMachine, macMini],
317
+ });
318
+ const onTheMac = new DeviceService.DeviceOnOtherHostError({
319
+ deviceId: DeviceId.make("MAC-UDID"),
320
+ host: thisMachine,
321
+ hosts: [macMini],
322
+ });
323
+
324
+ const run = <A, E>(
325
+ sessions: ReadonlyArray<ReturnType<typeof session>>,
326
+ program: (calls: {
327
+ readonly opened: Array<{ hostId: string; deviceId: string }>;
328
+ readonly closed: Array<{ hostId?: string | undefined; deviceId?: string | undefined }>;
329
+ readonly call: (
330
+ name: string,
331
+ args: Record<string, unknown>,
332
+ ) => Effect.Effect<
333
+ McpSchema.CallToolResult,
334
+ McpSchema.InternalError | McpSchema.InvalidParams,
335
+ McpServer.McpServer
336
+ >;
337
+ }) => Effect.Effect<A, E, McpServer.McpServer>,
338
+ overrides: Partial<DeviceService.DeviceService["Service"]> = {},
339
+ ) => {
340
+ const opened: Array<{ hostId: string; deviceId: string }> = [];
341
+ const closed: Array<{ hostId?: string | undefined; deviceId?: string | undefined }> = [];
342
+ const layerDevices = Layer.mock(DeviceService.DeviceService)({
343
+ state: Effect.succeed(multiHostState),
344
+ list: Effect.succeed(multiHostState),
345
+ agentReadinessIfSupported: () => Effect.succeed(readiness),
346
+ open: (input) =>
347
+ Effect.sync(() => {
348
+ opened.push({ hostId: input.hostId ?? "local", deviceId: input.deviceId });
349
+ return session(input.hostId ?? "local", input.deviceId, input.platform);
350
+ }),
351
+ sessionsForThread: () => Effect.succeed(sessions),
352
+ locateDevice: (input) =>
353
+ Effect.succeed(
354
+ Option.fromUndefinedOr(
355
+ multiHostState.devices.find(
356
+ (candidate) =>
357
+ candidate.id === input.deviceId &&
358
+ (input.hostId === undefined || candidate.hostId === input.hostId),
359
+ ),
360
+ ),
361
+ ),
362
+ locateSession: (input) =>
363
+ Effect.succeed(
364
+ Option.fromUndefinedOr(
365
+ sessions.find(
366
+ (candidate) =>
367
+ candidate.deviceId === input.deviceId &&
368
+ (input.hostId === undefined || candidate.hostId === input.hostId),
369
+ ),
370
+ ),
371
+ ),
372
+ screenshot: (target) =>
373
+ Effect.succeed({
374
+ device:
375
+ multiHostState.devices.find(
376
+ (candidate) => candidate.hostId === target.hostId && candidate.id === target.deviceId,
377
+ ) ?? device,
378
+ png,
379
+ }),
380
+ close: (input) =>
381
+ Effect.sync(() => {
382
+ closed.push({ hostId: input.hostId, deviceId: input.deviceId });
383
+ }),
384
+ agentTarget: () =>
385
+ Effect.succeed({
386
+ agentDeviceId: "MAC-UDID",
387
+ session: "thread-device",
388
+ args: ["--config", "/mac.json", "--session", "thread-device"],
389
+ }),
390
+ agentLauncher: () => Effect.succeedSome("/state/device/targets/thread-device/agent-device"),
391
+ ...overrides,
392
+ });
393
+ const call = (name: string, args: Record<string, unknown>) =>
394
+ McpServer.McpServer.pipe(
395
+ Effect.flatMap((server) => server.callTool({ name, arguments: args })),
396
+ Effect.provideService(McpInvocationContext.McpInvocationContext, invocation(["device"])),
397
+ Effect.provideService(McpSchema.McpServerClient, client),
398
+ );
399
+ return program({ opened, closed, call }).pipe(
400
+ Effect.scoped,
401
+ Effect.provide(
402
+ McpHttpServer.layerDeviceToolkit.pipe(
403
+ Layer.provideMerge(McpServer.McpServer.layer),
404
+ Layer.provideMerge(McpToolAccessTestkit.liveThreadsLayer),
405
+ Layer.provide(layerDevices),
406
+ Layer.provide(layerProjectsMock),
407
+ Layer.provide(
408
+ ServerConfig.layerTest(process.cwd(), { prefix: "t3-mcp-device-toolkit-test-" }),
409
+ ),
410
+ Layer.provide(NodeServices.layer),
411
+ ),
412
+ ),
413
+ );
414
+ };
415
+ const text = (result: McpSchema.CallToolResult) =>
416
+ result.content.flatMap((entry) => (entry.type === "text" ? [entry.text] : [])).join("\n");
417
+
418
+ it.effect("opens a device id that exists only on another host", () =>
419
+ run([], ({ opened, call }) =>
420
+ Effect.gen(function* () {
421
+ const result = yield* call("device_open", { deviceId: "MAC-UDID" });
422
+ expect(text(result)).not.toContain("No device");
423
+ expect(result.isError).toBe(false);
424
+ expect(opened).toEqual([{ hostId: "mac-mini", deviceId: "MAC-UDID" }]);
425
+ }),
426
+ ),
427
+ );
428
+
429
+ it.effect("binds the launcher to the id the device booted with", () => {
430
+ const targets: Array<string> = [];
431
+ return run(
432
+ [],
433
+ ({ call }) =>
434
+ Effect.gen(function* () {
435
+ const result = yield* call("device_open", { deviceId: "Pixel_10", hostId: "mac-mini" });
436
+ expect(result.isError).toBe(false);
437
+ expect(targets).toEqual(["emulator-5554", "emulator-5554"]);
438
+ }),
439
+ {
440
+ open: (input) =>
441
+ Effect.succeed(session(input.hostId ?? "local", "emulator-5554", "android")),
442
+ agentTarget: (target) =>
443
+ Effect.sync(() => {
444
+ targets.push(target.deviceId);
445
+ return { agentDeviceId: target.deviceId, session: "thread-device", args: [] };
446
+ }),
447
+ agentLauncher: (target) =>
448
+ Effect.sync(() => {
449
+ targets.push(target.deviceId);
450
+ return Option.some("/state/device/targets/thread-device/agent-device");
451
+ }),
452
+ },
453
+ );
454
+ });
455
+
456
+ it.effect("says a device closed during device_open was closed, not that its host is down", () =>
457
+ run(
458
+ [],
459
+ ({ call }) =>
460
+ Effect.gen(function* () {
461
+ const result = yield* call("device_open", { deviceId: "MAC-UDID" });
462
+ expect(result.isError).toBe(true);
463
+ expect(text(result)).toBe(
464
+ "The device was closed while device_open was preparing it. Call device_open again only if you still need it.",
465
+ );
466
+ }),
467
+ { agentLauncher: () => Effect.succeedNone },
468
+ ),
469
+ );
470
+
471
+ it.effect("refuses a device id that exists on two hosts and names both", () =>
472
+ run(
473
+ [],
474
+ ({ opened, call }) =>
475
+ Effect.gen(function* () {
476
+ const result = yield* call("device_open", { deviceId: "Pixel_10" });
477
+ expect(result.isError).toBe(true);
478
+ expect(text(result)).toContain("hostId local");
479
+ expect(text(result)).toContain("hostId mac-mini");
480
+ expect(text(result)).toBe(
481
+ "Device Pixel_10 is on more than one host: 'This machine' (hostId local), 'Mac Mini' (hostId mac-mini). Pass hostId.",
482
+ );
483
+ expect(opened).toEqual([]);
484
+ }),
485
+ { locateDevice: () => Effect.fail(onTwoHosts) },
486
+ ),
487
+ );
488
+
489
+ it.effect("keeps an explicit hostId and says which host has the device", () =>
490
+ run(
491
+ [],
492
+ ({ opened, call }) =>
493
+ Effect.gen(function* () {
494
+ const result = yield* call("device_open", { deviceId: "MAC-UDID", hostId: "local" });
495
+ expect(result.isError).toBe(true);
496
+ expect(text(result)).toContain("hostId mac-mini");
497
+ expect(text(result)).toBe(
498
+ "Device MAC-UDID is not on 'This machine' (hostId local). It is on 'Mac Mini' (hostId mac-mini); pass that hostId.",
499
+ );
500
+ expect(opened).toEqual([]);
501
+ }),
502
+ { locateDevice: () => Effect.fail(onTheMac) },
503
+ ),
504
+ );
505
+
506
+ it.effect("says no host has a device id, naming the host it was asked on", () =>
507
+ run([], ({ opened, call }) =>
508
+ Effect.gen(function* () {
509
+ const missing = (args: Record<string, unknown>) =>
510
+ call("device_open", { deviceId: "Pixel_9", ...args }).pipe(Effect.map(text));
511
+ expect(yield* missing({})).toBe(
512
+ "No device Pixel_9 on any host. Call device_list for current ids.",
513
+ );
514
+ expect(yield* missing({ hostId: "mac-mini" })).toBe(
515
+ "No device Pixel_9 on 'Mac Mini' (hostId mac-mini). Call device_list for current ids.",
516
+ );
517
+ expect(yield* missing({ hostId: "unknown-host" })).toBe(
518
+ "No device Pixel_9 on hostId unknown-host. Call device_list for current ids.",
519
+ );
520
+ expect(opened).toEqual([]);
521
+ }),
522
+ ),
523
+ );
524
+
525
+ it.effect("screenshots an open device by id on whichever host it is on", () =>
526
+ run([session("mac-mini", "MAC-UDID", "ios")], ({ call }) =>
527
+ Effect.gen(function* () {
528
+ const result = yield* call("device_screenshot", { deviceId: "MAC-UDID" });
529
+ expect(result.isError).toBe(false);
530
+ expect(result.structuredContent).toMatchObject({ device: { hostId: "mac-mini" } });
531
+ }),
532
+ ),
533
+ );
534
+
535
+ it.effect("says why device_screenshot failed instead of a generic error", () =>
536
+ run(
537
+ [session("mac-mini", "MAC-UDID", "ios")],
538
+ ({ call }) =>
539
+ Effect.gen(function* () {
540
+ const wrongHost = yield* call("device_screenshot", {
541
+ deviceId: "MAC-UDID",
542
+ hostId: "local",
543
+ });
544
+ expect(wrongHost.isError).toBe(true);
545
+ expect(text(wrongHost)).toContain("It is on 'Mac Mini' (hostId mac-mini)");
546
+ expect(text(wrongHost)).toBe(
547
+ "Device MAC-UDID is not on 'This machine' (hostId local). It is on 'Mac Mini' (hostId mac-mini); pass that hostId.",
548
+ );
549
+ }),
550
+ { locateSession: () => Effect.fail(onTheMac) },
551
+ ),
552
+ );
553
+
554
+ it.effect("tells an agent to open a device id before screenshotting it", () =>
555
+ run([], ({ call }) =>
556
+ Effect.gen(function* () {
557
+ const result = yield* call("device_screenshot", { deviceId: "MAC-UDID" });
558
+ expect(result.isError).toBe(true);
559
+ expect(text(result)).toBe(
560
+ "Device MAC-UDID is not open in this thread. Call device_open first.",
561
+ );
562
+ }),
563
+ ),
564
+ );
565
+
566
+ it.effect("tells an agent with no open device to call device_open before a screenshot", () =>
567
+ run([], ({ call }) =>
568
+ Effect.gen(function* () {
569
+ const result = yield* call("device_screenshot", {});
570
+ expect(result.isError).toBe(true);
571
+ expect(text(result)).toBe("No device is open in this thread. Call device_open first.");
572
+ expect(result.structuredContent).toMatchObject({
573
+ error: { _tag: "DeviceToolUnavailableError" },
574
+ });
575
+ }),
576
+ ),
577
+ );
578
+
579
+ it.effect("refuses to close an id open on two hosts instead of closing both", () =>
580
+ run(
581
+ [session("local", "Pixel_10", "android"), session("mac-mini", "Pixel_10", "android")],
582
+ ({ closed, call }) =>
583
+ Effect.gen(function* () {
584
+ const result = yield* call("device_close", { deviceId: "Pixel_10" });
585
+ expect(result.isError).toBe(true);
586
+ expect(text(result)).toContain("hostId mac-mini");
587
+ expect(text(result)).toBe(
588
+ "Device Pixel_10 is on more than one host: 'This machine' (hostId local), 'Mac Mini' (hostId mac-mini). Pass hostId.",
589
+ );
590
+ expect(closed).toEqual([]);
591
+ }),
592
+ { locateSession: () => Effect.fail(onTwoHosts) },
593
+ ),
594
+ );
595
+
596
+ it.effect("closes an open device on its host and treats an unopened one as closed", () =>
597
+ run([session("mac-mini", "MAC-UDID", "ios")], ({ closed, call }) =>
598
+ Effect.gen(function* () {
599
+ expect((yield* call("device_close", { deviceId: "MAC-UDID" })).isError).toBe(false);
600
+ expect((yield* call("device_close", { deviceId: "Pixel_9" })).isError).toBe(false);
601
+ expect(closed).toEqual([
602
+ { hostId: "mac-mini", deviceId: "MAC-UDID" },
603
+ { hostId: undefined, deviceId: "Pixel_9" },
604
+ ]);
605
+ }),
606
+ ),
607
+ );
608
+});
apps/server/src/mcp/McpHttpServer.ts
+6
-1
@@ -14,6 +14,7 @@ import type * as Types from "effect/Types";
14
import { AiError, McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
15
import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
16
import {
17
+ DeviceToolError,
18
OrchestratorMcpFailure,
19
PreviewAutomationError,
20
ProviderInteractionMode,
@@ -765,11 +766,15 @@ const registerDeviceScreenshot = Effect.fn("McpHttpServer.registerDeviceScreensh
766
Effect.provideService(ThreadManagementService.ThreadManagementService, threads),
767
),
768
"screenshot",
768
- "Device screenshot failed.",
769
+ (error) =>
770
+ isDeviceToolError(error) || isOrchestratorMcpFailure(error)
771
+ ? error.message
772
+ : "Device screenshot failed.",
773
);
774
});
775
776
const isOrchestratorMcpFailure = Schema.is(OrchestratorMcpFailure);
777
+const isDeviceToolError = Schema.is(DeviceToolError);
778
779
const registerHtmlPreview = Effect.fn("McpHttpServer.registerHtmlPreview")(function* () {
780
const htmlRender = yield* HtmlRender.HtmlRender;
apps/server/src/mcp/toolkits/device/handlers.test.ts
+28
@@ -26,6 +26,34 @@ describe("device tool helpers", () => {
26
expect(text).not.toContain("is on PATH");
27
});
28
29
+ it("shows a bound launcher's commands without flags and keeps device actions off simctl and ssh", () => {
30
+ const command = "/state/device/targets/t3-a/agent-device";
31
+ const text = agentDeviceQuickStart(device, [], command);
32
+ const examples = text.split("\n").filter((line) => line.trimStart().startsWith(command));
33
+ expect(examples).toContain(` ${command} snapshot -i # accessibility tree with @eN refs`);
34
+ expect(examples.find((line) => line.includes(" screenshot "))).toContain("--pixel-density <n>");
35
+ expect(agentDeviceQuickStart({ ...device, platform: "android" }, [], command)).not.toContain(
36
+ "--pixel-density",
37
+ );
38
+ expect(examples.join("\n")).not.toMatch(/--(?:platform|udid|serial|config|session)\b/);
39
+ expect(text).not.toContain("remain available");
40
+ expect(text).toContain("Do not use simctl, idb, adb or ssh for those actions.");
41
+ expect(text).toContain("If it is missing, call device_open again.");
42
+ });
43
+
44
+ it("opens the app before snapshots, CLI screenshots or input, looks with device_screenshot, and records the device screen", () => {
45
+ const command = "/state/device/targets/t3-a/agent-device";
46
+ const text = agentDeviceQuickStart(device, [], command);
47
+ // device_open starts no agent-device session, and an iOS snapshot needs one with an app.
48
+ expect(text).toContain(
49
+ "Run open <bundle-or-package-id> (apps lists them) before snapshots, CLI screenshots or input; it starts the session they need. Use device_screenshot just to look.",
50
+ );
51
+ // App-scoped recording needs an app opened in the session; device scope does not.
52
+ expect(text).toContain(
53
+ ` ${command} record start --scope device /tmp/run.mp4 # then record stop`,
54
+ );
55
+ });
56
+
57
it("reads PNG dimensions from the IHDR chunk", () => {
58
const png = new Uint8Array(24);
59
new DataView(png.buffer).setUint32(0, 0x89504e47);
apps/server/src/mcp/toolkits/device/handlers.ts
+113
-76
@@ -1,6 +1,7 @@
1
import {
2
type DeviceError,
3
type DeviceHostId,
4
+ type DeviceHostSummary,
5
type DeviceId,
6
type DevicePlatform,
7
type DeviceSummary,
@@ -8,12 +9,7 @@ import {
9
LOCAL_DEVICE_HOST_ID,
10
} from "@t3tools/contracts";
11
import * as Effect from "effect/Effect";
11
-import * as Path from "effect/Path";
12
-import * as HostProcess from "@t3tools/shared/HostProcess";
13
-import * as ServerConfig from "../../../config.ts";
14
-import { ensureAgentDeviceShim } from "../../../device/AgentDeviceShim.ts";
15
-import { nodeRuntimeUnavailableMessage } from "@t3tools/shared/nodeRuntime";
16
-
12
+import * as Option from "effect/Option";
13
import * as DeviceService from "../../../device/DeviceService.ts";
14
import { threadWorkspaceRoot } from "../../../project/threadWorkspaceRoot.ts";
15
import * as McpInvocationContext from "../../McpInvocationContext.ts";
@@ -26,20 +22,19 @@ function agentDeviceTargetArgs(device: DeviceSummary): ReadonlyArray<string> {
22
: ["--platform", "android", "--serial", device.id];
23
}
24
25
+const shellWord = (value: string) =>
26
+ /^[a-zA-Z0-9_./:-]+$/.test(value) ? value : "'" + value.replaceAll("'", "'\"'\"'") + "'";
27
+
28
+/** `targetArgs` are the flags the command still needs; a bound launcher needs none. */
29
export function agentDeviceQuickStart(
30
device: DeviceSummary,
31
targetArgs = agentDeviceTargetArgs(device),
32
command = "agent-device",
33
cloud = false,
34
): string {
35
- const executable = /^[a-zA-Z0-9_./:-]+$/.test(command)
36
- ? command
37
- : "'" + command.replaceAll("'", "'\"'\"'") + "'";
38
- const target = targetArgs
39
- .map((arg) =>
40
- /^[a-zA-Z0-9_./:-]+$/.test(arg) ? arg : "'" + arg.replaceAll("'", "'\"'\"'") + "'",
41
- )
42
- .join(" ");
35
+ const executable = shellWord(command);
36
+ const target = targetArgs.map(shellWord).join(" ");
37
+ const run = (args: string) => [executable, args, target].filter(Boolean).join(" ");
38
const platformNotes = cloud
39
? "This is an EAS Simulator session in the cloud. It bills the Expo account per minute until it stops, so call device_close with shutdown: true when you are done. It starts with no apps installed: install-from-source <url> installs a build from a URL (iOS needs a .tar.gz containing a .app), and install uploads one from this machine."
40
: device.platform === "ios"
@@ -47,18 +42,31 @@ export function agentDeviceQuickStart(
42
: "The Android snapshot helper installs itself on first use.";
43
return [
44
`The user is watching ${device.name} (${device.version}) in the Device panel.`,
50
- `Drive it with ${executable}. Use this exact executable path; login shells may reset PATH. Always pass ${target}.`,
51
- "Typical loop:",
52
- ` ${executable} open <bundle-or-package-id> ${target} # or: open <app> <deep-link-url>`,
53
- ` ${executable} snapshot -i ${target} # accessibility tree with @eN refs`,
54
- ` ${executable} click @e3 ${target}`,
55
- ` ${executable} fill @e5 "text" ${target}`,
56
- ` ${executable} screenshot /tmp/shot.png ${target} # or call device_screenshot`,
57
- ` ${executable} install <app> <path-to-.app-or-.apk> ${target}`,
58
- `Prefer snapshot refs over coordinates. Run ${executable} help for workflow guides and ${executable} <command> --help for flags.`,
59
- "Prefer agent-device for driving this device. simctl, adb, and xcrun remain available for anything it does not cover.",
60
- "For remote hosts, arrange builds, app installation, and any Metro reverse forwarding yourself. T3 provides discovery, streaming, and control only.",
61
- "Keep the returned --config and --session flags on every command. Other hosts can be used concurrently; opening one does not switch these commands.",
45
+ target === ""
46
+ ? `Drive it with ${executable}. It is bound to this device and session, so it needs no --platform, --udid, --serial, --config or --session flags. Use this exact path; login shells may reset PATH.`
47
+ : `Drive it with ${executable}. Use this exact path; login shells may reset PATH. Always pass ${target}.`,
48
+ // Screenshots and input need the session agent-device's open starts, and an iOS snapshot also
49
+ // needs its app. device_open does not run open itself: on iOS that can start a minutes-long
50
+ // XCTest runner build.
51
+ "Every app launch, deep link, tap, text entry, alert, setting, screenshot and recording on this device goes through it. Run open <bundle-or-package-id> (apps lists them) before snapshots, CLI screenshots or input; it starts the session they need. Use device_screenshot just to look.",
52
+ ` ${run("open <bundle-or-package-id> --relaunch")} # restarts the app; Expo dev clients connect to their Metro, --metro-port <port> picks it`,
53
+ ` ${run("open <bundle-or-package-id> <deep-link-url>")}`,
54
+ ` ${run("snapshot -i")} # accessibility tree with @eN refs`,
55
+ ` ${run("press @e3 --settle")}`,
56
+ ` ${run('fill @e5 "text" --settle')}`,
57
+ ` ${run("alert accept")}`,
58
+ ` ${run("settings appearance dark")} # also text-size, permission grant <name>`,
59
+ ` ${run("screenshot /tmp/shot.png")} # ${device.platform === "ios" ? "iOS saves 1x points; add --pixel-density <n> (3 on most iPhones) for device resolution, " : ""}or call device_screenshot to look`,
60
+ ` ${run("record start --scope device /tmp/run.mp4")} # then record stop`,
61
+ ` ${run("install <app> <path-to-.app-or-.apk>")}`,
62
+ `Prefer snapshot refs over coordinates. Run ${executable} help <command> for flags and ${executable} help workflow for guides.`,
63
+ "Do not use simctl, idb, adb or ssh for those actions. They stay fine for builds, installs, code sync, Metro, port forwards, logs, test runners and what this command cannot do; come back to it for every UI action and screenshot so the user can watch.",
64
+ "Each device_open returns its own command; opening another device does not retarget this one.",
65
+ ...(target === ""
66
+ ? [
67
+ "The command is removed when the device closes or T3 Code restarts. If it is missing, call device_open again.",
68
+ ]
69
+ : []),
70
platformNotes,
71
].join("\n");
72
}
@@ -67,30 +75,61 @@ const requireDeviceAccess = McpInvocationContext.requireThreadMcpCapability("dev
75
Effect.mapError(
76
() =>
77
new DeviceToolUnavailableError({
70
- reason: "Agent device access is turned off for this environment.",
78
+ reason:
79
+ "Agent device access is turned off for this environment. Ask the user to turn on Agent device access in Settings > Integrations > Devices; it applies when the agent session next starts, such as in a new thread.",
80
}),
81
),
82
);
83
84
+const hostName = (host: { readonly id: DeviceHostId; readonly label?: string | undefined }) =>
85
+ host.label === undefined ? `hostId ${host.id}` : `'${host.label}' (hostId ${host.id})`;
86
+
87
+const mapLocateErrors = <A, R>(
88
+ effect: Effect.Effect<
89
+ A,
90
+ DeviceService.DeviceHostAmbiguousError | DeviceService.DeviceOnOtherHostError,
91
+ R
92
+ >,
93
+) =>
94
+ effect.pipe(
95
+ Effect.catchTags({
96
+ DeviceHostAmbiguousError: (error) =>
97
+ Effect.fail(
98
+ new DeviceToolUnavailableError({
99
+ reason: `Device ${error.deviceId} is on more than one host: ${error.hosts.map(hostName).join(", ")}. Pass hostId.`,
100
+ }),
101
+ ),
102
+ DeviceOnOtherHostError: (error) =>
103
+ Effect.fail(
104
+ new DeviceToolUnavailableError({
105
+ reason: `Device ${error.deviceId} is not on ${hostName(error.host)}. It is on ${error.hosts.map(hostName).join(", ")}; pass that hostId.`,
106
+ }),
107
+ ),
108
+ }),
109
+ );
110
+
111
const pickDevice = Effect.fn("handlers.pickDevice")(function* (
76
- devices: ReadonlyArray<DeviceSummary>,
112
+ state: {
113
+ readonly hosts: ReadonlyArray<DeviceHostSummary>;
114
+ readonly devices: ReadonlyArray<DeviceSummary>;
115
+ },
116
input: {
117
readonly deviceId?: DeviceId | undefined;
118
readonly platform?: DevicePlatform | undefined;
119
readonly hostId?: DeviceHostId | undefined;
120
},
82
-): Effect.fn.Return<DeviceSummary, DeviceToolUnavailableError> {
83
- const hostId = input.hostId ?? LOCAL_DEVICE_HOST_ID;
121
+): Effect.fn.Return<DeviceSummary, DeviceToolUnavailableError, DeviceService.DeviceService> {
122
if (input.deviceId !== undefined) {
85
- const match = devices.find(
86
- (device) => device.hostId === hostId && device.id === input.deviceId,
87
- );
88
- if (match) return match;
123
+ const { deviceId, hostId } = input;
124
+ const devices = yield* DeviceService.DeviceService;
125
+ const located = yield* devices.locateDevice({ deviceId, hostId }).pipe(mapLocateErrors);
126
+ if (Option.isSome(located)) return located.value;
127
return yield* new DeviceToolUnavailableError({
90
- reason: `No device ${input.deviceId} on host ${hostId}. Call device_list for current ids.`,
128
+ reason: `No device ${deviceId} on ${hostId === undefined ? "any host" : hostName(state.hosts.find((host) => host.id === hostId) ?? { id: hostId })}. Call device_list for current ids.`,
129
});
130
}
93
- const candidates = devices.filter(
131
+ const hostId = input.hostId ?? LOCAL_DEVICE_HOST_ID;
132
+ const candidates = state.devices.filter(
133
(device) =>
134
device.hostId === hostId &&
135
(input.platform === undefined || device.platform === input.platform),
@@ -153,7 +192,7 @@ const handlers = {
192
"Device support is off. Ask the user to enable it in the Device panel before installing or starting device tools.",
193
});
194
}
156
- const target = yield* pickDevice(state.devices, input);
195
+ const target = yield* pickDevice(state, input);
196
// Resolve consent and agent connectivity before booting or registering a session.
197
if (!(yield* devices.agentReadinessIfSupported(target.hostId))) {
198
return yield* new DeviceToolUnavailableError({
@@ -177,42 +216,29 @@ const handlers = {
216
) ?? target;
217
// Target the opened device: an EAS device and its agent-device daemon
218
// exist only once its session runs, and Android ids change on boot.
180
- const agent = yield* devices.agentTarget({
219
+ const opened = {
220
threadId: scope.thread.threadId,
182
- hostId: device.hostId,
183
- deviceId: device.id,
184
- });
221
+ hostId: session.hostId,
222
+ deviceId: session.deviceId,
223
+ };
224
+ const agent = yield* devices.agentTarget(opened);
225
const cloud = after.hosts.some((host) => host.id === device.hostId && host.kind === "eas");
226
const targetArgs = [
227
...agentDeviceTargetArgs({ ...device, id: agent.agentDeviceId }),
228
...agent.args,
229
];
190
- const config = yield* ServerConfig.ServerConfig;
191
- const path = yield* Path.Path;
192
- const platform = yield* HostProcess.Platform;
193
- const shimDir = yield* ensureAgentDeviceShim({
194
- entryPath: yield* devices.agentCli,
195
- stateDir: config.stateDir,
196
- }).pipe(
197
- Effect.mapError(
198
- (error) =>
199
- new DeviceToolUnavailableError({
200
- reason:
201
- error._tag === "NodeRuntimeUnavailableError"
202
- ? nodeRuntimeUnavailableMessage("Device automation")
203
- : "Could not prepare the agent-device launcher.",
204
- cause: error,
205
- }),
206
- ),
207
- );
208
- const command = path.join(
209
- shimDir,
210
- platform === "win32" ? "agent-device.cmd" : "agent-device",
211
- );
230
+ const launcher = yield* devices.agentLauncher({ ...opened, targetArgs });
231
+ if (Option.isNone(launcher)) {
232
+ return yield* new DeviceToolUnavailableError({
233
+ reason:
234
+ "The device was closed while device_open was preparing it. Call device_open again only if you still need it.",
235
+ });
236
+ }
237
+ const command = launcher.value;
238
return {
239
device,
214
- agentDevice: { command, targetArgs },
215
- quickStart: agentDeviceQuickStart(device, targetArgs, command, cloud),
240
+ agentDevice: { command, targetArgs, session: agent.session },
241
+ quickStart: agentDeviceQuickStart(device, [], command, cloud),
242
};
243
}).pipe(Effect.mapError(toolError)),
244
),
@@ -220,20 +246,23 @@ const handlers = {
246
Effect.gen(function* () {
247
const scope = yield* requireDeviceAccess;
248
const devices = yield* DeviceService.DeviceService;
223
- const sessions = yield* devices.sessionsForThread(scope.thread.threadId);
224
- const hostId =
225
- input.deviceId === undefined ? input.hostId : (input.hostId ?? LOCAL_DEVICE_HOST_ID);
226
- const target = sessions.findLast(
227
- (session) =>
228
- (hostId === undefined || session.hostId === hostId) &&
229
- (input.deviceId === undefined || session.deviceId === input.deviceId),
230
- );
249
+ const threadId = scope.thread.threadId;
250
+ const target =
251
+ input.deviceId === undefined
252
+ ? (yield* devices.sessionsForThread(threadId)).findLast(
253
+ (session) => input.hostId === undefined || session.hostId === input.hostId,
254
+ )
255
+ : Option.getOrUndefined(
256
+ yield* devices
257
+ .locateSession({ threadId, deviceId: input.deviceId, hostId: input.hostId })
258
+ .pipe(mapLocateErrors),
259
+ );
260
if (!target) {
261
return yield* new DeviceToolUnavailableError({
262
reason:
263
input.deviceId === undefined
264
? "No device is open in this thread. Call device_open first."
236
- : `Device ${input.deviceId} on host ${hostId} is not open in this thread. Call device_open first.`,
265
+ : `Device ${input.deviceId} is not open in this thread. Call device_open first.`,
266
});
267
}
268
const shot = yield* devices.screenshot(target);
@@ -251,10 +280,18 @@ const handlers = {
280
Effect.gen(function* () {
281
const scope = yield* requireDeviceAccess;
282
const devices = yield* DeviceService.DeviceService;
283
+ const deviceId = input.deviceId;
284
+ const open =
285
+ deviceId === undefined
286
+ ? Option.none()
287
+ : yield* devices
288
+ .locateSession({ threadId: scope.thread.threadId, deviceId, hostId: input.hostId })
289
+ .pipe(mapLocateErrors);
290
+ const hostId = Option.isSome(open) ? open.value.hostId : input.hostId;
291
yield* devices.close({
292
threadId: scope.thread.threadId,
256
- ...(input.hostId === undefined ? {} : { hostId: input.hostId }),
257
- ...(input.deviceId === undefined ? {} : { deviceId: input.deviceId }),
293
+ ...(hostId === undefined ? {} : { hostId }),
294
+ ...(deviceId === undefined ? {} : { deviceId }),
295
...(input.shutdown === undefined ? {} : { shutdown: input.shutdown }),
296
});
297
return {};
apps/server/src/mcp/toolkits/device/tools.ts
+2
-2
@@ -29,7 +29,7 @@ const DeviceToolFailure = Schema.Union([DeviceToolError, OrchestratorMcpFailure]
29
30
const DeviceListTool = Tool.make("device_list", {
31
description:
32
- "List iOS Simulators and Android Emulators here, what each host can run, and what is open in this thread's Device panel. Call before `device_open` when you do not know a device id.",
32
+ "List iOS Simulators and Android Emulators on every device host, what each host can run, and what is open in this thread's Device panel. Call before `device_open` when you do not know a device id.",
33
// An empty struct serializes as `anyOf [object, array]`, which some
34
// providers reject and then drop every tool on the server with it.
35
parameters: Schema.Struct({
@@ -49,7 +49,7 @@ const DeviceListTool = Tool.make("device_list", {
49
50
const DeviceOpenTool = Tool.make("device_open", {
51
description:
52
- "Open a simulator or emulator for this thread. Boots it if needed and shows it in the user's Device panel. Returns the `agent-device` CLI call pinned to that device. Drive the device with that CLI.",
52
+ "Open a simulator or emulator for this thread. Pass `deviceId` and `hostId` from `device_list`. Boots it if needed and shows it in the user's Device panel. Returns the `agent-device` CLI call pinned to that device. Drive the device with that CLI.",
53
parameters: DeviceToolOpenInput,
54
success: DeviceToolOpenResult,
55
failure: DeviceToolFailure,
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
+69
@@ -79,6 +79,7 @@ import { attachmentRelativePath } from "../../attachmentStore.ts";
79
import { WorkflowAgentTranscriptReadObserver } from "../workflowAgentTranscript.ts";
80
import * as ServerConfig from "../../config.ts";
81
import * as McpProviderSession from "@t3tools/provider-core/server/mcpSession";
82
+import { T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH } from "@t3tools/provider-core/server/orchestrationInstructions";
83
import * as McpProviderSessions from "@t3tools/provider-core/server/McpProviderSessions";
84
import { PreviewControlsToolkit } from "../../mcp/toolkits/previewControls/tools.ts";
85
import { HtmlToolkit } from "../../mcp/toolkits/html/tools.ts";
@@ -603,6 +604,7 @@ describe("ClaudeAdapterV2 native protocol logging", () => {
604
assert.equal(systemPrompt.preset, "claude_code");
605
assert.include(systemPrompt.append ?? "", "Use `delegate_task`");
606
assert.include(systemPrompt.append ?? "", "call `t3_background_wait`");
607
+ assert.notInclude(systemPrompt.append ?? "", "## T3 Code devices");
608
const logged = ClaudeAdapterV2.loggedClaudeQueryOptions(options);
609
assert.equal(logged.hasMcpServers, true);
610
assert.notInclude(JSON.stringify(logged), "secret-claude-token");
@@ -622,6 +624,73 @@ describe("ClaudeAdapterV2 native protocol logging", () => {
624
});
625
});
626
627
+describe("ClaudeAdapterV2 device instructions", () => {
628
+ const options = (input: { readonly mcp: boolean; readonly deviceToolsAvailable: boolean }) =>
629
+ ClaudeAdapterV2.makeClaudeQueryOptions({
630
+ modelSelection: {
631
+ instanceId: ProviderInstanceId.make("claudeAgent"),
632
+ model: "claude-opus-5-5",
633
+ },
634
+ nativeThreadId: "native-thread-claude-devices",
635
+ resume: false,
636
+ cwd: "/workspace",
637
+ ...(input.mcp
638
+ ? { mcpServers: { "t3-code": { type: "http" as const, url: "http://127.0.0.1/mcp" } } }
639
+ : {}),
640
+ deviceToolsAvailable: input.deviceToolsAvailable,
641
+ environment: {},
642
+ });
643
+ const append = (input: { readonly mcp: boolean; readonly deviceToolsAvailable: boolean }) =>
644
+ (options(input).systemPrompt as { readonly append?: string }).append ?? "";
645
+
646
+ it("gives a session with device access the device block and the ToolSearch line to load it", () => {
647
+ const text = append({ mcp: true, deviceToolsAvailable: true });
648
+ assert.include(text, T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH);
649
+ assert.include(text, "Use `delegate_task`");
650
+ });
651
+
652
+ it("leaves the device block out without device access or without T3 tools", () => {
653
+ assert.notInclude(append({ mcp: true, deviceToolsAvailable: false }), "## T3 Code devices");
654
+ assert.notInclude(append({ mcp: false, deviceToolsAvailable: true }), "## T3 Code devices");
655
+ });
656
+
657
+ it("gives native subagents the device block only in a session with device access", async () => {
658
+ // Subagents start from their task prompt, not the parent's system prompt.
659
+ const subagentContext = (input: {
660
+ readonly mcp: boolean;
661
+ readonly deviceToolsAvailable: boolean;
662
+ }) =>
663
+ Promise.all(
664
+ (options(input).hooks?.SubagentStart ?? []).flatMap((matcher) =>
665
+ matcher.hooks.map((hook) =>
666
+ hook(
667
+ {
668
+ hook_event_name: "SubagentStart",
669
+ agent_id: "agent-1",
670
+ agent_type: "general-purpose",
671
+ session_id: "native-thread-claude-devices",
672
+ transcript_path: "/transcript.jsonl",
673
+ cwd: "/workspace",
674
+ },
675
+ undefined,
676
+ { signal: new AbortController().signal },
677
+ ),
678
+ ),
679
+ ),
680
+ );
681
+ assert.deepEqual(await subagentContext({ mcp: true, deviceToolsAvailable: true }), [
682
+ {
683
+ hookSpecificOutput: {
684
+ hookEventName: "SubagentStart",
685
+ additionalContext: T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH,
686
+ },
687
+ },
688
+ ]);
689
+ assert.deepEqual(await subagentContext({ mcp: true, deviceToolsAvailable: false }), []);
690
+ assert.deepEqual(await subagentContext({ mcp: false, deviceToolsAvailable: true }), []);
691
+ });
692
+});
693
+
694
describe("ClaudeAdapterV2 context usage", () => {
695
it("dates cache expiry from the request start, not the response end", () => {
696
const usage = ClaudeAdapterV2.claudeProviderTurnTokenUsage(
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
+28
-3
@@ -29,6 +29,7 @@ import {
29
type ForkSessionResult,
30
getSessionMessages,
31
getSubagentMessages,
32
+ type HookCallback,
33
query,
34
resolveSettings as resolveClaudeSettings,
35
type Options as ClaudeQueryOptions,
@@ -167,7 +168,10 @@ import {
168
} from "../../provider/claudeUsageLimits.ts";
169
import type { ManagedServerProvider } from "@t3tools/provider-core/server/snapshot";
170
import { mergeProviderInstanceEnvironment } from "@t3tools/provider-core/server/instanceEnvironment";
170
-import { T3_CODE_ORCHESTRATION_INSTRUCTIONS } from "@t3tools/provider-core/server/orchestrationInstructions";
171
+import {
172
+ T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH,
173
+ T3_CODE_ORCHESTRATION_INSTRUCTIONS,
174
+} from "@t3tools/provider-core/server/orchestrationInstructions";
175
import { buildRuntimeInstructions } from "@t3tools/provider-core/server/runtimeInstructions";
176
import {
177
mcpToolPresentation,
@@ -1431,6 +1435,15 @@ const CLAUDE_BACKGROUND_WAIT_INSTRUCTIONS = `
1435
To wait for a background command or Monitor you started (tests, a build), call \`t3_background_wait\` with its task ID before you end your turn. Do not mark work you leave running, or PRs. T3 MCP tools are deferred: load one with ToolSearch before you call it.
1436
`;
1437
1438
+// Native subagents start from their task, not this session's system prompt.
1439
+const subagentDeviceInstructions: HookCallback = () =>
1440
+ Promise.resolve({
1441
+ hookSpecificOutput: {
1442
+ hookEventName: "SubagentStart",
1443
+ additionalContext: T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH,
1444
+ },
1445
+ });
1446
+
1447
export function makeClaudeQueryOptions(input: {
1448
readonly modelSelection: ModelSelection;
1449
readonly nativeThreadId: string;
@@ -1442,6 +1455,8 @@ export function makeClaudeQueryOptions(input: {
1455
readonly sdkSettings?: string | ClaudeSdkSettings;
1456
readonly environment?: NodeJS.ProcessEnv;
1457
readonly mcpServers?: ClaudeQueryOptions["mcpServers"];
1458
+ /** The thread's T3 MCP session holds the `device` capability. */
1459
+ readonly deviceToolsAvailable?: boolean;
1460
readonly tools?: ClaudeAgentSdkQueryTools;
1461
readonly allowedTools?: ReadonlyArray<string>;
1462
readonly disallowedTools?: ReadonlyArray<string>;
@@ -1506,6 +1521,7 @@ export function makeClaudeQueryOptions(input: {
1521
...compactQuerySettings,
1522
env: { ...compactQuerySettings?.env, ENABLE_TOOL_SEARCH: input.toolSearchOverride },
1523
} as ClaudeSdkSettings);
1524
+ const deviceInstructions = input.mcpServers !== undefined && input.deviceToolsAvailable === true;
1525
const options: ClaudeAgentSdkQueryOptions = {
1526
model: compiledSelection.apiModelId,
1527
tools: claudeAgentSdkQueryToolsForSdk(selectedTools),
@@ -1558,10 +1574,17 @@ export function makeClaudeQueryOptions(input: {
1574
buildRuntimeInstructions({ harness: "Claude Code" }) +
1575
(input.mcpServers === undefined
1576
? ""
1561
- : T3_CODE_ORCHESTRATION_INSTRUCTIONS + CLAUDE_BACKGROUND_WAIT_INSTRUCTIONS),
1577
+ : T3_CODE_ORCHESTRATION_INSTRUCTIONS +
1578
+ CLAUDE_BACKGROUND_WAIT_INSTRUCTIONS +
1579
+ (deviceInstructions
1580
+ ? `\n${T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH}\n`
1581
+ : "")),
1582
...launchAppendSystemPrompt,
1583
].join("\n\n"),
1584
},
1585
+ ...(deviceInstructions
1586
+ ? { hooks: { SubagentStart: [{ hooks: [subagentDeviceInstructions] }] } }
1587
+ : {}),
1588
...(Object.keys(extraArgs).length === 0 ? {} : { extraArgs }),
1589
};
1590
const additionalDirectories = [
@@ -9689,8 +9712,9 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
9712
nativeThreadId: string,
9713
) {
9714
const queryPolicy = yield* queryPolicyForTurn(turnInput);
9715
+ const mcpSession = yield* mcpSessions.read(turnInput.threadId);
9716
const mcpOverrides = claudeMcpQueryOverrides({
9693
- mcpSession: yield* mcpSessions.read(turnInput.threadId),
9717
+ mcpSession,
9718
readOnlySandbox:
9719
sandboxPolicyKindForClaudeRuntimePolicy(turnInput.runtimePolicy) === "readOnly",
9720
...(queryPolicy.allowedTools === undefined
@@ -9826,6 +9850,7 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
9850
...(mcpOverrides.mcpServers === undefined
9851
? {}
9852
: { mcpServers: mcpOverrides.mcpServers }),
9853
+ deviceToolsAvailable: mcpSession?.capabilities?.has("device") === true,
9854
permissionMode: queryPolicy.permissionMode,
9855
...(queryPolicy.allowDangerouslySkipPermissions === undefined
9856
? {}
apps/server/src/orchestration-v2/ProviderSessionManager.test.ts
+32
-6
@@ -225,6 +225,7 @@ function makeThreadCreatedEvent(input: {
225
readonly threadId: ThreadId;
226
readonly now: DateTime.Utc;
227
readonly projectId?: ProjectId;
228
+ readonly delegatedBy?: ThreadId;
229
}) {
230
return Effect.gen(function* () {
231
const projectId =
@@ -249,11 +250,14 @@ function makeThreadCreatedEvent(input: {
250
branch: null,
251
worktreePath: null,
252
activeProviderThreadId: providerThreadId,
252
- lineage: {
253
- parentThreadId: null,
254
- relationshipToParent: null,
255
- rootThreadId: input.threadId,
256
- },
253
+ lineage:
254
+ input.delegatedBy === undefined
255
+ ? { parentThreadId: null, relationshipToParent: null, rootThreadId: input.threadId }
256
+ : {
257
+ parentThreadId: input.delegatedBy,
258
+ relationshipToParent: "subagent",
259
+ rootThreadId: input.delegatedBy,
260
+ },
261
forkedFrom: null,
262
createdAt: input.now,
263
updatedAt: input.now,
@@ -633,6 +637,7 @@ function runBrowserAccessScenario(input: {
637
readonly deviceOverride?: boolean;
638
readonly createThread?: boolean;
639
readonly projectExists?: boolean;
640
+ readonly delegatedBy?: ThreadId;
641
}) {
642
return Effect.gen(function* () {
643
const state = yield* Ref.make(emptyState);
@@ -661,7 +666,15 @@ function runBrowserAccessScenario(input: {
666
});
667
if (input.createThread !== false) {
668
yield* eventSink.write({
664
- events: [yield* makeThreadCreatedEvent({ idAllocator, threadId, now, projectId })],
669
+ events: [
670
+ yield* makeThreadCreatedEvent({
671
+ idAllocator,
672
+ threadId,
673
+ now,
674
+ projectId,
675
+ ...(input.delegatedBy === undefined ? {} : { delegatedBy: input.delegatedBy }),
676
+ }),
677
+ ],
678
});
679
}
680
yield* manager
@@ -3628,3 +3641,16 @@ it.effect(
3641
assert.isFalse(denied?.capabilities?.has("device"));
3642
}),
3643
);
3644
+
3645
+// Device instructions reach delegated children only because their own sessions hold `device`.
3646
+it.effect("ProviderSessionManagerV2 gives a delegated child its project's device access", () =>
3647
+ Effect.gen(function* () {
3648
+ const child = yield* runBrowserAccessScenario({
3649
+ enableAgentBrowserAccess: false,
3650
+ projectOverride: false,
3651
+ deviceOverride: true,
3652
+ delegatedBy: ThreadId.make("thread-provider-session-manager-parent"),
3653
+ });
3654
+ assert.isTrue(child?.capabilities?.has("device"));
3655
+ }),
3656
+);
apps/server/src/provider/CodexDeveloperInstructions.test.ts
+13
@@ -1,5 +1,6 @@
1
import * as NodeAssert from "node:assert/strict";
2
3
+import { T3_CODE_DEVICE_TOOL_INSTRUCTIONS } from "@t3tools/provider-core/server/orchestrationInstructions";
4
import { describe, it } from "vite-plus/test";
5
6
import {
@@ -76,6 +77,18 @@ describe("Codex orchestration context", () => {
77
});
78
});
79
80
+describe("Codex device context", () => {
81
+ it("adds the shared device block only when the session holds device access", () => {
82
+ const tools = (device: boolean) =>
83
+ buildCodexAdditionalContext({ model: "gpt-6.1-sol" }, { browser: true, device }).t3_code_tools
84
+ ?.value ?? "";
85
+
86
+ NodeAssert.ok(tools(true).includes(T3_CODE_DEVICE_TOOL_INSTRUCTIONS));
87
+ NodeAssert.ok(!tools(true).includes("ToolSearch"));
88
+ NodeAssert.ok(!tools(false).includes("## T3 Code devices"));
89
+ });
90
+});
91
+
92
function runtimeInstructions(runtime: Parameters<typeof buildCodexAdditionalContext>[0]) {
93
return buildCodexAdditionalContext(runtime).t3_code_runtime!.value;
94
}
apps/server/src/provider/CodexDeveloperInstructions.ts
+1
-4
@@ -3,16 +3,13 @@ import { buildRuntimeInstructions } from "@t3tools/provider-core/server/runtimeI
3
4
import {
5
T3_CODE_BROWSER_TOOL_INSTRUCTIONS,
6
+ T3_CODE_DEVICE_TOOL_INSTRUCTIONS,
7
T3_CODE_ORCHESTRATION_SECTIONS,
8
} from "@t3tools/provider-core/server/orchestrationInstructions";
9
10
/** Codex silently truncates additionalContext values over 1,000 tokens, counted as UTF-8 bytes / 4. */
11
export const CODEX_ADDITIONAL_CONTEXT_VALUE_MAX_BYTES = 4_000;
12
12
-const T3_CODE_DEVICE_TOOL_INSTRUCTIONS = `## T3 Code devices
13
-
14
-For iOS Simulators and Android Emulators here, call \`device_list\`, then \`device_open\`. Drive the device with the exact \`agent-device\` launcher and flags it returns, on every command. Prefer \`agent-device snapshot -i\` refs over coordinates. Use \`device_screenshot\` to see the screen. Use \`xcrun simctl\` or \`adb\` only for builds, logs, and ports. If a platform is unavailable, say so.`;
15
-
13
export interface T3CodeToolAvailability {
14
readonly browser: boolean;
15
readonly device: boolean;
apps/server/src/provider/agentContextBudget.json
+2
-2
@@ -1,5 +1,5 @@
1
{
2
"claudeSystemAppendBytes": 5135,
3
- "codexAdditionalContextBytes": 5687,
4
- "mcpToolListJsonBytes": 45842
3
+ "codexAdditionalContextBytes": 6865,
4
+ "mcpToolListJsonBytes": 45907
5
}
docs/internals/devices.md
+18
-3
@@ -93,9 +93,24 @@ already-running agent without the CLI.
93
94
How to drive a device is returned from `device_open`, not kept in an
95
always-loaded prompt or skill: it costs nothing in threads that never open a
96
-device and cannot drift from the pinned CLI version. The always-on prompt block
97
-is a few lines that point at the tools and prefer them over raw `simctl` and
98
-`adb`, which stay available for what the tools do not cover.
96
+device and cannot drift from the pinned CLI version. `device_open` returns a
97
+launcher bound to its agent-device session, so agents need no target flags.
98
+The launcher leaves out the flags a command refuses (`cdp` talks to Metro, not
99
+to the device), refuses the commands that would replace T3's connection, and
100
+checks that connection first: agent-device reports a sandboxed shell and a
101
+dropped tunnel alike as an unreachable daemon, so the launcher names which one it
102
+is. Ending a session (`device_close`, the Device panel, a shutdown) also closes
103
+its agent-device session, which quits the app that session opened and releases the CLI's claim on the device.
104
+
105
+Agents choose between these tools and ssh before they open anything, so
106
+sessions that hold `device` get a short block from
107
+[`orchestrationInstructions.ts`](../../packages/provider-core/src/server/orchestrationInstructions.ts)
108
+through their adapter's instruction channel. It points simulator and emulator UI
109
+work on local and SSH hosts at the tools; `simctl`, `adb` and ssh stay
110
+available for what the tools do not cover. Pi and Muse do not send it yet.
111
+Claude's native subagents never see the session's system prompt, so a
112
+`SubagentStart` hook passes them the block, where the runtime runs hooks and the
113
+subagent's context is not isolated.
114
115
## The viewer decodes both vendored protocols
116
evals/mcp-tool-use/run.test.ts
+2
@@ -248,6 +248,8 @@ it("rebuilds the template from this checkout and sends a child T3's task prompt"
248
"You are Claude Code.",
249
`Main prompt.\n - Primary working directory: /home/user/app\n\n${t3SystemAppend("claude-sonnet-5-5")}`,
250
]);
251
+ // The eval offers the device tools, so Claude's append carries the device block.
252
+ assert.include(t3SystemAppend("claude-sonnet-5-5"), "## T3 Code devices");
253
assert.equal(base.environment.cwd, "/home/user/app");
254
assert.include(system[2], "model named Sonnet 5.5. The exact model ID is claude-sonnet-5-5.");
255
const deferred = system[2]?.split("Load them first:\n")[1]?.split("\n\n")[0]?.split("\n") ?? [];
packages/contracts/src/device.test.ts
+26
@@ -1,6 +1,7 @@
1
import { describe, expect, it } from "@effect/vitest";
2
import { Schema } from "effect";
3
import {
4
+ DeviceBootError,
5
DeviceServiceState,
6
EasDeviceHostConfig,
7
EasDeviceHostConfigs,
@@ -79,3 +80,28 @@ describe("device state for clients from before EAS hosts", () => {
80
expect(decodeState(wire).hosts).toEqual(state.hosts);
81
});
82
});
83
+
84
+describe("device boot errors", () => {
85
+ it("gives a next step instead of blaming the environment server when the host sent no details", () => {
86
+ const message = new DeviceBootError({
87
+ hostId: "mac",
88
+ deviceId: "Pixel_10",
89
+ reason: "launch_failed",
90
+ cause: null,
91
+ }).message;
92
+ expect(message).not.toContain("environment server");
93
+ expect(message).toContain("Try again or open another device");
94
+ });
95
+
96
+ it("keeps the host's diagnostics when it sent them", () => {
97
+ const message = new DeviceBootError({
98
+ hostId: "mac",
99
+ deviceId: "Pixel_10",
100
+ reason: "launch_failed",
101
+ diagnostics: "emulator: PANIC: Missing emulator engine program for 'x86_64' CPU.",
102
+ cause: null,
103
+ }).message;
104
+ expect(message).toContain("PANIC: Missing emulator engine program");
105
+ expect(message).not.toContain("Try again");
106
+ });
107
+});
packages/contracts/src/device.ts
+6
-4
@@ -492,13 +492,14 @@ export class DeviceBootError extends Schema.TaggedError<DeviceBootError>()("Devi
492
}) {
493
override get message(): string {
494
const explanation = {
495
- disk_space: "There is not enough free disk space on the environment server.",
495
+ disk_space: "There is not enough free disk space on its device host.",
496
timeout: "The device did not become ready in time.",
497
- launch_failed:
498
- "The simulator or emulator could not start. Check its configuration on the environment server.",
497
+ launch_failed: "The simulator or emulator could not start.",
498
}[this.reason];
499
const summary = `Device ${this.deviceId} failed to boot: ${explanation}`;
501
- return this.diagnostics ? `${summary}\n\n${this.diagnostics}` : summary;
500
+ return this.diagnostics
501
+ ? `${summary}\n\n${this.diagnostics}`
502
+ : `${summary} The device host sent no details. Try again or open another device; if it keeps failing, check the device on that host.`;
503
}
504
}
505
@@ -584,6 +585,7 @@ export const DeviceToolOpenResult = Schema.Struct({
585
agentDevice: Schema.Struct({
586
command: Schema.String,
587
targetArgs: Schema.Array(Schema.String),
588
+ session: Schema.String,
589
}),
590
quickStart: Schema.String,
591
});
packages/provider-acp/src/server/adapter.ts
+3
-1
@@ -7171,9 +7171,11 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
7171
sessionId: string,
7172
) {
7173
const prompt: Array<EffectAcpSchema.ContentBlock> = [];
7174
+ const mcpSession = yield* mcpSessions.read(turnInput.threadId);
7175
const instructionState = {
7176
interactionMode: turnInput.runtimePolicy.interactionMode,
7176
- hasT3Mcp: (yield* readMcpContext(turnInput.threadId)).servers.length > 0,
7177
+ hasT3Mcp: acpMcpContext(mcpSession, self).servers.length > 0,
7178
+ hasDeviceTools: mcpSession?.capabilities?.has("device") === true,
7179
} satisfies T3AcpInstructionState;
7180
const previousInstructionState = (yield* Ref.get(promptInstructionStates)).get(sessionId);
7181
const compactionMarker = (yield* Ref.get(compactionMarkers)).get(sessionId);
packages/provider-core/src/server/orchestrationInstructions.test.ts
new
+85
@@ -0,0 +1,85 @@
1
+import { assert, describe, it } from "@effect/vitest";
2
+
3
+import {
4
+ T3_CODE_DEVICE_TOOL_INSTRUCTIONS,
5
+ T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH,
6
+ T3_CODE_ORCHESTRATION_INSTRUCTIONS,
7
+ t3AcpPromptWithInstructions,
8
+ t3OrchestrationPrompt,
9
+ t3OrchestrationSystemPrompt,
10
+} from "./orchestrationInstructions.ts";
11
+
12
+describe("T3 device instructions", () => {
13
+ it("route device work through device_open and give Claude the line that loads the tools", () => {
14
+ for (const intent of ["`device_list`", "`device_open`", "`agent-device`", "ssh", "`hostId`"]) {
15
+ assert.include(T3_CODE_DEVICE_TOOL_INSTRUCTIONS, intent);
16
+ }
17
+ assert.notInclude(T3_CODE_DEVICE_TOOL_INSTRUCTIONS, "ToolSearch");
18
+ const loadLine =
19
+ " Load them with ToolSearch `select:mcp__t3-code__device_list,mcp__t3-code__device_open,mcp__t3-code__device_screenshot,mcp__t3-code__device_close`.";
20
+ assert.include(T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH, loadLine);
21
+ assert.equal(
22
+ T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH.replace(loadLine, ""),
23
+ T3_CODE_DEVICE_TOOL_INSTRUCTIONS,
24
+ );
25
+ });
26
+
27
+ it("open the app before the returned command's snapshots, screenshots and input", () => {
28
+ assert.include(
29
+ T3_CODE_DEVICE_TOOL_INSTRUCTIONS,
30
+ "its snapshots, screenshots and input need `open <app>` first,",
31
+ );
32
+ });
33
+
34
+ it("keep the failure rule from taking over or closing a session another thread holds", () => {
35
+ // agent-device's DEVICE_IN_USE advice is to rerun with the owner's --session or close it first.
36
+ assert.include(
37
+ T3_CODE_DEVICE_TOOL_INSTRUCTIONS,
38
+ "follow its advice once, but never reuse or close another session; if it still fails,",
39
+ );
40
+ });
41
+
42
+ it("reach OpenCode and Cursor only when the session holds device access", () => {
43
+ assert.include(t3OrchestrationSystemPrompt(true, true), T3_CODE_DEVICE_TOOL_INSTRUCTIONS);
44
+ assert.notInclude(t3OrchestrationSystemPrompt(true, false), "## T3 Code devices");
45
+ assert.isUndefined(t3OrchestrationSystemPrompt(false, true));
46
+
47
+ const firstRun = (hasDeviceTools: boolean) =>
48
+ t3OrchestrationPrompt({
49
+ prompt: "Check the login screen.",
50
+ hasT3Mcp: true,
51
+ hasDeviceTools,
52
+ orchestrationDelivered: false,
53
+ deviceInstructionsDelivered: false,
54
+ });
55
+ assert.include(firstRun(true), T3_CODE_DEVICE_TOOL_INSTRUCTIONS);
56
+ assert.notInclude(firstRun(false), "## T3 Code devices");
57
+
58
+ const laterRun = (deviceInstructionsDelivered: boolean) =>
59
+ t3OrchestrationPrompt({
60
+ prompt: "Check the login screen.",
61
+ hasT3Mcp: true,
62
+ hasDeviceTools: true,
63
+ orchestrationDelivered: true,
64
+ deviceInstructionsDelivered,
65
+ });
66
+ assert.include(laterRun(false), T3_CODE_DEVICE_TOOL_INSTRUCTIONS);
67
+ assert.notInclude(laterRun(false), T3_CODE_ORCHESTRATION_INSTRUCTIONS.trim());
68
+ assert.equal(laterRun(true), "Check the login screen.");
69
+ });
70
+
71
+ it("reach ACP agents again when device access changes mid-thread", () => {
72
+ const state = { interactionMode: "default", hasT3Mcp: true, hasDeviceTools: false } as const;
73
+ const withDevices = t3AcpPromptWithInstructions({
74
+ prompt: "Check the login screen.",
75
+ state: { ...state, hasDeviceTools: true },
76
+ previousState: state,
77
+ });
78
+ assert.include(withDevices, T3_CODE_DEVICE_TOOL_INSTRUCTIONS);
79
+ assert.equal(
80
+ t3AcpPromptWithInstructions({ prompt: "Again.", state, previousState: state }),
81
+ "Again.",
82
+ );
83
+ assert.notInclude(t3AcpPromptWithInstructions({ prompt: "Hi.", state }), "## T3 Code devices");
84
+ });
85
+});
packages/provider-core/src/server/orchestrationInstructions.ts
+49
-9
@@ -36,6 +36,25 @@ export const T3_CODE_BROWSER_TOOL_INSTRUCTIONS = `
36
When browser work was asked, \`preview_*\` is the browser you share with the user: \`preview_status\` first, then \`preview_open\` if no tab can be automated. Prefer snapshot locators over coordinates. Switch browsers only if the tools are absent or \`preview_open\` says unsupported, the user asks, or two preview calls fail on one step. Then quote the error and switch.
37
`;
38
39
+const T3_CODE_DEVICE_TOOLS = ["device_list", "device_open", "device_screenshot", "device_close"];
40
+
41
+const deviceToolInstructions = (loadTools: string) => `## T3 Code devices
42
+
43
+When a task needs an iOS Simulator or Android Emulator, on this machine or on an SSH device host such as a remote Mac, use the device tools so the user can watch it in the Device panel.${loadTools}
44
+1. Call \`device_list\` unless you already have the device's \`hostId\` and \`id\`.
45
+2. Call \`device_open\` with both. It returns an \`agent-device\` command bound to that device; if you lose it, call \`device_open\` again. Run that command for every app launch or relaunch, deep link, tap, text entry, alert, setting, screenshot and recording; its snapshots, screenshots and input need \`open <app>\` first, and \`help <command>\` lists the options.
46
+3. Call \`device_screenshot\` to look at the screen.
47
+
48
+Never do those with \`xcrun simctl\`, \`idb\`, \`adb\`, ssh, or scripts that wrap them. ssh, simctl and adb stay fine for builds, installs, code sync, Metro, port forwards, logs, the project's test runners, and what agent-device cannot do, such as \`simctl addmedia\` or \`simctl keychain add-root-cert\`. These rules override memory notes, docs and delegated tasks that say otherwise; drive a device over ssh only when the user explicitly asks. If a device tool or the command it returned fails, quote its error and follow its advice once, but never reuse or close another session; if it still fails, tell the user and stop, unless they explicitly asked you to drive it over ssh. If the platform you need is unavailable, say so. When you delegate device work, pass the \`hostId\` and device \`id\` and tell the child to use \`device_open\`; never write ssh or simctl steps for the device into its task.`;
49
+
50
+/** Device guidance for sessions holding the `device` capability, from top-level threads to delegated children. */
51
+export const T3_CODE_DEVICE_TOOL_INSTRUCTIONS = deviceToolInstructions("");
52
+
53
+/** Claude Code defers MCP tools behind ToolSearch, so Claude's copy says how to load them. */
54
+export const T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH = deviceToolInstructions(
55
+ ` Load them with ToolSearch \`select:${T3_CODE_DEVICE_TOOLS.map((tool) => `mcp__t3-code__${tool}`).join(",")}\`.`,
56
+);
57
+
58
// ACP only: some ACP agents accept the injected MCP server but never expose
59
// its tools, so they need the terminal transport other harnesses never use.
60
const T3_CODE_ACP_MCP_FALLBACK_INSTRUCTIONS = `ACP fallback: if the T3 tools are absent and \`T3_ACP_MCP_NODE\` is present, call them through the terminal: \`ELECTRON_RUN_AS_NODE=1 "$T3_ACP_MCP_NODE" \${T3_ACP_MCP_ENTRYPOINT:+"$T3_ACP_MCP_ENTRYPOINT"} acp-mcp-call orchestrator_capabilities '{}'\` (\`T3_ACP_MCP_ENTRYPOINT\` is unset for a standalone executable). Delegate with \`acp-mcp-call delegate_task '{"task":"...","target":{"providerInstanceId":"...","model":"..."},"mode":"async","clientRequestId":"..."}'\`.`;
@@ -51,6 +70,7 @@ Investigate with read-only actions and do not edit files or otherwise execute th
70
export interface T3AcpInstructionState {
71
readonly interactionMode: ProviderInteractionMode;
72
readonly hasT3Mcp: boolean;
73
+ readonly hasDeviceTools: boolean;
74
}
75
76
/** ACP lacks system/developer fields; inject context on first prompt and tool/mode changes. */
@@ -63,7 +83,8 @@ export function t3AcpPromptWithInstructions(input: {
83
if (input.prompt.trimStart().startsWith("/")) return input.prompt;
84
if (
85
input.previousState?.interactionMode === input.state.interactionMode &&
66
- input.previousState.hasT3Mcp === input.state.hasT3Mcp
86
+ input.previousState.hasT3Mcp === input.state.hasT3Mcp &&
87
+ input.previousState.hasDeviceTools === input.state.hasDeviceTools
88
) {
89
return input.prompt;
90
}
@@ -74,6 +95,7 @@ export function t3AcpPromptWithInstructions(input: {
95
...(input.state.hasT3Mcp
96
? [
97
T3_CODE_BROWSER_TOOL_INSTRUCTIONS.trim(),
98
+ ...(input.state.hasDeviceTools ? [T3_CODE_DEVICE_TOOL_INSTRUCTIONS] : []),
99
T3_CODE_ORCHESTRATION_INSTRUCTIONS.trim(),
100
T3_CODE_ACP_MCP_FALLBACK_INSTRUCTIONS,
101
]
@@ -82,20 +104,38 @@ export function t3AcpPromptWithInstructions(input: {
104
return `<t3_code_instructions>\n${instructions.join("\n\n")}\n</t3_code_instructions>\n\n<user_request>\n${input.prompt}\n</user_request>`;
105
}
106
85
-function prependT3OrchestrationInstructions(prompt: string): string {
86
- return `<t3_code_orchestration_instructions>${T3_CODE_ORCHESTRATION_INSTRUCTIONS.trim()}</t3_code_orchestration_instructions>\n\n<user_request>\n${prompt}\n</user_request>`;
107
+const orchestrationInstructions = (hasDeviceTools: boolean) =>
108
+ hasDeviceTools
109
+ ? `${T3_CODE_ORCHESTRATION_INSTRUCTIONS}\n${T3_CODE_DEVICE_TOOL_INSTRUCTIONS}\n`
110
+ : T3_CODE_ORCHESTRATION_INSTRUCTIONS;
111
+
112
+function prependT3OrchestrationInstructions(prompt: string, instructions: string): string {
113
+ return `<t3_code_orchestration_instructions>${instructions.trim()}</t3_code_orchestration_instructions>\n\n<user_request>\n${prompt}\n</user_request>`;
114
}
115
89
-export function t3OrchestrationPromptForFirstRun(input: {
116
+/** For providers whose instructions ride on the prompt, so a compacted conversation loses them. */
117
+export function t3OrchestrationPrompt(input: {
118
readonly prompt: string;
91
- readonly runOrdinal: number;
119
readonly hasT3Mcp: boolean;
120
+ readonly hasDeviceTools: boolean;
121
+ readonly orchestrationDelivered: boolean;
122
+ readonly deviceInstructionsDelivered: boolean;
123
}): string {
94
- return input.runOrdinal === 1 && input.hasT3Mcp
95
- ? prependT3OrchestrationInstructions(input.prompt)
124
+ if (!input.hasT3Mcp) return input.prompt;
125
+ if (!input.orchestrationDelivered) {
126
+ return prependT3OrchestrationInstructions(
127
+ input.prompt,
128
+ orchestrationInstructions(input.hasDeviceTools),
129
+ );
130
+ }
131
+ return input.hasDeviceTools && !input.deviceInstructionsDelivered
132
+ ? prependT3OrchestrationInstructions(input.prompt, T3_CODE_DEVICE_TOOL_INSTRUCTIONS)
133
: input.prompt;
134
}
135
99
-export function t3OrchestrationSystemPrompt(hasT3Mcp: boolean): string | undefined {
100
- return hasT3Mcp ? T3_CODE_ORCHESTRATION_INSTRUCTIONS : undefined;
136
+export function t3OrchestrationSystemPrompt(
137
+ hasT3Mcp: boolean,
138
+ hasDeviceTools: boolean,
139
+): string | undefined {
140
+ return hasT3Mcp ? orchestrationInstructions(hasDeviceTools) : undefined;
141
}
packages/provider-cursor/src/server/adapter.test.ts
+152
@@ -586,6 +586,158 @@ describe("CursorAdapterV2", () => {
586
),
587
);
588
589
+ it.effect("sends T3 instructions to each Cursor conversation that lacks them", () =>
590
+ Effect.gen(function* () {
591
+ const fileSystem = yield* FileSystem.FileSystem;
592
+ const workspace = yield* fileSystem.makeTempDirectoryScoped({ prefix: "cursor-v2-device-" });
593
+ const sentMessages: Array<string> = [];
594
+ const instanceId = ProviderInstanceId.make("cursor");
595
+ const threadId = ThreadId.make("cursor-device-thread");
596
+ const mcpSessions = yield* McpProviderSessions.McpProviderSessions;
597
+ const setDeviceAccess = (device: boolean) =>
598
+ mcpSessions.set({
599
+ environmentId: EnvironmentId.make("cursor-device-environment"),
600
+ threadId,
601
+ providerSessionId: "cursor-device-session",
602
+ providerInstanceId: instanceId,
603
+ endpoint: "http://127.0.0.1:43123/mcp",
604
+ authorizationHeader: "Bearer synthetic-cursor-token",
605
+ browserToolsAvailable: true,
606
+ capabilities: new Set(device ? ["device"] : []),
607
+ });
608
+ const modelSelection = { instanceId, model: "composer-2.5" };
609
+ const runtimePolicy = ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
610
+ runtimeMode: "full-access",
611
+ interactionMode: "default",
612
+ cwd: workspace,
613
+ });
614
+ const adapter = yield* makeCursorAdapterV2({
615
+ instanceId,
616
+ environment: { HOME: workspace },
617
+ }).pipe(
618
+ Effect.provideService(CursorAgentSdk.CursorAgentSdkRunner, {
619
+ assertComplete: Effect.void,
620
+ open: () =>
621
+ Effect.succeed({
622
+ agentId: "native-cursor-device",
623
+ listMessages: Effect.succeed([]),
624
+ close: Effect.void,
625
+ send: (input) =>
626
+ Effect.sync(() => {
627
+ sentMessages.push(
628
+ typeof input.message === "string" ? input.message : input.message.text,
629
+ );
630
+ const runId = `native-cursor-run-${sentMessages.length}`;
631
+ return {
632
+ agentId: "native-cursor-device",
633
+ runId,
634
+ wait: Effect.succeed({
635
+ id: runId,
636
+ requestId: `native-request-${sentMessages.length}`,
637
+ status: "finished" as const,
638
+ model: { id: "composer-2.5" },
639
+ durationMs: 1,
640
+ }),
641
+ cancel: Effect.void,
642
+ };
643
+ }),
644
+ }),
645
+ }),
646
+ Effect.provide(TestProviderHost.layer({ cwd: workspace })),
647
+ );
648
+ const runtime = yield* adapter.openSession({
649
+ threadId,
650
+ providerSessionId: ProviderSessionId.make("cursor-device-session"),
651
+ modelSelection,
652
+ runtimePolicy,
653
+ });
654
+ const providerThread = yield* runtime.ensureThread({
655
+ threadId,
656
+ modelSelection,
657
+ runtimePolicy,
658
+ });
659
+ const now = yield* DateTime.now;
660
+ const appThread = {
661
+ id: threadId,
662
+ projectId: ProjectId.make("cursor-device-project"),
663
+ createdBy: "user" as const,
664
+ creationSource: "web" as const,
665
+ title: "Cursor devices",
666
+ providerInstanceId: instanceId,
667
+ modelSelection,
668
+ runtimeMode: "full-access" as const,
669
+ interactionMode: "default" as const,
670
+ branch: null,
671
+ worktreePath: null,
672
+ activeProviderThreadId: providerThread.id,
673
+ lineage: { parentThreadId: null, relationshipToParent: null, rootThreadId: threadId },
674
+ forkedFrom: null,
675
+ createdAt: now,
676
+ updatedAt: now,
677
+ archivedAt: null,
678
+ settledOverride: null,
679
+ settledAt: null,
680
+ lastVisitedAt: null,
681
+ deletedAt: null,
682
+ };
683
+ // Starts at run 5: a conversation from before device instructions existed, now resumed.
684
+ let runOrdinal = 4;
685
+ const send = Effect.fnUntraced(function* (compact = false) {
686
+ runOrdinal += 1;
687
+ const turnInput = {
688
+ threadId,
689
+ providerThread,
690
+ modelSelection,
691
+ runtimePolicy,
692
+ runId: RunId.make(`cursor-device-run-${runOrdinal}`),
693
+ runOrdinal,
694
+ providerTurnOrdinal: runOrdinal,
695
+ attemptId: RunAttemptId.make(`cursor-device-attempt-${runOrdinal}`),
696
+ rootNodeId: NodeId.make(`cursor-device-root-${runOrdinal}`),
697
+ appThread,
698
+ message: {
699
+ messageId: MessageId.make(`cursor-device-message-${runOrdinal}`),
700
+ createdBy: "user" as const,
701
+ creationSource: "web" as const,
702
+ text: "Open the app.",
703
+ attachments: [],
704
+ },
705
+ };
706
+ yield* compact ? runtime.compactThread!(turnInput) : runtime.startTurn(turnInput);
707
+ yield* runtime.events.pipe(
708
+ Stream.filter((event) => event.type === "turn.terminal"),
709
+ Stream.runHead,
710
+ );
711
+ const sent = sentMessages.at(-1)!;
712
+ return {
713
+ orchestration: sent.includes("## T3 Code orchestration"),
714
+ devices: sent.includes("## T3 Code devices"),
715
+ };
716
+ });
717
+ const told = (orchestration: boolean, devices: boolean) => ({ orchestration, devices });
718
+
719
+ yield* setDeviceAccess(true);
720
+ assert.deepEqual(yield* send(), told(false, true));
721
+ assert.deepEqual(yield* send(), told(false, false));
722
+ yield* send(true);
723
+ assert.deepEqual(
724
+ yield* send(),
725
+ told(true, true),
726
+ "compaction drops what the conversation was told",
727
+ );
728
+ yield* setDeviceAccess(false);
729
+ assert.deepEqual(yield* send(), told(false, false));
730
+ yield* setDeviceAccess(true);
731
+ assert.deepEqual(yield* send(), told(false, true), "device access turned on later");
732
+ assert.deepEqual(yield* send(), told(false, false));
733
+ }).pipe(
734
+ Effect.scoped,
735
+ Effect.provide(
736
+ Layer.mergeAll(NodeServices.layer, IdAllocator.layer, McpProviderSessions.layer),
737
+ ),
738
+ ),
739
+ );
740
+
741
it.effect("projects Cursor directory trees and lint diagnostics as file search results", () =>
742
Effect.gen(function* () {
743
const fileSystem = yield* FileSystem.FileSystem;
packages/provider-cursor/src/server/adapter.ts
+35
-5
@@ -52,7 +52,7 @@ import {
52
hasCursorSkillMention,
53
rewriteCursorSkillMentions,
54
} from "./skills.ts";
55
-import { t3OrchestrationPromptForFirstRun } from "@t3tools/provider-core/server/orchestrationInstructions";
55
+import { t3OrchestrationPrompt } from "@t3tools/provider-core/server/orchestrationInstructions";
56
import { buildRuntimeInstructions } from "@t3tools/provider-core/server/runtimeInstructions";
57
import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
58
import { makeProviderFailure } from "@t3tools/provider-core/server/failure";
@@ -904,6 +904,12 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* (
904
});
905
const events = yield* Queue.unbounded<ProviderAdapter.ProviderAdapterV2Event>();
906
const liveAgent = yield* Ref.make<CursorLiveAgent | null>(null);
907
+ // What the native conversation was told since it started or was last compacted.
908
+ const told = yield* Ref.make<{
909
+ readonly agent: string;
910
+ readonly orchestration: boolean;
911
+ readonly device: boolean;
912
+ } | null>(null);
913
const warnedUnsupportedSandbox = yield* Ref.make(false);
914
const activeTurn = yield* Ref.make<ActiveCursorTurn | null>(null);
915
const planIds = yield* Ref.make(new Map<string, OrchestrationV2PlanArtifact["id"]>());
@@ -2181,6 +2187,8 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* (
2187
const resolveUserMessage = Effect.fnUntraced(function* (
2188
turnInput: ProviderAdapter.ProviderAdapterV2TurnInput,
2189
mcpServers: Record<string, McpServerConfig> | undefined,
2190
+ hasDeviceTools: boolean,
2191
+ delivered: { readonly orchestration: boolean; readonly device: boolean },
2192
) {
2193
const rawText = turnInput.message.text;
2194
if (rawText.trim() === "/compress" && turnInput.message.attachments.length === 0) {
@@ -2200,7 +2208,7 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* (
2208
.map((skill) => skill.name),
2209
);
2210
}
2203
- const userText = t3OrchestrationPromptForFirstRun({
2211
+ const userText = t3OrchestrationPrompt({
2212
prompt: yield* providerMessageTextWithAttachmentPaths({
2213
text:
2214
cursorSkillNames === undefined
@@ -2210,8 +2218,10 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* (
2218
resolveAttachmentPath: host.resolveAttachmentPath,
2219
resolveExtractedTextPath: host.resolveExtractedTextPath,
2220
}),
2213
- runOrdinal: turnInput.runOrdinal,
2221
hasT3Mcp: mcpServers !== undefined,
2222
+ hasDeviceTools,
2223
+ orchestrationDelivered: delivered.orchestration,
2224
+ deviceInstructionsDelivered: delivered.device,
2225
});
2226
const images = yield* Effect.forEach(
2227
turnInput.message.attachments.filter(isProviderNativeImageAttachment),
@@ -2275,8 +2285,22 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* (
2285
modelSelection: turnInput.modelSelection,
2286
runtimePolicy: turnInput.runtimePolicy,
2287
});
2278
- const mcpServers = cursorMcpServers(yield* mcpSessions.read(turnInput.threadId));
2279
- const message = yield* resolveUserMessage(turnInput, mcpServers);
2288
+ const mcpSession = yield* mcpSessions.read(turnInput.threadId);
2289
+ const mcpServers = cursorMcpServers(mcpSession);
2290
+ const hasDeviceTools =
2291
+ mcpServers !== undefined && mcpSession?.capabilities?.has("device") === true;
2292
+ const known = yield* Ref.get(told);
2293
+ // A conversation this process has not sent to was told on its first run.
2294
+ const delivered =
2295
+ known?.agent === agent.nativeThreadId
2296
+ ? known
2297
+ : { orchestration: turnInput.runOrdinal > 1, device: false };
2298
+ const message = yield* resolveUserMessage(
2299
+ turnInput,
2300
+ mcpServers,
2301
+ hasDeviceTools,
2302
+ delivered,
2303
+ );
2304
const pendingUpdates: Array<InteractionUpdate> = [];
2305
let context: ActiveCursorTurn | null = null;
2306
// MCP send overrides replace the ambient servers loaded when the agent opens.
@@ -2297,6 +2321,12 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* (
2321
},
2322
})
2323
.pipe(Effect.mapError(classifyCursorModelRejection(turnInput.modelSelection)));
2324
+ const compacted = message === "/compress";
2325
+ yield* Ref.set(told, {
2326
+ agent: agent.nativeThreadId,
2327
+ orchestration: !compacted && (delivered.orchestration || mcpServers !== undefined),
2328
+ device: !compacted && hasDeviceTools,
2329
+ });
2330
const startedAt = yield* DateTime.now;
2331
const completed = yield* Deferred.make<void, never>();
2332
const providerTurnId = idAllocator.derive.providerTurn({
packages/provider-opencode/src/server/adapter.ts
+4
-1
@@ -948,7 +948,10 @@ export const makeOpenCodeAdapterV2 = Effect.fn("makeOpenCodeAdapterV2")(function
948
949
const mcpSession = yield* mcpSessions.read(input.threadId);
950
const hasT3Mcp = mcpSession !== undefined && !connection.external;
951
- const orchestrationSystemPrompt = t3OrchestrationSystemPrompt(hasT3Mcp);
951
+ const orchestrationSystemPrompt = t3OrchestrationSystemPrompt(
952
+ hasT3Mcp,
953
+ mcpSession?.capabilities?.has("device") === true,
954
+ );
955
if (hasT3Mcp) {
956
yield* OpenCodeRuntime.runOpenCodeSdk("mcp.add", () =>
957
client.mcp.add({
packages/provider-opencode/src/server/v2/adapter.ts
+1
-1
@@ -3051,7 +3051,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr
3051
}
3052
const instructions = [
3053
buildRuntimeInstructions({ harness: "OpenCode", model: turnInput.modelSelection.model }),
3054
- t3OrchestrationSystemPrompt(mcpAvailable),
3054
+ t3OrchestrationSystemPrompt(mcpAvailable, mcpSession?.capabilities?.has("device") === true),
3055
]
3056
.filter((part) => part !== undefined && part.length > 0)
3057
.join("\n\n");