@devries-cameron20 / t3code-1 / commits / d07c0a7c7b
Fork 0

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");