@autifyhq/aximo-cli 0.15.0 → 0.17.0

package/dist/commands/mcp/server.test.js

@@ -24,14 +24,16 @@ async function connect() {
     };
 }
 describe("createMcpServer wiring", () => {
-    it("exposes all 36 tools through tools/list with valid JSON Schema", async () => {
+    it("exposes all 41 tools through tools/list with valid JSON Schema", async () => {
         const { client, cleanup } = await connect();
         try {
             const { tools } = await client.listTools();
             expect(tools.map((t) => t.name).sort()).toEqual([
                 "aximo_get_case",
+                "aximo_get_credits",
                 "aximo_get_session",
                 "aximo_wait_for_session",
+                "aximo_cancel_session",
                 "aximo_get_session_capture",
                 "aximo_get_session_snapshot",
                 "aximo_export_session_pdf",
@@ -65,6 +67,9 @@ describe("createMcpServer wiring", () => {
                 "aximo_list_plan_runs",
                 "aximo_get_plan_run",
                 "aximo_save_session_as_case",
+                "aximo_start_testbox",
+                "aximo_get_testbox",
+                "aximo_stop_testbox",
             ].sort());
             const timeline = tools.find((t) => t.name === "aximo_get_session_timeline");
             expect(timeline?.inputSchema?.required).toContain("sessionId");
@@ -98,7 +103,7 @@ describe("createMcpServer wiring", () => {
         const { client, cleanup } = await connect();
         try {
             const { tools } = await client.listTools();
-            expect(tools.length).toBe(36);
+            expect(tools.length).toBe(41);
             const result = await client.callTool({ name: "aximo_list_projects", arguments: {} });
             expect(result.isError).toBe(true);
             const content = result.content;

package/dist/commands/mcp/testbox-tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/mcp/testbox-tools.test.js

@@ -0,0 +1,278 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
+import { getTestboxConfigPath, getTestboxStatePath } from "../device/paths.js";
+import { fail, fakeDocker, ok, starts } from "../device/testbox/fake-docker.js";
+import { defineTools } from "./tools.js";
+let tempHome;
+beforeAll(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-mcp-testbox-"));
+    process.env["AXIMO_HOME"] = tempHome;
+    process.env["AXIMO_API_KEY"] = "test-key";
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    server.listen();
+});
+afterAll(() => {
+    delete process.env["AXIMO_HOME"];
+    delete process.env["AXIMO_API_KEY"];
+    delete process.env["AXIMO_BASE_URL"];
+    server.close();
+    rmSync(tempHome, { recursive: true, force: true });
+});
+beforeEach(() => {
+    rmSync(join(tempHome, "testbox"), { recursive: true, force: true });
+    mkdirSync(join(tempHome, "testbox"), { recursive: true });
+});
+afterEach(() => server.resetHandlers());
+function fakeClock() {
+    const start = 1_700_000_000_000;
+    let t = start;
+    return {
+        now: () => t,
+        sleep: async (ms) => {
+            t += ms;
+        },
+        elapsed: () => t - start,
+    };
+}
+function devices(list) {
+    server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ devices: list })));
+}
+function seedRegistration() {
+    writeFileSync(getTestboxConfigPath("default"), JSON.stringify({
+        deviceId: "dev-1",
+        deviceToken: "tok",
+        name: "mac-testbox-abcd",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        baseUrl: TEST_BASE_URL,
+    }));
+}
+function seedState(state) {
+    writeFileSync(getTestboxStatePath("default"), JSON.stringify({ startedAt: new Date().toISOString(), pid: process.pid, ...state }));
+}
+const config = {
+    image: "ghcr.io/autifyhq/aximo-testbox:0.1.0",
+    ports: "3000",
+    blockHosts: [],
+    network: "bridge",
+    novncPort: 6080,
+    screen: "1280x720",
+};
+function runningBox(docker) {
+    docker.on(starts("inspect"), ok(`true|${config.image}|${JSON.stringify({ "aximo.testbox": "default", "aximo.testbox.config": JSON.stringify(config) })}\n`));
+}
+function toolsWithDetachedUp(docker = fakeDocker(), detachedUp = {}) {
+    const spawned = [];
+    const clock = fakeClock();
+    const deps = {
+        testbox: {
+            docker: docker.run,
+            clock,
+            spawn: (args) => {
+                spawned.push(args);
+                if (detachedUp.writesPullingState ?? true)
+                    seedState({ phase: "pulling" });
+                detachedUp.onSpawn?.();
+                return 4242;
+            },
+        },
+    };
+    const all = defineTools(deps);
+    const tool = (name) => {
+        const t = all.find((x) => x.name === name);
+        if (!t)
+            throw new Error(`tool ${name} not found`);
+        return t;
+    };
+    const payload = (result) => JSON.parse(result.content[0].text);
+    return { tool, payload, spawned, clock };
+}
+describe("aximo_start_testbox", () => {
+    it("spawns a detached up with the flags and reports the pull in progress", async () => {
+        devices([]);
+        const { tool, payload, spawned } = toolsWithDetachedUp();
+        const result = await tool("aximo_start_testbox").handler({
+            ports: "5173",
+            blockHosts: ["prod.example.com"],
+            startUrl: "http://localhost:5173/",
+            screen: "1920x1080",
+            timeoutSeconds: 5,
+        });
+        expect(spawned).toEqual([
+            [
+                "device",
+                "testbox",
+                "up",
+                "--no-wait",
+                "--name",
+                "default",
+                "--ports",
+                "5173",
+                "--block-hosts",
+                "prod.example.com",
+                "--start-url",
+                "http://localhost:5173/",
+                "--screen",
+                "1920x1080",
+            ],
+        ]);
+        expect(result.isError).toBeFalsy();
+        expect(payload(result)).toMatchObject({
+            ready: false,
+            state: "pulling",
+            hint: expect.stringContaining("aximo_get_testbox"),
+        });
+    });
+    it("does not spawn a second up while one is still running", async () => {
+        devices([]);
+        seedState({ phase: "starting" });
+        const { tool, payload, spawned } = toolsWithDetachedUp();
+        const result = await tool("aximo_start_testbox").handler({ timeoutSeconds: 3 });
+        expect(spawned).toEqual([]);
+        expect(payload(result)).toMatchObject({ ready: false, state: "starting" });
+    });
+    it("forgets a previous run's error before spawning, instead of reporting it as this run's", async () => {
+        devices([]);
+        seedState({ phase: "error", pid: 1, lastError: "old failure" });
+        const { tool, payload, spawned } = toolsWithDetachedUp();
+        const result = payload(await tool("aximo_start_testbox").handler({ timeoutSeconds: 3 }));
+        expect(spawned).toHaveLength(1);
+        expect(result["state"]).toBe("pulling");
+        expect(result["lastError"]).toBeUndefined();
+    });
+    it("returns ready with the device id once the box is online", async () => {
+        devices([{ id: "dev-1", name: "mac-testbox-abcd", status: "online" }]);
+        seedRegistration();
+        const docker = fakeDocker();
+        const { tool, payload, spawned } = toolsWithDetachedUp(docker, {
+            writesPullingState: false,
+            onSpawn: () => runningBox(docker),
+        });
+        const result = payload(await tool("aximo_start_testbox").handler({ timeoutSeconds: 3 }));
+        expect(spawned).toHaveLength(1);
+        expect(result).toMatchObject({
+            ready: true,
+            state: "online",
+            container: "running",
+            agent: "running",
+            userDeviceId: "dev-1",
+            deviceName: "mac-testbox-abcd",
+            deviceStatus: "online",
+            liveViewUrl: "http://127.0.0.1:6080/vnc.html?autoconnect=1&resize=scale&password=pw123",
+            ports: [{ port: 3000, reachable: true }],
+            hint: expect.stringContaining("userDeviceId"),
+        });
+    });
+    it("does not touch a box that is already online unless asked to reconfigure it", async () => {
+        devices([{ id: "dev-1", name: "mac-testbox-abcd", status: "online" }]);
+        seedRegistration();
+        const docker = fakeDocker();
+        runningBox(docker);
+        const { tool, payload, spawned } = toolsWithDetachedUp(docker, { writesPullingState: false });
+        expect(payload(await tool("aximo_start_testbox").handler({}))["ready"]).toBe(true);
+        expect(spawned).toEqual([]);
+        await tool("aximo_start_testbox").handler({ ports: "5173" });
+        expect(spawned).toHaveLength(1);
+    });
+    it("returns within timeoutSeconds even when the detached up never writes state", async () => {
+        devices([]);
+        const { tool, payload, clock } = toolsWithDetachedUp(fakeDocker(), {
+            writesPullingState: false,
+        });
+        const result = payload(await tool("aximo_start_testbox").handler({ timeoutSeconds: 7 }));
+        expect(result["state"]).toBe("down");
+        expect(clock.elapsed()).toBeLessThanOrEqual(7_000 + 3_000);
+    });
+    it("is a tool error with the install link when Docker is missing", async () => {
+        devices([]);
+        const docker = fakeDocker();
+        docker.on(starts("info"), () => {
+            throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
+        const { tool, payload, spawned } = toolsWithDetachedUp(docker);
+        const result = await tool("aximo_start_testbox").handler({});
+        expect(result.isError).toBe(true);
+        expect(payload(result)["error"]).toContain("https://docs.docker.com/get-docker/");
+        expect(spawned).toEqual([]);
+    });
+    it("rejects a name that is not a valid box name", async () => {
+        devices([]);
+        const { tool } = toolsWithDetachedUp();
+        const result = await tool("aximo_start_testbox").handler({ name: "../x" });
+        expect(result.isError).toBe(true);
+    });
+});
+describe("aximo_get_testbox and aximo_stop_testbox", () => {
+    it("get reports down with the start hint when nothing runs", async () => {
+        devices([]);
+        const { tool, payload } = toolsWithDetachedUp();
+        expect(payload(await tool("aximo_get_testbox").handler({}))).toEqual({
+            ready: false,
+            state: "down",
+            name: "default",
+            container: "absent",
+            hint: "Not running. Call aximo_start_testbox.",
+        });
+    });
+    it("get waits up to timeoutSeconds while the box is still connecting", async () => {
+        devices([{ id: "dev-1", name: "mac-testbox-abcd", status: "offline" }]);
+        seedRegistration();
+        const docker = fakeDocker();
+        runningBox(docker);
+        const { tool, payload, clock } = toolsWithDetachedUp(docker);
+        const result = payload(await tool("aximo_get_testbox").handler({ timeoutSeconds: 7 }));
+        expect(result).toMatchObject({
+            ready: false,
+            state: "connecting",
+            hint: expect.stringContaining("aximo_get_testbox"),
+        });
+        expect(clock.elapsed()).toBe(6_000);
+    });
+    it("get surfaces a failed detached up as an error with its cause", async () => {
+        devices([]);
+        seedState({
+            phase: "error",
+            pid: 1,
+            lastError: "Could not pull ghcr.io/autifyhq/aximo-testbox:0.1.0: denied",
+        });
+        const { tool, payload } = toolsWithDetachedUp();
+        expect(payload(await tool("aximo_get_testbox").handler({}))).toMatchObject({
+            state: "error",
+            lastError: expect.stringContaining("Could not pull"),
+            hint: expect.stringContaining("aximo_start_testbox"),
+        });
+    });
+    it("get passes the agent's last message through", async () => {
+        devices([{ id: "dev-1", name: "mac-testbox-abcd", status: "offline" }]);
+        seedRegistration();
+        const docker = fakeDocker();
+        runningBox(docker);
+        docker.on((args) => args.includes("cat") && args.includes("/run/aximo/agent.status"), ok("Auth failed. Re-register with: aximo device register\n"));
+        const { tool, payload } = toolsWithDetachedUp(docker);
+        expect(payload(await tool("aximo_get_testbox").handler({}))["agentStatus"]).toContain("Auth failed");
+    });
+    it("stop removes the container and nothing else", async () => {
+        devices([]);
+        const docker = fakeDocker();
+        runningBox(docker);
+        const { tool, payload } = toolsWithDetachedUp(docker);
+        expect(payload(await tool("aximo_stop_testbox").handler({}))).toEqual({
+            name: "default",
+            removed: true,
+        });
+        expect(docker.find("rm", "-f", "aximo-testbox")).toHaveLength(1);
+        expect(docker.find("volume")).toHaveLength(0);
+    });
+    it("maps a Docker failure to a tool error", async () => {
+        devices([]);
+        const docker = fakeDocker();
+        runningBox(docker);
+        docker.on(starts("rm"), fail("permission denied"));
+        const { tool, payload } = toolsWithDetachedUp(docker);
+        const result = await tool("aximo_stop_testbox").handler({});
+        expect(result.isError).toBe(true);
+        expect(payload(result)["error"]).toContain("permission denied");
+    });
+});

package/dist/commands/mcp/tools.d.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { type ClientDeps } from "../../client.js";
+import { type TestboxDeps } from "../device/testbox/box.js";
+import { type DetachedSpawner } from "../device/testbox/self-command.js";
 interface ToolResult {
     content: Array<{
         type: "text";
@@ -7,6 +9,11 @@ interface ToolResult {
     }>;
     isError?: boolean;
 }
+export interface ToolDeps extends ClientDeps {
+    testbox?: TestboxDeps & {
+        spawn?: DetachedSpawner;
+    };
+}
 export interface Tool<TInput extends z.ZodRawShape = z.ZodRawShape> {
     name: string;
     title: string;
@@ -14,5 +21,5 @@ export interface Tool<TInput extends z.ZodRawShape = z.ZodRawShape> {
     inputSchema: TInput;
     handler: (input: z.infer<z.ZodObject<TInput>>) => Promise<ToolResult>;
 }
-export declare function defineTools(deps?: ClientDeps): Tool[];
+export declare function defineTools(deps?: ToolDeps): Tool[];
 export {};

package/dist/commands/mcp/tools.js

@@ -1,9 +1,16 @@
 import { isAbsolute } from "node:path";
 import { z } from "zod";
 import { request } from "../../client.js";
-import { WAIT_DEFAULT_SECONDS, WAIT_MAX_SECONDS, waitForSession } from "./wait.js";
+import { getTestboxLogPath } from "../device/paths.js";
+import { clearState, downTestbox, pendingUp, readState, statusTestbox, waitForTestbox, } from "../device/testbox/box.js";
+import { BOX_NAME_RE, validateBoxName } from "../device/testbox/container.js";
+import { isDockerProblem, preflightDocker, runDocker } from "../device/testbox/docker.js";
+import { TestboxError } from "../device/testbox/errors.js";
+import { spawnDetached } from "../device/testbox/self-command.js";
+import { listUserDevices } from "../device/user-devices.js";
+import { realClock, WAIT_DEFAULT_SECONDS, WAIT_MAX_SECONDS, waitForSession } from "./wait.js";
 import { exportSession, SESSION_EXPORT_LOCALES, } from "../../session-export.js";
-import { ARCHIVE_FIRST_HINT, featureHint, isArchiveFirstConflict, withDetails, } from "../../errors.js";
+import { ARCHIVE_FIRST_HINT, creditHint, featureHint, isArchiveFirstConflict, withDetails, } from "../../errors.js";
 function ok(payload) {
     return {
         content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
@@ -32,7 +39,9 @@ async function call(fn) {
         if (status === 401)
             return err("Unauthorized: check AXIMO_API_KEY", "Run `aximo configure`.");
         if (status === 403) {
-            return err(message || "Forbidden", featureHint(e.message, details) ?? "API key may not have access to this resource.");
+            return err(message || "Forbidden", featureHint(e.message, details) ??
+                creditHint(e.message) ??
+                "API key may not have access to this resource.");
         }
         if (status === 404)
             return err(message || "Not found");
@@ -99,7 +108,48 @@ function exportSessionTo(input, deps) {
     }
     return exportSession(input, deps);
 }
+const TESTBOX_HINTS = {
+    online: "Pass userDeviceId as the device for aximo_create_session or aximo_run_case, and give the user liveViewUrl to watch the run.",
+    pulling: "Still starting (a first start pulls a ~1 GB image). Call aximo_get_testbox with timeoutSeconds: 45 until ready.",
+    starting: "Still starting. Call aximo_get_testbox with timeoutSeconds: 45 until ready.",
+    connecting: "The box is up and the agent is connecting. Call aximo_get_testbox with timeoutSeconds: 45 until ready.",
+    down: "Not running. Call aximo_start_testbox.",
+    error: "Fix the cause in lastError, then call aximo_start_testbox again.",
+};
+function testboxReport(status) {
+    return {
+        ready: status.state === "online",
+        state: status.state,
+        name: status.name,
+        container: status.container,
+        ...(status.agent ? { agent: status.agent } : {}),
+        ...(status.device
+            ? {
+                userDeviceId: status.device.userDeviceId,
+                deviceName: status.device.name,
+                deviceStatus: status.device.status,
+            }
+            : {}),
+        ...(status.liveViewUrl ? { liveViewUrl: status.liveViewUrl } : {}),
+        ...(status.ports ? { ports: status.ports } : {}),
+        ...(status.agentStatus ? { agentStatus: status.agentStatus } : {}),
+        ...(status.lastError ? { lastError: status.lastError } : {}),
+        hint: TESTBOX_HINTS[status.state],
+    };
+}
+const testboxNameSchema = z
+    .string()
+    .regex(BOX_NAME_RE)
+    .optional()
+    .describe("Box name, only when running more than one box on this machine.");
+// The detached `up` normally writes its first state within a second; after this
+// the tool reads Docker directly.
+const START_SETTLE_MS = 10_000;
 export function defineTools(deps = {}) {
+    const testbox = { ...deps, ...deps.testbox };
+    const spawnUp = deps.testbox?.spawn ?? spawnDetached;
+    const clock = testbox.clock ?? realClock;
+    const secondsLeft = (deadline) => Math.max(0, Math.round((deadline - clock.now()) / 1000));
     return [
         {
             name: "aximo_list_projects",
@@ -111,6 +161,24 @@ export function defineTools(deps = {}) {
                 return res;
             }),
         },
+        {
+            name: "aximo_get_credits",
+            title: "Get credit balance",
+            description: "Get your organization's credit balance for the current period: granted, used and remaining, in the unit named by creditUnit (legacy or platform). onDemandRemaining is on-demand credit still available once remaining runs out, so remaining can be 0 while runs still start. blocked is true when a new session or run would be refused for lack of credits; metered is false when credits are not enforced. Check it before starting runs to warn when the balance is low.",
+            inputSchema: {},
+            handler: async () => call(async () => {
+                try {
+                    return await request("/api/organizations/credits", {}, deps);
+                }
+                catch (e) {
+                    // Servers before the route answer with Next.js's HTML 404 page.
+                    if (e.status === 404) {
+                        throw Object.assign(new Error("This Aximo server does not support the credit balance yet"), { status: 404 });
+                    }
+                    throw e;
+                }
+            }),
+        },
         {
             name: "aximo_list_devices",
             title: "List Device Farm devices",
@@ -131,21 +199,7 @@ export function defineTools(deps = {}) {
             title: "List registered BYOD devices",
             description: "List the BYOD (bring-your-own) desktop and mobile devices registered with `aximo device register` by the owner of this API key — other members' devices are not included. Each device's id is the userDeviceId to pass in a case's apiDesktopConfig or multi-device local entries (aximo_update_case) and in per-run overrides. status shows whether the device is online. Returns 404 when BYOD is not enabled for the organization.",
             inputSchema: {},
-            handler: async () => call(async () => {
-                try {
-                    return await request("/api/devices/user", {}, deps);
-                }
-                catch (e) {
-                    // The route answers a bare 404 when the org has no BYOD feature.
-                    if (e.status === 404) {
-                        throw Object.assign(new Error("BYOD is not enabled for this organization"), {
-                            status: 403,
-                            details: { feature: "byodEnabled" },
-                        });
-                    }
-                    throw e;
-                }
-            }),
+            handler: async () => call(async () => ({ devices: await listUserDevices(deps) })),
         },
         {
             name: "aximo_list_uploads",
@@ -498,6 +552,17 @@ export function defineTools(deps = {}) {
                 return await request("/api/sessions", { method: "POST", body }, deps);
             }),
         },
+        {
+            name: "aximo_cancel_session",
+            title: "Cancel session",
+            description: "Cancel a queued or running session: it moves to terminated and stops on its device at the next step, including a BYOD session waiting for an offline device. Use it to stop a run that went wrong instead of letting it spend credits. A session that has already finished returns a conflict error and is left unchanged.",
+            inputSchema: {
+                sessionId: z.string().uuid(),
+            },
+            handler: async ({ sessionId }) => call(async () => {
+                return await request(`/api/sessions/${encodeURIComponent(sessionId)}/cancel`, { method: "POST" }, deps);
+            }),
+        },
         {
             name: "aximo_create_plan",
             title: "Create test plan",
@@ -614,7 +679,7 @@ export function defineTools(deps = {}) {
         {
             name: "aximo_run_plan",
             title: "Run test plan",
-            description: "Start a run of a test plan (all its cases) and return the new planRunId, totalCases, and the effective executionMode. The plan must be apiEnabled (aximo_get_plan shows this). All fields except planId are per-run overrides of the plan's stored settings: omit them to run with the saved defaults. Poll aximo_get_plan_run with the returned planRunId to follow the run; wait at least 5 seconds between polls.",
+            description: "Start a run of a test plan (all its cases) and return the new planRunId, totalCases, and the effective executionMode. The plan must be apiEnabled (aximo_get_plan shows this). All fields except planId and mobileConfig are per-run overrides of the plan's stored settings: omit them to run with the saved defaults. mobileConfig is only a fallback (see its description). Poll aximo_get_plan_run with the returned planRunId to follow the run; wait at least 5 seconds between polls.",
             inputSchema: {
                 planId: z.string().uuid(),
                 model: z
@@ -638,7 +703,7 @@ export function defineTools(deps = {}) {
                         .describe("Takes precedence over the single-app uploadArn/uploadType/appName fields."),
                 })
                     .optional()
-                    .describe("Device + app for the plan's mobile cases; overrides the plan's stored config."),
+                    .describe("Fallback device + app, used only for mobile cases with no device saved on the plan or the case. A saved device always wins and keeps its own app; to run on another device, save it on the case or the plan."),
                 desktopConfig: z
                     .object({
                     devices: z.array(z.object({ userDeviceId: z.string().uuid() })).min(1),
@@ -724,5 +789,91 @@ export function defineTools(deps = {}) {
                 return await request(`/api/sessions/${encodeURIComponent(sessionId)}/save-as-case`, { method: "POST", body }, deps);
             }),
         },
+        // Local tools: these run Docker on the machine hosting the MCP server.
+        {
+            name: "aximo_start_testbox",
+            title: "Start the testbox",
+            description: "Start the testbox: a sandboxed Chromium in Docker on this machine, registered as a local (BYOD) device, whose localhost is this machine's localhost. Use it to test an app running locally without taking over the user's screen. Idempotent: a box that is already up is reused, and calling again never starts a second one. Returns within timeoutSeconds with ready=true and the userDeviceId once the device is online, or ready=false with the current state; then poll with aximo_get_testbox (read-only) rather than calling this again. Requires Docker; the error says how to install it. The user signs into the app through liveViewUrl if needed, and keeps that tab to watch runs.",
+            inputSchema: {
+                name: testboxNameSchema,
+                ports: z
+                    .string()
+                    .regex(/^[0-9, -]+$/)
+                    .optional()
+                    .describe("Host ports the app serves on, e.g. 3000 or 3000,5173-5180. Default 3000."),
+                blockHosts: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Hosts the browser must refuse, e.g. the production domain. A browser rule matched by name, not a network boundary."),
+                startUrl: z.string().url().optional().describe("Page the browser opens on start."),
+                screen: z
+                    .string()
+                    .regex(/^\d{3,4}x\d{3,4}$/)
+                    .optional()
+                    .describe("Virtual screen size WIDTHxHEIGHT. Default 1280x720; use 1920x1080 only for a layout that needs a wide viewport."),
+                timeoutSeconds: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(WAIT_MAX_SECONDS)
+                    .optional()
+                    .describe(`Seconds to wait before returning. Default ${WAIT_DEFAULT_SECONDS}.`),
+            },
+            handler: async ({ name, ports, blockHosts, startUrl, screen, timeoutSeconds }) => call(async () => {
+                const deadline = clock.now() + (timeoutSeconds ?? WAIT_DEFAULT_SECONDS) * 1000;
+                const boxName = validateBoxName(name);
+                const docker = await preflightDocker(testbox.docker ?? runDocker);
+                if (isDockerProblem(docker))
+                    throw new TestboxError(docker.message);
+                const current = await statusTestbox(boxName, testbox);
+                const reconfigure = ports !== undefined ||
+                    blockHosts !== undefined ||
+                    startUrl !== undefined ||
+                    screen !== undefined;
+                if (current.state === "online" && !reconfigure)
+                    return testboxReport(current);
+                if (!pendingUp(boxName, clock)) {
+                    // A previous run's error would otherwise be read as this run's result.
+                    clearState(boxName);
+                    const args = ["device", "testbox", "up", "--no-wait", "--name", boxName];
+                    if (ports)
+                        args.push("--ports", ports);
+                    if (blockHosts?.length)
+                        args.push("--block-hosts", blockHosts.join(","));
+                    if (startUrl)
+                        args.push("--start-url", startUrl);
+                    if (screen)
+                        args.push("--screen", screen);
+                    spawnUp(args, getTestboxLogPath(boxName));
+                    const settleBy = Math.min(deadline, clock.now() + START_SETTLE_MS);
+                    while (readState(boxName) === null && clock.now() < settleBy)
+                        await clock.sleep(500);
+                }
+                return testboxReport(await waitForTestbox(boxName, secondsLeft(deadline), testbox));
+            }),
+        },
+        {
+            name: "aximo_get_testbox",
+            title: "Get testbox status",
+            description: "Read-only. Container, agent and device state of the testbox, which mirrored ports answer from inside the box, and the live-view link. With timeoutSeconds it waits up to that long (max 90) for the box to come online and returns whatever the state is then: pulling, starting, connecting, online, down or error. A first start pulls the image and can take a few minutes, so keep calling until ready=true. Check ports before a run: an unreachable port means the app is not listening, not that the test failed.",
+            inputSchema: {
+                name: testboxNameSchema,
+                timeoutSeconds: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .max(WAIT_MAX_SECONDS)
+                    .optional()
+                    .describe("Seconds to wait for the box to come online. Default 0: answer at once."),
+            },
+            handler: async ({ name, timeoutSeconds }) => call(async () => testboxReport(await waitForTestbox(name, timeoutSeconds ?? 0, testbox))),
+        },
+        {
+            name: "aximo_stop_testbox",
+            title: "Stop the testbox",
+            description: "Stop and remove the testbox container. The browser profile (sign-ins) and the device registration are kept, so the next aximo_start_testbox is quick. Dropping the profile or the registration is a human action: `aximo device testbox reset` / `prune` in a terminal.",
+            inputSchema: { name: testboxNameSchema },
+            handler: async ({ name }) => call(() => downTestbox(name, testbox)),
+        },
     ];
 }