@autifyhq/aximo-cli 0.14.0 → 0.16.0

package/dist/commands/mcp/tools.js

@@ -1,6 +1,16 @@
+import { isAbsolute } from "node:path";
 import { z } from "zod";
 import { request } from "../../client.js";
-import { ARCHIVE_FIRST_HINT, featureHint, isArchiveFirstConflict, withDetails, } from "../../errors.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, creditHint, featureHint, isArchiveFirstConflict, withDetails, } from "../../errors.js";
 function ok(payload) {
     return {
         content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
@@ -29,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");
@@ -50,7 +62,7 @@ async function call(fn) {
         if (typeof status === "number")
             return err(`HTTP ${status}: ${message}`);
         if (e.message.startsWith("No API key configured")) {
-            return err("API key not configured", "Run `aximo configure` and restart the MCP server.");
+            return err("API key not configured", "Run `aximo configure`, then call the tool again.");
         }
         const cause = e.cause;
         const networkCode = cause?.code;
@@ -80,7 +92,64 @@ const runAppsSchema = z
     bundleId: z.string().optional(),
 }))
     .max(3);
+const exportOutputPathSchema = z
+    .string()
+    .min(1)
+    .describe("Absolute file path to write, e.g. /tmp/result.pdf. Parent directories are created and an existing file is replaced.");
+const exportLocaleSchema = z
+    .enum(SESSION_EXPORT_LOCALES)
+    .optional()
+    .describe("Language of the report labels. Default en.");
+// The MCP server's working directory is wherever the client launched it, so a
+// relative path would land somewhere the caller cannot predict.
+function exportSessionTo(input, deps) {
+    if (!isAbsolute(input.outputPath)) {
+        throw new Error("outputPath must be an absolute path");
+    }
+    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",
@@ -112,21 +181,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",
@@ -165,6 +220,22 @@ export function defineTools(deps = {}) {
                 return await request(`/api/sessions/${encodeURIComponent(sessionId)}`, {}, deps);
             }),
         },
+        {
+            name: "aximo_wait_for_session",
+            title: "Wait for session",
+            description: "Wait for a session to finish and return within timeoutSeconds whatever its state. Polls every 5 seconds. Returns done=true with the final session (status succeeded, failed, terminated, error, or archived), or done=false with the current status so you can call again. Default 45 seconds, maximum 90: most MCP clients cut a tool call off at 60, so only go above that where the client has no limit. A multi-minute run is a handful of these calls.",
+            inputSchema: {
+                sessionId: z.string().uuid(),
+                timeoutSeconds: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(WAIT_MAX_SECONDS)
+                    .optional()
+                    .describe(`Seconds to wait before returning. Default ${WAIT_DEFAULT_SECONDS}.`),
+            },
+            handler: async ({ sessionId, timeoutSeconds }) => call(() => waitForSession(sessionId, timeoutSeconds ?? WAIT_DEFAULT_SECONDS, deps)),
+        },
         {
             name: "aximo_get_session_messages",
             title: "Get session messages",
@@ -240,6 +311,28 @@ export function defineTools(deps = {}) {
                 return await request(`/api/sessions/${encodeURIComponent(sessionId)}/snapshots/${encodeURIComponent(snapshotId)}`, {}, deps);
             }),
         },
+        {
+            name: "aximo_export_session_pdf",
+            title: "Export session result as PDF",
+            description: "Download a session's test result report (overview, result summary, and every step with its screenshot) as a PDF and write it to outputPath on this machine. Returns the written path and size, not the file bytes. A running session exports the steps recorded so far. Sessions over 500 steps return HTTP 413: export the screenshots archive instead. For a plan run, take each case's sessionId from aximo_get_plan_run.",
+            inputSchema: {
+                sessionId: z.string().uuid(),
+                outputPath: exportOutputPathSchema,
+                locale: exportLocaleSchema,
+            },
+            handler: async ({ sessionId, outputPath, locale }) => call(() => exportSessionTo({ sessionId, format: "pdf", outputPath, locale }, deps)),
+        },
+        {
+            name: "aximo_export_session_screenshots",
+            title: "Export session screenshots as ZIP",
+            description: "Download a ZIP of every step screenshot of a session (screenshots/step-001.png or .jpg, as stored) plus metadata.csv (one row per step: screenshot file, AI thoughts, tool, details) and session.csv, and write it to outputPath on this machine. Returns the written path and size, not the file bytes. The download is verified complete before success is reported; a truncated archive is deleted and returned as an error. A session with no screenshots returns HTTP 409.",
+            inputSchema: {
+                sessionId: z.string().uuid(),
+                outputPath: exportOutputPathSchema,
+                locale: exportLocaleSchema,
+            },
+            handler: async ({ sessionId, outputPath, locale }) => call(() => exportSessionTo({ sessionId, format: "screenshots", outputPath, locale }, deps)),
+        },
         {
             name: "aximo_list_cases",
             title: "List test cases",
@@ -398,6 +491,60 @@ export function defineTools(deps = {}) {
                 return await request(`/api/triggers/cases/${encodeURIComponent(caseId)}/run`, { method: "POST", body }, deps);
             }),
         },
+        {
+            name: "aximo_create_session",
+            title: "Create session",
+            description: "Start an agent session from a prompt, without saving a test case. Consumes organization credits. Returns the new sessionId; follow it with aximo_wait_for_session. Runs in Aximo's cloud browser unless userDeviceId names a registered local device (aximo_list_user_devices); for an app on localhost use a local device and put the app's URL in the prompt itself.",
+            inputSchema: {
+                title: z.string().min(1).max(500).describe("Shown in the session list."),
+                prompt: z
+                    .string()
+                    .min(1)
+                    .max(10000)
+                    .describe("What to test, in plain language: the steps and what counts as a pass."),
+                projectId: z.string().uuid(),
+                platform: z.enum(["desktop", "android", "ios"]).optional().describe("Default desktop."),
+                model: z
+                    .string()
+                    .optional()
+                    .describe("Agent model (e.g. 'sonnet', 'haiku', 'auto'). Server-validated."),
+                startUrl: z
+                    .string()
+                    .url()
+                    .optional()
+                    .describe("Web sessions on cloud browsers: first URL to open."),
+                tags: z.array(z.string().max(64)).max(10).optional(),
+                hostnameOverrideIds: z.array(z.string().uuid()).optional(),
+                userDeviceId: z
+                    .string()
+                    .uuid()
+                    .optional()
+                    .describe("A user-owned (BYOD) device id; runs there instead of the cloud."),
+                deviceArn: z.string().optional().describe("Mobile: encrypted Device Farm device token."),
+                deviceName: z.string().optional(),
+                uploadArn: z.string().optional().describe("Mobile: encrypted app upload token."),
+                uploadType: z.enum(["own_app", "existing", "sample"]).optional(),
+                appName: z.string().optional(),
+                bundleId: z.string().optional(),
+                apps: runAppsSchema
+                    .optional()
+                    .describe("Mobile multi-app sessions: up to 3 apps; takes precedence over the single-app fields."),
+            },
+            handler: async (body) => call(async () => {
+                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",
@@ -600,7 +747,7 @@ export function defineTools(deps = {}) {
         {
             name: "aximo_get_plan_run",
             title: "Get plan run status",
-            description: "Get the overall status and per-case breakdown of a plan run (from aximo_list_plan_runs, or the planRunId returned when a run was triggered). Poll this to observe a run in progress; wait at least 5 seconds between polls. A run's status reflects execution, not the test verdict: a run can complete with failedCases > 0, so read passedCases/failedCases and the per-case statuses to judge outcomes.",
+            description: "Get the overall status and per-case breakdown of a plan run (from aximo_list_plan_runs, or the planRunId returned when a run was triggered). Poll this to observe a run in progress; wait at least 5 seconds between polls. A run's status reflects execution, not the test verdict: a run can complete with failedCases > 0, so read passedCases/failedCases and the per-case statuses to judge outcomes. Each case carries its sessionId (null until its session is created) for aximo_get_session and the export tools.",
             inputSchema: {
                 planId: z.string().uuid(),
                 planRunId: z.string().uuid(),
@@ -624,5 +771,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)),
+        },
     ];
 }

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

@@ -1,6 +1,9 @@
-import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { z } from "zod";
-import { ARCHIVE_FIRST_HINT, handleApiError, isArchiveFirstConflict } from "../../errors.js";
+import { ARCHIVE_FIRST_HINT, CREDIT_HINT, handleApiError, isArchiveFirstConflict, } from "../../errors.js";
 import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
 import { defineTools } from "./tools.js";
 beforeAll(() => {
@@ -29,11 +32,14 @@ describe("defineTools", () => {
             "aximo_list_uploads",
             "aximo_list_sessions",
             "aximo_get_session",
+            "aximo_wait_for_session",
             "aximo_get_session_messages",
             "aximo_get_session_screenshots",
             "aximo_get_session_timeline",
             "aximo_get_session_capture",
             "aximo_get_session_snapshot",
+            "aximo_export_session_pdf",
+            "aximo_export_session_screenshots",
             "aximo_list_cases",
             "aximo_get_case",
             "aximo_create_case",
@@ -42,6 +48,8 @@ describe("defineTools", () => {
             "aximo_restore_case",
             "aximo_delete_case",
             "aximo_run_case",
+            "aximo_create_session",
+            "aximo_cancel_session",
             "aximo_create_plan",
             "aximo_add_case_to_plan",
             "aximo_remove_case_from_plan",
@@ -55,6 +63,9 @@ describe("defineTools", () => {
             "aximo_list_plan_runs",
             "aximo_get_plan_run",
             "aximo_save_session_as_case",
+            "aximo_start_testbox",
+            "aximo_get_testbox",
+            "aximo_stop_testbox",
         ]);
     });
 });
@@ -247,6 +258,90 @@ describe("aximo_update_case", () => {
         expect(parsed).not.toHaveProperty("startUrl");
     });
 });
+describe("aximo_wait_for_session", () => {
+    const sessionId = "bbbbbbbb-bbbb-4bbb-9bbb-bbbbbbbbbbbb";
+    it("returns done=true with the session when the status is already final", async () => {
+        const session = { id: sessionId, status: "failed", summary: "Button missing" };
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}`, () => HttpResponse.json(session)));
+        const tool = byName(defineTools(), "aximo_wait_for_session");
+        const result = await tool.handler({ sessionId });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual({
+            done: true,
+            status: "failed",
+            waitedSeconds: 0,
+            session,
+        });
+    });
+    it("returns done=false with a hint when the run outlasts the timeout", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}`, () => HttpResponse.json({ id: sessionId, status: "running" })));
+        const tool = byName(defineTools(), "aximo_wait_for_session");
+        // 1 s is shorter than one poll interval, so this returns after a single poll.
+        const result = await tool.handler({ sessionId, timeoutSeconds: 1 });
+        expect(result.isError).toBeUndefined();
+        const payload = parsePayload(result);
+        expect(payload.done).toBe(false);
+        expect(payload.status).toBe("running");
+        expect(payload.hint).toMatch(/aximo_wait_for_session again/);
+    });
+    it("shapes API errors like every other tool", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}`, () => HttpResponse.json({ error: "Session not found" }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_wait_for_session");
+        const result = await tool.handler({ sessionId, timeoutSeconds: 1 });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result)).toEqual({ error: "Session not found" });
+    });
+});
+describe("aximo_cancel_session", () => {
+    const sessionId = "78787878-7878-4787-9787-787878787878";
+    it("POSTs the cancel endpoint and returns the terminated session", async () => {
+        const payload = { success: true, sessionId, status: "terminated" };
+        server.use(http.post(`${TEST_BASE_URL}/api/sessions/${sessionId}/cancel`, () => HttpResponse.json(payload)));
+        const result = await byName(defineTools(), "aximo_cancel_session").handler({ sessionId });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+    });
+    it("reports a finished session as an error with no archive hint", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/sessions/${sessionId}/cancel`, () => HttpResponse.json({ error: "Cannot cancel a session that has already finished" }, { status: 409 })));
+        const result = await byName(defineTools(), "aximo_cancel_session").handler({ sessionId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result)).toEqual({
+            error: "Cannot cancel a session that has already finished",
+        });
+    });
+});
+describe("aximo_create_session", () => {
+    const projectId = "12121212-1212-4212-9212-121212121212";
+    it("POSTs /api/sessions with the prompt and device and returns sessionId", async () => {
+        let body = null;
+        let apiKey = null;
+        const payload = { success: true, sessionId: "34343434-3434-4343-9343-343434343434" };
+        server.use(http.post(`${TEST_BASE_URL}/api/sessions`, async ({ request: req }) => {
+            apiKey = req.headers.get("x-api-key");
+            body = await req.json();
+            return HttpResponse.json(payload, { status: 201 });
+        }));
+        const tool = byName(defineTools(), "aximo_create_session");
+        const input = {
+            title: "Login works",
+            prompt: "Open http://localhost:3000 and sign in as demo@example.com. Pass if the dashboard loads.",
+            projectId,
+            userDeviceId: "56565656-5656-4565-9565-565656565656",
+        };
+        const result = await tool.handler(input);
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(apiKey).toBe("test-key");
+        expect(body).toEqual(input);
+    });
+    it("passes API validation errors through as a tool error", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/sessions`, () => HttpResponse.json({ error: "Project not found" }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_create_session");
+        const result = await tool.handler({ title: "t", prompt: "p", projectId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result)).toEqual({ error: "Project not found" });
+    });
+});
 describe("aximo_run_case", () => {
     const caseId = "77777777-7777-4777-9777-777777777777";
     it("POSTs /api/triggers/cases/:id/run with the per-run overrides and returns sessionId", async () => {
@@ -297,7 +392,10 @@ describe("aximo_run_case", () => {
         const tool = byName(defineTools(), "aximo_run_case");
         const result = await tool.handler({ caseId });
         expect(result.isError).toBe(true);
-        expect(parsePayload(result).error).toBe("Insufficient credits to start session");
+        expect(parsePayload(result)).toEqual({
+            error: "Insufficient credits to start session",
+            hint: CREDIT_HINT,
+        });
     });
     it("maps a 429 to a rate-limit error an agent can back off on", async () => {
         server.use(http.post(`${TEST_BASE_URL}/api/triggers/cases/${caseId}/run`, () => HttpResponse.json({ error: "Rate limit exceeded. Try again later." }, { status: 429, headers: { "Retry-After": "60" } })));
@@ -1037,3 +1135,53 @@ describe("409 handling parity between the CLI and MCP error mappers", () => {
         }
     });
 });
+describe("session export tools", () => {
+    const sessionId = "33333333-3333-4333-9333-333333333333";
+    let dir;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), "aximo-mcp-export-"));
+    });
+    afterEach(() => rmSync(dir, { recursive: true, force: true }));
+    it("aximo_export_session_pdf writes the PDF and returns its path, not the bytes", async () => {
+        let apiKey = null;
+        let locale = null;
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/pdf`, ({ request: req }) => {
+            apiKey = req.headers.get("x-api-key");
+            locale = new URL(req.url).searchParams.get("locale");
+            return new HttpResponse("%PDF-1.3\n%%EOF\n");
+        }));
+        const outputPath = join(dir, "result.pdf");
+        const tool = byName(defineTools(), "aximo_export_session_pdf");
+        const result = await tool.handler({ sessionId, outputPath, locale: "ko" });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual({
+            sessionId,
+            format: "pdf",
+            path: outputPath,
+            sizeBytes: 15,
+        });
+        expect(readFileSync(outputPath, "utf8")).toBe("%PDF-1.3\n%%EOF\n");
+        expect([apiKey, locale]).toEqual(["test-key", "ko"]);
+    });
+    it("aximo_export_session_screenshots deletes a truncated archive and reports an error", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/screenshots`, () => new HttpResponse(Buffer.from("PK\x03\x04 half an archive"))));
+        const tool = byName(defineTools(), "aximo_export_session_screenshots");
+        const result = await tool.handler({ sessionId, outputPath: join(dir, "shots.zip") });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toMatch(/truncated/);
+        expect(readdirSync(dir)).toEqual([]);
+    });
+    it("passes on the API's 409 for a session without screenshots", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/screenshots`, () => HttpResponse.json({ error: "Session has no screenshots to export" }, { status: 409 })));
+        const tool = byName(defineTools(), "aximo_export_session_screenshots");
+        const result = await tool.handler({ sessionId, outputPath: join(dir, "shots.zip") });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result)).toEqual({ error: "Session has no screenshots to export" });
+    });
+    it("rejects a relative outputPath", async () => {
+        const tool = byName(defineTools(), "aximo_export_session_pdf");
+        const result = await tool.handler({ sessionId, outputPath: "result.pdf" });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result)).toEqual({ error: "outputPath must be an absolute path" });
+    });
+});

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

@@ -0,0 +1,20 @@
+import { type ClientDeps } from "../../client.js";
+import type { Session } from "../../types.js";
+export declare const TERMINAL_SESSION_STATUSES: readonly ["succeeded", "failed", "terminated", "error", "archived"];
+export declare const WAIT_DEFAULT_SECONDS = 45;
+export declare const WAIT_MAX_SECONDS = 90;
+export declare const WAIT_POLL_INTERVAL_MS = 5000;
+export interface WaitClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export declare const realClock: WaitClock;
+export interface WaitResult {
+    done: boolean;
+    status: string | undefined;
+    waitedSeconds: number;
+    session: Session;
+    hint?: string;
+}
+export declare function isTerminalStatus(status: string | undefined): boolean;
+export declare function waitForSession(sessionId: string, timeoutSeconds: number, deps?: ClientDeps, clock?: WaitClock): Promise<WaitResult>;

package/dist/commands/mcp/wait.js

@@ -0,0 +1,46 @@
+import { request } from "../../client.js";
+// Mirrors TERMINAL_SESSION_STATUSES in ai-tester (packages/db/src/agent-sessions.ts).
+export const TERMINAL_SESSION_STATUSES = [
+    "succeeded",
+    "failed",
+    "terminated",
+    "error",
+    "archived",
+];
+// Most MCP clients cut a tool call off at 60 s; Kiro has no cutoff at all, so a
+// call that never returns hangs the whole chat. The default stays under 60 and
+// the ceiling gives clients without a limit a longer stretch per call.
+export const WAIT_DEFAULT_SECONDS = 45;
+export const WAIT_MAX_SECONDS = 90;
+export const WAIT_POLL_INTERVAL_MS = 5_000;
+export const realClock = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+export function isTerminalStatus(status) {
+    return TERMINAL_SESSION_STATUSES.includes(status ?? "");
+}
+export async function waitForSession(sessionId, timeoutSeconds, deps = {}, clock = realClock) {
+    const start = clock.now();
+    const deadline = start + timeoutSeconds * 1000;
+    const path = `/api/sessions/${encodeURIComponent(sessionId)}`;
+    for (;;) {
+        const session = await request(path, {}, deps);
+        const waitedSeconds = Math.round((clock.now() - start) / 1000);
+        if (isTerminalStatus(session.status)) {
+            return { done: true, status: session.status, waitedSeconds, session };
+        }
+        // Stop when the next poll would land past the deadline, so the call
+        // returns within timeoutSeconds even when a poll itself is slow.
+        if (clock.now() + WAIT_POLL_INTERVAL_MS > deadline) {
+            return {
+                done: false,
+                status: session.status,
+                waitedSeconds,
+                session,
+                hint: "Still running. Call aximo_wait_for_session again with the same sessionId.",
+            };
+        }
+        await clock.sleep(WAIT_POLL_INTERVAL_MS);
+    }
+}

package/dist/commands/mcp/wait.test.d.ts

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