Skip to content
TypeScript
42.6 KB
Raw Blame
// @effect-diagnostics nodeBuiltinImport:off
import * as NodeFS from "node:fs";
import * as NodeZlib from "node:zlib";
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
import * as NodeServices from "@effect/platform-node/NodeServices";
import * as Layer from "effect/Layer";
import { assert, it } from "@effect/vitest";
import * as Effect from "effect/Effect";
import * as Schema from "effect/Schema";

import {
  AGENT_DEVICE_SHELL,
  agentDeviceSessionError,
  agentDeviceSessions,
  describeSessions,
  deviceFailure,
  type LauncherTarget,
  launcherHelp,
  makeDeviceTools,
  type ShellCall,
} from "./devices.ts";
import {
  buildBase,
  buildMessages,
  cannedOutput,
  makeSample,
  McpToolUseCase,
  shellRequest,
  t3SubagentContext,
  t3SystemAppend,
  withDevices,
} from "./run.ts";
import { DeviceOperationError, LOCAL_DEVICE_HOST_ID } from "@t3tools/contracts";

const MAC = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";
const IPHONE = "BBBBBBBB-BBBB-4BBB-8BBB-BBBBBBBBBBBB";
const world = {
  devices: [
    {
      hostId: MAC,
      id: IPHONE,
      name: "Acme iPhone",
      platform: "ios",
      version: "iOS 26.0",
      booted: true,
      physical: false,
    },
  ],
  deviceHosts: { [MAC]: "build-mac" },
};
const screenshotFailure = {
  _tag: "DeviceOperationError",
  operation: "screenshot",
  reason: "request_failed",
  cause: null,
};
const decodeCase = Schema.decodeUnknownSync(McpToolUseCase);
const deviceCase = (setup: object) =>
  decodeCase({
    id: "device-case",
    area: "device-manager",
    kind: "guard",
    pattern: "device",
    experience: "A device case.",
    setup: { role: "top", world, ...setup },
    prompt: "Show a fresh screenshot of the iPhone on build-mac.",
    expect: {},
  });
const capture = JSON.parse(
  NodeZlib.gunzipSync(
    NodeFS.readFileSync(new URL("./templates/claude.json.gz", import.meta.url)),
  ).toString(),
).request.provider_native;
const model = "claude-opus-5-5";
const base = buildBase(capture, { model, keepUserInstructions: false });
const json = (text: string) => JSON.parse(text);

it.effect("answers device calls with T3's handlers over the case's world", () =>
  Effect.gen(function* () {
    const { devices, deviceHosts } = deviceCase({}).setup.world ?? {};
    const tools = yield* makeDeviceTools({ devices: devices ?? [], deviceHosts }, base.environment);
    const listed = json((yield* tools.call("device_list", {})).text);
    assert.deepEqual(listed.devices, world.devices);
    assert.deepEqual(
      listed.hosts.map((host: { label: string }) => host.label),
      ["This machine", "build-mac"],
    );
    const opened = json((yield* tools.call("device_open", { hostId: MAC, deviceId: IPHONE })).text);
    const { command } = opened.agentDevice;
    assert.match(command, /^\/home\/user\/\.t3\/userdata\/device\/.+\/agent-device$/);
    assert.include(opened.quickStart, command);
    assert.deepEqual(tools.launchers, [command]);
    // The image never reaches the model; T3's text result has the rest.
    assert.deepEqual(json((yield* tools.call("device_screenshot", {})).text).screenshot, {
      mimeType: "image/png",
      width: 1206,
      height: 2622,
    });
    const failed = yield* tools.call("device_screenshot", {}, deviceFailure(screenshotFailure));
    assert.isTrue(failed.isError);
    assert.include(failed.text, "screenshot failed");
    const elsewhere = yield* tools.call("device_open", { hostId: "local", deviceId: IPHONE });
    assert.isTrue(elsewhere.isError);
    assert.include(elsewhere.text, IPHONE);
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it.effect("lists the boot state T3 left a device in", () =>
  Effect.gen(function* () {
    const { devices, deviceHosts } = deviceCase({}).setup.world ?? {};
    const stopped = (devices ?? []).map((device) => ({ ...device, booted: false }));
    const tools = yield* makeDeviceTools({ devices: stopped, deviceHosts }, base.environment);
    const before = json((yield* tools.call("device_list", {})).text);
    assert.isFalse(before.devices.find((d: { id: string }) => d.id === IPHONE).booted);
    yield* tools.call("device_open", { hostId: MAC, deviceId: IPHONE });
    const after = json((yield* tools.call("device_list", {})).text);
    assert.isTrue(after.devices.find((d: { id: string }) => d.id === IPHONE).booted);
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it("decodes only T3 device errors as injected failures", () => {
  assert.isDefined(deviceFailure(screenshotFailure));
  assert.isUndefined(deviceFailure({ error: "Synthetic hub is unavailable", isError: true }));
  assert.isUndefined(deviceFailure("default"));
});

it.effect("rebuilds prior device results with T3, whose sessions reach the measured turn", () =>
  Effect.gen(function* () {
    const testCase = deviceCase({
      priorTurns: [
        { role: "user", text: "Show me Settings on the iPhone on build-mac." },
        {
          role: "assistant",
          toolCalls: [
            { tool: "device_list", input: {}, result: "default" },
            { tool: "device_open", input: { hostId: MAC, deviceId: IPHONE }, result: "default" },
          ],
        },
      ],
      mocks: { device_screenshot: screenshotFailure },
    });
    const sample = makeSample(testCase, base);
    assert.throws(() => buildMessages(sample), /run withDevices/);
    yield* withDevices(sample);
    const shown = JSON.stringify(buildMessages(sample));
    const [launcher = ""] = sample.devices?.launchers ?? [];
    assert.include(shown, launcher);
    assert.notInclude(shown, `"content":"default"`);
    const tools = sample.devices!;
    assert.isFalse((yield* tools.call("device_screenshot", {})).isError);
    const mock = deviceFailure(testCase.setup.mocks?.device_screenshot);
    assert.isTrue((yield* tools.call("device_screenshot", {}, mock)).isError);
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it.effect("gives a native subagent T3's SubagentStart context instead of T3's append", () =>
  Effect.gen(function* () {
    const subagentContext = yield* Effect.promise(() => t3SubagentContext(model));
    const native = {
      ...buildBase(capture, { model, keepUserInstructions: false, nativeSubagent: true }),
      subagentContext,
    };
    const system = (blocks: typeof base.system) =>
      blocks.map((block) => String(block.text)).join("");
    assert.include(system(base.system), t3SystemAppend(model));
    assert.notInclude(system(native.system), t3SystemAppend(model));
    const testCase = deviceCase({ role: "native-subagent" });
    const shown = (sample: typeof native) =>
      buildMessages(makeSample(testCase, sample))[0]?.content.map((block) => String(block.text));
    const reminders = shown(native)?.join("\n") ?? "";
    // A ref without T3's hook gives the subagent nothing.
    assert.equal(
      reminders.includes("SubagentStart hook additional context"),
      subagentContext !== "",
    );
    assert.include(reminders, subagentContext);
    // Claude Code 2.1.310 records the hook's context after the task, and sends it that way.
    const blocks = shown({ ...native, subagentContext: "## T3 Code devices" }) ?? [];
    assert.equal(blocks.at(-2), testCase.prompt);
    assert.equal(
      blocks.at(-1),
      "<system-reminder>\nSubagentStart hook additional context: ## T3 Code devices\n</system-reminder>",
    );
  }),
);

it.effect("tells the shell simulator the launchers T3 returned and agent-device's real CLI", () =>
  Effect.gen(function* () {
    const sample = makeSample(deviceCase({}), base);
    yield* withDevices(sample);
    const call = { tool: "Bash", input: { command: "ls /tmp" } };
    const told = (request: ReturnType<typeof shellRequest>) => JSON.stringify(request.messages);
    assert.notInclude(told(shellRequest(sample, call, "claude-haiku-5-5")), "launchers T3's");
    const opened = yield* sample.devices!.call("device_open", { hostId: MAC, deviceId: IPHONE });
    const { command } = json(opened.text).agentDevice;
    const request = shellRequest(sample, call, "claude-haiku-5-5");
    assert.include(told(request), `agent-device launchers T3's device_open returned: ${command}`);
    // agent-device's own syntax: a positional recording path, and `record stop` with no flag.
    assert.include(request.system, AGENT_DEVICE_SHELL);
    assert.include(
      request.system,
      "agent-device record start [path] [--scope <app|device|system>]",
    );
    assert.include(request.system, "| record stop |");
    assert.include(request.system, "Unknown flag: --stop. Did you mean --scope?");
    // A case without devices keeps the shell prompt every other case has.
    const plain = makeSample(deviceCase({ world: {} }), base);
    assert.notInclude(shellRequest(plain, call, "claude-haiku-5-5").system, "agent-device");
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it("prints agent-device's own help for a lone help command on a returned launcher", () => {
  const help = (topic: string) =>
    AGENT_DEVICE_SHELL.split(`$ agent-device help${topic ? ` ${topic}` : ""}\n`)[1]
      ?.split("\n$ agent-device help")[0]
      ?.trimEnd();
  // Commands from the paired runs. The simulator once answered the first with a placeholder.
  const launcher = "/home/user/.t3/userdata/device/bin/agent-device";
  const target = `--platform ios --udid ${IPHONE} --config /home/user/.t3/userdata/device/hosts/303617b9730210ef3c86c52d.json --session t3-4c43aa31e607633b85e9ff2f`;
  const asked = (command: string) => launcherHelp([launcher], command);
  assert.match(help("") ?? "", /^agent-device <command> \[args\] \[--json\]\n/);
  assert.equal(asked(`${launcher} help ${target}`), help(""));
  assert.equal(asked(`${launcher} record --help ${target}`), help("record"));
  assert.equal(asked(`${launcher} help open ${target}`), help("open"));
  assert.equal(asked(`${launcher} --help 2>&1`), help(""));
  assert.equal(asked(`${launcher} help settings --session=t3-1`), help("settings"));
  // A password reaches fill from stdin, so request_secret's file never enters argv.
  assert.equal(asked(`${launcher} fill --help ${target}`), help("fill"));
  assert.include(help("fill"), "fill <x y|@ref|selector> --text-stdin");
  // Anything else stays with the simulator: other topics, pipes, aliases, other commands.
  assert.isUndefined(asked(`${launcher} metro --help ${target}`));
  assert.isUndefined(asked(`${launcher} help record 2>&1 | head -40`));
  assert.isUndefined(asked(`AD=${launcher}; $AD help record`));
  assert.isUndefined(asked(`${launcher} snapshot -i ${target}`));
  assert.isUndefined(asked(`/usr/local/bin/agent-device help`));
});

it("pins agent-device's help to the version T3 installs", () => {
  const versions = JSON.parse(
    NodeFS.readFileSync(
      new URL("../../apps/server/src/device/deviceToolVersions.json", import.meta.url),
      "utf8",
    ),
  );
  assert.include(AGENT_DEVICE_SHELL, `agent-device ${versions["agent-device"]} prints this help`);
});

// agent-device 0.21.31's errors as a real Mac printed them (stderr, exit status 1).
const NO_SESSION =
  "Error (SESSION_NOT_FOUND): No active session. Run open first.\nHint: Run open first or pass an explicit device selector.";
const APP_RECORDING_BEFORE_OPEN =
  "Error (INVALID_ARGS): record start with app scope and an explicit session requires an active app session; run open <app> first, or use --scope device to record the full screen\nHint: Check command arguments and run --help for usage examples.";
/** agent-device 0.21.31's snapshot-runtime-binding refusal, with the CLI's default hint. */
const iosSnapshotRefused = (session: string) =>
  `Error (SESSION_NOT_FOUND): iOS snapshot requires an active app session on the target device. Run open first (for example: open --session ${session} --platform ios --device "<name>" <app>).\nHint: Run open first or pass an explicit device selector.`;
const APP_RECORDING_WITHOUT_APP =
  "Error (UNKNOWN): App-scoped recording requires an active app session; open the app under test before recording.\nHint: Unexpected internal error. Retry with --debug and report the diagnostics log if it persists.";

it.effect("answers the returned launcher as agent-device does before and after open", () =>
  Effect.gen(function* () {
    const { devices = [], deviceHosts } = deviceCase({}).setup.world ?? {};
    const tools = yield* makeDeviceTools({ devices, deviceHosts }, base.environment);
    const opened = json((yield* tools.call("device_open", { hostId: MAC, deviceId: IPHONE })).text);
    const { command, targetArgs, session: bound } = opened.agentDevice;
    // This ref's launcher: a bound one names its session; the shared one takes device_open's flags.
    const session: string = bound ?? targetArgs[targetArgs.indexOf("--session") + 1];
    const line = (args: string) =>
      bound === undefined ? `${command} ${args} ${targetArgs.join(" ")}` : `${command} ${args}`;
    const history: Array<ShellCall> = [];
    const answer = (args: string) => tools.sessionError(history, line(args));
    const ran = (args: string, output: string) =>
      history.push({ tool: "Bash", input: { command: line(args) }, output });

    const shot = answer("screenshot /tmp/shot.png") ?? "";
    assert.isTrue(shot.startsWith(`Exit code 1\n${NO_SESSION}\nDiagnostic ID: `));
    assert.match(
      shot,
      new RegExp(
        `\\nDiagnostics Log: /home/user/\\.agent-device/remote-diagnostics/${session}/requests/[\\da-f]{16}\\.ndjson$`,
      ),
    );
    for (const args of ["press @e3 --settle", 'fill @e5 "hello world"', "scroll down", "home"]) {
      assert.include(answer(args), NO_SESSION, args);
    }
    assert.include(answer("record start /tmp/run.mp4"), APP_RECORDING_BEFORE_OPEN);
    // An iOS snapshot needs an app open in the session.
    assert.include(answer("snapshot -i"), iosSnapshotRefused("sim"));
    // With the device selector both refs pass, these run without a session.
    for (const args of [
      "open",
      "devices",
      "apps",
      "settings appearance dark",
      "alert accept",
      "install com.acme.app /tmp/Acme.app",
      "record start --scope device /tmp/run.mp4",
    ]) {
      assert.isUndefined(answer(args), args);
    }
    // Unknown flags, JSON output and compound commands stay with the simulator.
    assert.isUndefined(answer("screenshot --bogus /tmp/shot.png"));
    assert.isUndefined(answer("screenshot --json /tmp/shot.png"));
    assert.isUndefined(tools.sessionError(history, `${line("screenshot /tmp/a.png")} && echo ok`));
    assert.deepEqual([...tools.sessions(history)], [[session, undefined]]);

    ran("open com.acme.missing", "Exit code 1\nError (APP_NOT_INSTALLED): App not installed");
    assert.include(answer("screenshot /tmp/shot.png"), NO_SESSION);
    ran("open", `Opened: ${session}`);
    assert.isUndefined(answer("screenshot /tmp/shot.png"));
    assert.isUndefined(answer("press @e3"));
    assert.include(answer("record start /tmp/run.mp4"), APP_RECORDING_WITHOUT_APP);
    assert.isUndefined(answer("record start --scope device /tmp/run.mp4"));
    assert.include(answer("snapshot -i"), iosSnapshotRefused(session));
    ran("open com.acme.app", "Opened: com.acme.app");
    assert.isUndefined(answer("record start /tmp/run.mp4"));
    assert.isUndefined(answer("snapshot -i"));
    assert.deepEqual([...tools.sessions(history)], [[session, { app: true }]]);
    ran("close", "Closed");
    assert.include(
      tools.sessionError(history, `${line("screenshot /tmp/a.png")} 2>&1`),
      NO_SESSION,
    );
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

const shared = (session: string): LauncherTarget => ({
  command: "/home/user/.t3/userdata/device/bin/agent-device",
  session,
  bound: false,
  deviceId: IPHONE,
  ios: true,
  iosSimulator: true,
});
const boundTarget: LauncherTarget = {
  command: "/home/user/.t3/userdata/device/targets/t3-bound/agent-device",
  session: "t3-bound",
  bound: true,
  deviceId: IPHONE,
  ios: true,
  iosSimulator: true,
};
const bash = (command: string, output = "OK"): ShellCall => ({
  tool: "Bash",
  input: { command },
  output,
});
const errorCode = (
  targets: ReadonlyArray<LauncherTarget>,
  history: ReadonlyArray<ShellCall>,
  command: string,
) => agentDeviceSessionError(targets, agentDeviceSessions(targets, {}, history), command)?.code;

it("names the session on either ref: the bound launcher's own, or the shared one's --session", () => {
  const flags = `--platform ios --udid ${IPHONE} --config /home/user/.t3/userdata/device/hosts/x.json`;
  const sharedTargets = [shared("t3-a"), shared("t3-b")];
  // The shared launcher answers each session its flags name; without one, its own check (not
  // modelled) refuses before agent-device runs.
  const opened = [bash(`${sharedTargets[0]!.command} open com.acme.app ${flags} --session t3-a`)];
  assert.isUndefined(
    errorCode(
      sharedTargets,
      opened,
      `${sharedTargets[0]!.command} screenshot ${flags} --session t3-a`,
    ),
  );
  assert.equal(
    errorCode(
      sharedTargets,
      opened,
      `${sharedTargets[0]!.command} screenshot ${flags} --session=t3-b`,
    ),
    "SESSION_NOT_FOUND",
  );
  assert.isUndefined(errorCode(sharedTargets, [], `${sharedTargets[0]!.command} screenshot`));
  // The bound launcher needs no flags, and an explicit --session still wins.
  assert.equal(
    errorCode([boundTarget], [], `${boundTarget.command} screenshot`),
    "SESSION_NOT_FOUND",
  );
  assert.equal(errorCode([boundTarget], [], `${boundTarget.command} record start`), "INVALID_ARGS");
  const boundOpen = [bash(`${boundTarget.command} open`)];
  assert.isUndefined(errorCode([boundTarget], boundOpen, `${boundTarget.command} screenshot`));
  assert.equal(
    errorCode([boundTarget], boundOpen, `${boundTarget.command} record start /tmp/r.mp4`),
    "UNKNOWN",
  );
  assert.equal(
    errorCode([boundTarget], boundOpen, `${boundTarget.command} screenshot --session other`),
    "SESSION_NOT_FOUND",
  );
  // Without a selector, agent-device's record and close refuse a missing named session with
  // other text; that stays with the simulator.
  assert.isUndefined(
    errorCode(sharedTargets, [], `${sharedTargets[0]!.command} record start --session t3-a`),
  );
});

it("follows the session through aliases, compound calls, snapshots and whole-screen recordings", () => {
  const launcher = boundTarget.command;
  const after = (...history: ReadonlyArray<ShellCall>) =>
    agentDeviceSessions([boundTarget], {}, history).get("t3-bound");
  assert.deepEqual(after(bash(`AD=${launcher}; "$AD" open com.acme.app`)), { app: true });
  // A failed lone open starts nothing; an open in a failed compound call still counts.
  assert.isUndefined(after(bash(`${launcher} open com.acme.app`, "Exit code 1\nError (X): no")));
  assert.deepEqual(
    after(bash(`${launcher} open com.acme.app && ${launcher} press @e9`, "Exit code 1\nboom")),
    { app: true },
  );
  // Dead tails, remote agent-device and help start nothing.
  assert.isUndefined(after(bash(`false && ${launcher} open`, "Exit code 1")));
  assert.isUndefined(after(bash("ssh build-mac agent-device open com.acme.app")));
  assert.isUndefined(after(bash(`${launcher} help open`)));
  // agent-device publishes a session for a sessionless Android snapshot, without an app. An iOS
  // snapshot without an app fails and starts nothing.
  assert.isUndefined(after(bash(`${launcher} snapshot -i`)));
  const android = { ...boundTarget, ios: false, iosSimulator: false };
  assert.deepEqual(
    agentDeviceSessions([android], {}, [bash(`${launcher} snapshot -i`)]).get("t3-bound"),
    { app: false },
  );
  // A whole-screen recording holds a session only until it stops.
  const recording = bash(`${launcher} record start --scope device /tmp/r.mp4`);
  assert.deepEqual(after(recording), { app: false, recordingOnly: true });
  assert.isUndefined(errorCode([boundTarget], [recording], `${launcher} screenshot`));
  assert.isUndefined(after(recording, bash(`${launcher} record stop`)));
  assert.equal(
    errorCode(
      [boundTarget],
      [recording, bash(`${launcher} record stop`)],
      `${launcher} screenshot`,
    ),
    "SESSION_NOT_FOUND",
  );
  assert.deepEqual(after(bash(`${launcher} open`), bash(`${launcher} close`)), undefined);
});

it("follows the shared launcher's session through flags held in a variable or an array", () => {
  // Forms Sonnet used with the shared launcher in a live sample.
  const target = shared("t3-a");
  const flags = `--platform ios --udid ${IPHONE} --config /home/user/.t3/userdata/device/hosts/x.json --session t3-a`;
  const after = (history: ShellCall, targets = [target]) =>
    agentDeviceSessions(targets, {}, [history]).get("t3-a");
  const opened = bash(
    `AD=${target.command}; A="${flags}"; $AD open com.acme.app $A 2>&1 | tail -5; sleep 5; $AD snapshot -i $A 2>&1 | head -60`,
    "Opened: com.acme.app",
  );
  assert.deepEqual(after(opened), { app: true });
  const array = bash(`A=(${flags}); ${target.command} open "\${A[@]}" 2>&1 | head -60`);
  assert.deepEqual(after(array), { app: false });
  // With two sessions behind the shared launcher, unread flags name neither.
  assert.isUndefined(after(array, [target, shared("t3-b")]));
  // agent-device still sees no session for a plain command after a failed open in a variable.
  const failed = bash(
    `AD=${target.command}; A="${flags}"; $AD open $A`,
    "Exit code 1\nError (X): no",
  );
  assert.equal(
    errorCode([target], [failed], `${target.command} screenshot ${flags}`),
    "SESSION_NOT_FOUND",
  );
});

it.effect("starts sessions the world says prior turns opened, and rejects unknown devices", () =>
  Effect.gen(function* () {
    const testCase = deviceCase({
      world: { ...world, agentDeviceSessions: { [IPHONE]: { app: "com.acme.app" } } },
      priorTurns: [
        { role: "user", text: "Show me Settings on the iPhone on build-mac." },
        {
          role: "assistant",
          toolCalls: [
            { tool: "device_open", input: { hostId: MAC, deviceId: IPHONE }, result: "default" },
          ],
        },
      ],
    });
    const sample = makeSample(testCase, base);
    yield* withDevices(sample);
    const tools = sample.devices!;
    const [launcher = ""] = tools.launchers;
    assert.deepEqual([...tools.sessions(sample.shell).values()], [{ app: true }]);
    const call = { tool: "Bash", input: { command: "ls" } };
    assert.include(
      JSON.stringify(shellRequest(sample, call, "claude-haiku-5-5").messages),
      "is open with an app",
    );
    assert.isUndefined(tools.sessionError(sample.shell, `${launcher} record start /tmp/r.mp4`));
    const { devices = [], deviceHosts } = testCase.setup.world ?? {};
    const unknown = { devices, deviceHosts, agentDeviceSessions: { "not-a-device": {} } };
    const exit = yield* Effect.exit(makeDeviceTools(unknown, base.environment));
    assert.isTrue(exit._tag === "Failure");
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it.effect(
  "answers a shell mock first, then help, then the session error, before the simulator",
  () =>
    Effect.gen(function* () {
      const sample = makeSample(deviceCase({}), base);
      yield* withDevices(sample);
      const opened = yield* sample.devices!.call("device_open", { hostId: MAC, deviceId: IPHONE });
      const { command, targetArgs, session } = json(opened.text).agentDevice;
      const flags = session === undefined ? ` ${targetArgs.join(" ")}` : "";
      const told = () =>
        JSON.stringify(
          shellRequest(sample, { tool: "Bash", input: {} }, "claude-haiku-5-5").messages,
        );
      assert.include(told(), "has not started");
      assert.include(cannedOutput(sample, `${command} screenshot /tmp/a.png${flags}`), NO_SESSION);
      assert.match(cannedOutput(sample, `${command} help record`) ?? "", /^Usage:/);
      assert.isUndefined(cannedOutput(sample, `${command} open com.acme.app${flags}`));
      const outage = makeSample(
        deviceCase({
          shellMocks: [
            { match: "\\bagent-device\\b", output: "Exit code 1\nError (COMMAND_FAILED): down" },
          ],
        }),
        base,
      );
      yield* withDevices(outage);
      yield* outage.devices!.call("device_open", { hostId: MAC, deviceId: IPHONE });
      assert.include(cannedOutput(outage, `${command} screenshot /tmp/a.png${flags}`), "down");
      sample.shell.push({
        tool: "Bash",
        input: { command: `${command} open com.acme.app${flags}` },
        output: "Opened: com.acme.app",
      });
      assert.isUndefined(cannedOutput(sample, `${command} screenshot /tmp/a.png${flags}`));
      assert.include(told(), "is open with an app");
    }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it("keeps a redirection's descriptor out of the app an open names, on either launcher", () => {
  // Sol R10 B1: `open 2>&1` once read as `open 2`, an app the real shell never passes.
  const flags = `--platform ios --udid ${IPHONE} --config /home/user/.t3/userdata/device/hosts/x.json --session t3-a`;
  for (const [target, args] of [
    [shared("t3-a"), ` ${flags}`],
    [boundTarget, ""],
  ] as const) {
    for (const redirect of ["2>&1", "2>&1 | tail -5", "2>/dev/null"]) {
      const opened = [
        bash(`${target.command} open${args} ${redirect}`, `Opened: ${target.session}`),
      ];
      assert.deepEqual(
        agentDeviceSessions([target], {}, opened).get(target.session),
        { app: false },
        redirect,
      );
      assert.equal(
        errorCode([target], opened, `${target.command} record start /tmp/run.mp4${args}`),
        "UNKNOWN",
        redirect,
      );
    }
  }
});

it("follows opens the parser cannot prove ran, in calls that did not fail", () => {
  // Opus R10 B1(b): shapes from run 5, where `&&` before `;` leaves an open uncertain.
  const launcher = boundTarget.command;
  const after = (command: string, output = "Opened: com.acme.app") =>
    agentDeviceSessions([boundTarget], {}, [bash(command, output)]).get("t3-bound");
  assert.deepEqual(
    after(`mkdir -p /tmp/p && ${launcher} open com.acme.app 2>&1 | tail -3; echo done`),
    { app: true },
  );
  assert.deepEqual(after(`cd /tmp && ${launcher} open com.acme.app; ${launcher} snapshot -i`), {
    app: true,
  });
  // The launcher alias such a call sets, too, here and in later calls.
  assert.deepEqual(after(`mkdir -p /tmp/p && AD=${launcher}; $AD open com.acme.app`), {
    app: true,
  });
  assert.deepEqual(after(`mkdir -p /tmp/p && AD="${launcher}"; "\${AD}" open com.acme.app`), {
    app: true,
  });
  assert.deepEqual(
    agentDeviceSessions([boundTarget], {}, [
      bash(`cd /tmp && AD=${launcher}; echo ready`),
      bash("$AD open com.acme.app"),
    ]).get("t3-bound"),
    { app: true },
  );
  // A failed call credits only what certainly ran.
  assert.isUndefined(
    after(`mkdir -p /tmp/p && ${launcher} open com.acme.app; echo done`, "Exit code 1\nno"),
  );
  assert.isUndefined(
    after(`mkdir -p /tmp/p && AD=${launcher}; $AD open com.acme.app`, "Exit code 1\nno"),
  );
});

const SPARE_MAC = "cccccccc-cccc-4ccc-8ccc-cccccccccccc";
const SPARE_PHONE = "DDDDDDDD-DDDD-4DDD-8DDD-DDDDDDDDDDDD";
const twoMacs = {
  devices: [
    ...world.devices,
    { ...world.devices[0]!, hostId: SPARE_MAC, id: SPARE_PHONE, name: "Acme Spare iPhone" },
  ],
  deviceHosts: { ...world.deviceHosts, [SPARE_MAC]: "spare-mac" },
};
const deviceTools = (extra: object) =>
  makeDeviceTools(
    { ...twoMacs, ...extra } as Parameters<typeof makeDeviceTools>[0],
    base.environment,
  );

it.effect("lists a host whose discovery fails as T3 does: failed, with none of its devices", () =>
  Effect.gen(function* () {
    // F1's saved device_list: the hub answered, but its device list timed out.
    const failure = new DeviceOperationError({
      operation: "list",
      reason: "request_failed",
      cause: null,
    });
    const tools = yield* deviceTools({ deviceDiscoveryFailures: { [MAC]: failure } });
    const listed = json((yield* tools.call("device_list", {})).text);
    assert.deepEqual(listed.hostStatuses[MAC], {
      status: "failed",
      detail:
        "Device list failed: Could not communicate with device support. Try refreshing devices.",
    });
    assert.equal(listed.hostStatuses[SPARE_MAC].status, "ready");
    assert.deepEqual(
      listed.devices.map((device: { id: string }) => device.id),
      [SPARE_PHONE],
    );
    const opened = yield* tools.call("device_open", { hostId: MAC, deviceId: IPHONE });
    assert.isTrue(opened.isError);
    assert.include(opened.text, IPHONE);
    assert.isFalse(
      (yield* tools.call("device_open", { hostId: SPARE_MAC, deviceId: SPARE_PHONE })).isError,
    );
    // A failed host with no devices of its own still needs its label.
    const unlabeled = yield* Effect.exit(
      deviceTools({ deviceDiscoveryFailures: { "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee": failure } }),
    );
    assert.isTrue(unlabeled._tag === "Failure");
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it.effect("denies every device tool with T3's own error when agent device access is off", () =>
  Effect.gen(function* () {
    const tools = yield* deviceTools({ deviceAgentAccess: false });
    for (const [name, input] of [
      ["device_list", {}],
      ["device_open", { hostId: MAC, deviceId: IPHONE }],
      ["device_screenshot", {}],
      ["device_close", {}],
    ] as const) {
      const result = yield* tools.call(name, input);
      assert.isTrue(result.isError, name);
      // Refs before typed screenshot errors print their generic screenshot failure instead, and
      // later refs may add how to turn access on.
      const denied = result.text.startsWith(
        "Agent device access is turned off for this environment.",
      );
      assert.isTrue(
        denied || (name === "device_screenshot" && result.text === "Device screenshot failed."),
        `${name}: ${result.text}`,
      );
    }
    // T3 drops its device text for a thread without the capability, on refs that have it.
    assert.notInclude(t3SystemAppend(model, false), "## T3 Code devices");
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it.effect("reports an unreadable capture as T3 does: a successful 0×0 screenshot", () =>
  Effect.gen(function* () {
    const tools = yield* deviceTools({ deviceInvalidCapture: true });
    yield* tools.call("device_open", { hostId: MAC, deviceId: IPHONE });
    const shot = yield* tools.call("device_screenshot", {});
    assert.isFalse(shot.isError);
    assert.deepEqual(json(shot.text).screenshot, { mimeType: "image/png", width: 0, height: 0 });
    const sample = makeSample(
      deviceCase({ world: { ...world, deviceInvalidCapture: true } }),
      base,
    );
    yield* withDevices(sample);
    const told = JSON.stringify(shellRequest(sample, { tool: "Bash", input: {} }, model).messages);
    assert.include(told, "agent-device's own screenshot finds the PNG and is unaffected");
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it.effect("refuses an open on a device another thread's agent-device session holds", () =>
  Effect.gen(function* () {
    const tools = yield* deviceTools({ deviceOwners: { [IPHONE]: "acme-design-review" } });
    // T3 names the owner's session as it names every thread's.
    const owner = "t3-a062c547ef0b6bf8ee839b67";
    assert.deepEqual(tools.owners, [
      { deviceId: IPHONE, threadId: "acme-design-review", session: owner },
    ]);
    // T3 has no cross-thread gate: device_open succeeds, and device_list shows only this thread.
    const opened = json((yield* tools.call("device_open", { hostId: MAC, deviceId: IPHONE })).text);
    assert.deepEqual(json((yield* tools.call("device_list", {})).text).open, [
      { hostId: MAC, deviceId: IPHONE },
    ]);
    const { command, targetArgs, session: bound } = opened.agentDevice;
    const own: string = bound ?? targetArgs[targetArgs.indexOf("--session") + 1];
    const target = (session = own) =>
      bound === undefined
        ? targetArgs.map((arg: string) => (arg === own ? session : arg)).join(" ")
        : session === own
          ? ""
          : `--session ${session}`;
    const line = (args: string, session?: string) => `${command} ${args} ${target(session)}`.trim();
    const history: Array<ShellCall> = [];
    const answer = (args: string, session?: string) =>
      tools.sessionError(history, line(args, session)) ?? "";
    const inUse = `Error (DEVICE_IN_USE): Device is already in use by session "${owner}".\nHint: Run agent-device session list to inspect active sessions. To reuse this device, rerun the command with --session ${owner}. To open a new session on this device, first run agent-device close --session ${owner}.`;
    assert.include(
      answer("open com.acme.app"),
      `${inUse} To wait for the device to free up, run the same open with --wait <ms>.\nDiagnostic ID: `,
    );
    assert.include(
      answer("open --wait 5000"),
      `Error (DEVICE_IN_USE): Device is already in use by session "${owner}".\nHint: Waited 5000ms for this device and it stayed busy. Run agent-device session list`,
    );
    assert.notInclude(answer("open --wait 5000"), "--wait <ms>");
    // The hint's reuse works, in the other thread's session.
    assert.equal(answer("screenshot /tmp/a.png", owner), "");
    assert.equal(answer("open com.acme.app", owner), "");
    // A failed open starts nothing, in a compound call too.
    history.push({
      tool: "Bash",
      input: { command: `${line("open com.acme.app")} && ${line("screenshot /tmp/a.png")}` },
      output: "Exit code 1\nError (DEVICE_IN_USE): Device is already in use",
    });
    assert.deepEqual(
      [...tools.sessions(history)],
      [
        [own, undefined],
        [owner, { app: true }],
      ],
    );
    const sample = makeSample(
      deviceCase({ world: { ...twoMacs, deviceOwners: { [IPHONE]: "acme-design-review" } } }),
      base,
    );
    yield* withDevices(sample);
    const told = JSON.stringify(shellRequest(sample, { tool: "Bash", input: {} }, model).messages);
    assert.include(
      told,
      `${owner} (Acme iPhone, ${IPHONE}, on build-mac) belongs to another T3 thread (acme-design-review)`,
    );
    // Closing the owner's session frees the device.
    history.push({ tool: "Bash", input: { command: line("close", owner) }, output: "Closed" });
    assert.equal(answer("open com.acme.app"), "");
    assert.include(describeSessions(tools.sessions(history), tools.owners), "was closed");
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it.effect("leaves a free device free when another thread holds a different one", () =>
  Effect.gen(function* () {
    const tools = yield* deviceTools({ deviceOwners: { [IPHONE]: "acme-design-review" } });
    const opened = json(
      (yield* tools.call("device_open", { hostId: SPARE_MAC, deviceId: SPARE_PHONE })).text,
    );
    const { command, targetArgs, session } = opened.agentDevice;
    const flags = session === undefined ? ` ${targetArgs.join(" ")}` : "";
    assert.isUndefined(tools.sessionError([], `${command} open com.acme.app${flags}`));
    assert.include(
      tools.sessionError([], `${command} screenshot /tmp/a.png${flags}`) ?? "",
      "SESSION_NOT_FOUND",
    );
    // The local host always exists and holds none of the world's devices.
    assert.isFalse(
      (yield* tools.call("device_list", {})).text.includes(`"hostId":"${LOCAL_DEVICE_HOST_ID}"`),
    );
  }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

type Opened = { command: string; targetArgs: Array<string>; session?: string };
/** This ref's command line for a launcher: a bound one needs no flags; the shared one takes them. */
const commandLine = (opened: Opened, args: string, session?: string) => {
  const own = opened.session ?? opened.targetArgs[opened.targetArgs.indexOf("--session") + 1];
  if (opened.session !== undefined)
    return `${opened.command} ${args}${session === undefined ? "" : ` --session ${session}`}`;
  const flags = opened.targetArgs.map((arg) => (arg === own && session ? session : arg));
  return `${opened.command} ${args} ${flags.join(" ")}`;
};

it.effect(
  "tells the simulator each launcher's device, and routes DEVICE_IN_USE to the held one",
  () =>
    Effect.gen(function* () {
      // Opus R11-B3(a): in run 6 the simulator gave the free spare's plain open the owner's
      // DEVICE_IN_USE twice. It could not tell which device a flagless bound launcher drives.
      const owner = "t3-a062c547ef0b6bf8ee839b67";
      const sample = makeSample(
        deviceCase({ world: { ...twoMacs, deviceOwners: { [IPHONE]: "acme-design-review" } } }),
        base,
      );
      yield* withDevices(sample);
      const tools = sample.devices!;
      const open = (hostId: string, deviceId: string) =>
        Effect.map(
          tools.call("device_open", { hostId, deviceId }),
          (result): Opened => json(result.text).agentDevice,
        );
      const held = yield* open(MAC, IPHONE);
      const spare = yield* open(SPARE_MAC, SPARE_PHONE);
      const session = (opened: Opened) =>
        opened.session ?? opened.targetArgs[opened.targetArgs.indexOf("--session") + 1];
      const told = (command: string) =>
        String(
          shellRequest(sample, { tool: "Bash", input: { command } }, model).messages[0]?.content[0]
            ?.text,
        );
      // Run 6's history: the held device's plain open, refused without the simulator.
      const heldOpen = commandLine(held, "open com.acme.app --metro-port 8095");
      const refused = cannedOutput(sample, heldOpen) ?? "";
      assert.include(
        refused,
        `Error (DEVICE_IN_USE): Device is already in use by session "${owner}".`,
      );
      sample.shell.push({ tool: "Bash", input: { command: heldOpen }, output: refused });

      // The spare's plain open goes to the simulator, which now knows it drives the free spare.
      const spareOpen = commandLine(spare, "open com.acme.app --metro-port 8095");
      assert.isUndefined(cannedOutput(sample, spareOpen));
      const free = told(spareOpen);
      assert.include(
        free,
        `agent-device launchers T3's device_open returned: ${
          held.session === undefined
            ? `${held.command} (shared: each command's --udid or --serial and --session name its device and session)`
            : `${held.command} (drives Acme iPhone, ${IPHONE}, on build-mac, in session ${held.session}); ${spare.command} (drives Acme Spare iPhone, ${SPARE_PHONE}, on spare-mac, in session ${spare.session})`
        }`,
      );
      assert.include(
        free,
        `${session(held)} (Acme iPhone, ${IPHONE}, on build-mac) has not started; ${session(spare)} (Acme Spare iPhone, ${SPARE_PHONE}, on spare-mac) has not started; ${owner} (Acme iPhone, ${IPHONE}, on build-mac) belongs to another T3 thread (acme-design-review) and holds its device with an app open.`,
      );
      assert.include(
        free,
        `In the new call, \`${spareOpen}\` drives Acme Spare iPhone, ${SPARE_PHONE}, on spare-mac, which no other session holds: it prints no DEVICE_IN_USE.`,
      );
      assert.notInclude(free, "Error (DEVICE_IN_USE)");

      // A compound open of the held device gets agent-device's exact refusal, for that open only.
      const piped = commandLine(held, "open com.acme.app");
      const refusal = told(`${piped} 2>&1 | tail -5`);
      assert.include(
        refusal,
        `In the new call, \`${piped}\` drives Acme iPhone, ${IPHONE}, on build-mac, which session ${owner} holds: it fails with exit code 1, printing "Error (DEVICE_IN_USE): Device is already in use by session "${owner}"." and "Hint: Run agent-device session list to inspect active sessions. To reuse this device,`,
      );
      assert.notInclude(refusal, "no other session holds");
      // One call may try the held device, then fall back to the spare through an alias.
      const alias =
        spare.session === undefined
          ? `A=${spare.command}; "$A" open com.acme.app ${spare.targetArgs.join(" ")}`
          : `A=${spare.command}; "$A" open com.acme.app`;
      const both = told(`${piped} || echo busy; ${alias}`);
      assert.include(both, `which session ${owner} holds: it fails with exit code 1`);
      assert.include(
        both,
        `on spare-mac, which no other session holds: it prints no DEVICE_IN_USE`,
      );
      // An open in the other thread's own session is not refused, and gets no route.
      assert.notInclude(told(commandLine(held, "open com.acme.app", owner)), "In the new call");
      // An open after the same call closes the other thread's session finds the device free.
      const reopen = told(`${commandLine(held, "close", owner)}; ${piped}`);
      assert.include(
        reopen,
        `\`${piped}\` drives Acme iPhone, ${IPHONE}, on build-mac, which no other session holds: it prints no DEVICE_IN_USE`,
      );
      assert.notInclude(reopen, `which session ${owner} holds`);
      // Neither do commands other than open.
      assert.notInclude(
        told(`${commandLine(spare, "screenshot /tmp/a.png")} && echo ok`),
        "In the new call",
      );

      // A world where no other thread holds a device gets no route either.
      const alone = makeSample(deviceCase({}), base);
      yield* withDevices(alone);
      const own: Opened = json(
        (yield* alone.devices!.call("device_open", { hostId: MAC, deviceId: IPHONE })).text,
      ).agentDevice;
      const request = shellRequest(
        alone,
        { tool: "Bash", input: { command: `${commandLine(own, "open com.acme.app")} | tail -3` } },
        model,
      );
      assert.notInclude(JSON.stringify(request.messages), "In the new call");
      assert.include(
        JSON.stringify(request.messages),
        `${session(own)} (Acme iPhone, ${IPHONE}, on build-mac) has not started`,
      );
    }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
);

it("tells the simulator 0.21.31's --foreground and session list behaviour", () => {
  // Opus R11-B3(b): 0.21.31 (session2.js ys) refuses only an open --foreground with no app or URL.
  // Run 6's simulator refused `open <app> --foreground` in 9 base samples.
  assert.include(
    AGENT_DEVICE_SHELL,
    "open --foreground with no app or URL fails with exit code 1 when the command passes --udid or --device",
  );
  assert.include(AGENT_DEVICE_SHELL, "open <app> --foreground works.");
  // Run 6's simulator answered the DEVICE_IN_USE hint's `session list` with "Unknown command".
  assert.include(
    AGENT_DEVICE_SHELL,
    "session list prints, as JSON, the started sessions on the launcher's host, other threads' too",
  );
  // Neither is refused without the simulator.
  for (const args of ["open com.acme.app --foreground", "session list"]) {
    assert.isUndefined(
      agentDeviceSessionError(
        [boundTarget],
        new Map([["t3-bound", undefined]]),
        `${boundTarget.command} ${args}`,
      ),
      args,
    );
  }
});