@autifyhq/aximo-cli 0.14.0 → 0.15.0

package/README.md

@@ -73,6 +73,7 @@ Run `aximo <command> --help` for detailed usage. `aximo schema [command.path]` r
 | `aximo project list`         | List organization projects                                     |
 | `aximo session create`       | Create and queue a test session                                |
 | `aximo session get`          | Get session status                                             |
+| `aximo session export`       | Download a session result as a PDF or a screenshot ZIP         |
 | `aximo session save-as-case` | Save a finished session as a reusable test case                |
 | `aximo case create`          | Create a test case                                             |
 | `aximo case update`          | Update a test case                                             |
@@ -145,10 +146,14 @@ aximo session create --title <t> --prompt <p> --project-id <id> \
   [--json '<body>'] [--dry-run]
 
 aximo session get <sessionId>
+
+aximo session export <sessionId> [--format pdf|screenshots] [--output <path>] [--locale en|ja|ko]
 ```
 
 Desktop sessions default to `platform=desktop`, `model=sonnet`. Mobile sessions require both `--device-arn` and `--upload-arn`.
 
+`session export` writes the test result report (`pdf`, the default) or a ZIP of the step screenshots with `metadata.csv` and `session.csv` (`screenshots`) to `--output`, defaulting to `<sessionId>.pdf` / `<sessionId>-screenshots.zip`. The download is verified complete before it replaces the output file.
+
 ### Test cases
 
 ```bash
@@ -670,7 +675,7 @@ claude mcp add aximo -- aximo mcp
 
 VS Code (Copilot agent mode) uses the same entry under a `servers` key in `.vscode/mcp.json`.
 
-The server exposes 29 tools: 17 read-only ones for inspecting sessions, cases, plans, plan runs, devices, and uploads (`aximo_get_session_timeline` is the load-bearing one for Playwright export; `aximo_list_plans` and `aximo_get_plan` cover plan discovery; `aximo_list_plan_runs` and `aximo_get_plan_run` cover run-status polling; `aximo_list_devices`, `aximo_list_user_devices`, and `aximo_list_uploads` supply the device and upload tokens that case configs and run overrides take), 10 that author content (create, update, archive, and delete cases — including a case's per-target device configuration — create, update, and archive plans, save a session as a case), and 2 that trigger runs (`aximo_run_case` starts a case run and returns the `sessionId`; `aximo_run_plan` starts a plan run and returns the `planRunId` — both spend organization credits and require the case or plan to be `apiEnabled`). See the [MCP reference](./skills/aximo-cli/references/mcp.md) for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.
+The server exposes 34 tools: 17 read-only ones for inspecting sessions, cases, plans, plan runs, devices, and uploads (`aximo_get_session_timeline` is the load-bearing one for Playwright export; `aximo_list_plans` and `aximo_get_plan` cover plan discovery; `aximo_list_plan_runs` and `aximo_get_plan_run` cover run-status polling; `aximo_list_devices`, `aximo_list_user_devices`, and `aximo_list_uploads` supply the device and upload tokens that case configs and run overrides take), 2 that export a session result to a local file (`aximo_export_session_pdf` for the test result report, `aximo_export_session_screenshots` for a ZIP of the step screenshots), 13 that author content (create, update, archive, restore, and delete cases — including a case's per-target device configuration — create, update, archive, restore, and delete plans, add or remove a plan's cases, save a session as a case), and 2 that trigger runs (`aximo_run_case` starts a case run and returns the `sessionId`; `aximo_run_plan` starts a plan run and returns the `planRunId` — both spend organization credits and require the case or plan to be `apiEnabled`). See the [MCP reference](./skills/aximo-cli/references/mcp.md) for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.
 
 ## Agent Skills
 

package/dist/commands/mcp/index.js

@@ -10,15 +10,18 @@ export default defineCommand({
     },
     args: {},
     async run() {
-        // Fail fast before the JSON-RPC handshake; diagnostics go to stderr only.
+        // Serve even without a key. A server that exits before the handshake shows
+        // up in the client as an empty tool list with no explanation; a server that
+        // answers every call with the `aximo configure` hint tells the agent what
+        // to do. The key is re-read on each request, so no restart is needed after
+        // configuring. Diagnostics go to stderr only.
         try {
             getApiKey();
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             process.stderr.write(`aximo mcp: ${message}\n`);
-            process.exitCode = 1;
-            return;
+            process.stderr.write("aximo mcp: serving anyway; tools return this error until a key is set\n");
         }
         const baseUrl = getBaseUrl();
         process.stderr.write(`aximo mcp: serving stdio MCP against ${baseUrl}\n`);

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

@@ -24,15 +24,18 @@ async function connect() {
     };
 }
 describe("createMcpServer wiring", () => {
-    it("exposes all 29 tools through tools/list with valid JSON Schema", async () => {
+    it("exposes all 36 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_session",
+                "aximo_wait_for_session",
                 "aximo_get_session_capture",
                 "aximo_get_session_snapshot",
+                "aximo_export_session_pdf",
+                "aximo_export_session_screenshots",
                 "aximo_get_session_messages",
                 "aximo_get_session_screenshots",
                 "aximo_get_session_timeline",
@@ -48,6 +51,7 @@ describe("createMcpServer wiring", () => {
                 "aximo_restore_case",
                 "aximo_delete_case",
                 "aximo_run_case",
+                "aximo_create_session",
                 "aximo_create_plan",
                 "aximo_add_case_to_plan",
                 "aximo_remove_case_from_plan",
@@ -88,6 +92,25 @@ describe("createMcpServer wiring", () => {
             await cleanup();
         }
     });
+    it("serves the full tool list without an API key and answers calls with the configure hint", async () => {
+        const prev = process.env["AXIMO_API_KEY"];
+        delete process.env["AXIMO_API_KEY"];
+        const { client, cleanup } = await connect();
+        try {
+            const { tools } = await client.listTools();
+            expect(tools.length).toBe(36);
+            const result = await client.callTool({ name: "aximo_list_projects", arguments: {} });
+            expect(result.isError).toBe(true);
+            const content = result.content;
+            const payload = JSON.parse(content[0].text);
+            expect(payload.error).toBe("API key not configured");
+            expect(payload.hint).toBe("Run `aximo configure`, then call the tool again.");
+        }
+        finally {
+            process.env["AXIMO_API_KEY"] = prev;
+            await cleanup();
+        }
+    });
     it("returns isError with a validation message when input fails the schema", async () => {
         const { client, cleanup } = await connect();
         try {

package/dist/commands/mcp/tools.js

@@ -1,5 +1,8 @@
+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 { exportSession, SESSION_EXPORT_LOCALES, } from "../../session-export.js";
 import { ARCHIVE_FIRST_HINT, featureHint, isArchiveFirstConflict, withDetails, } from "../../errors.js";
 function ok(payload) {
     return {
@@ -50,7 +53,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,6 +83,22 @@ 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);
+}
 export function defineTools(deps = {}) {
     return [
         {
@@ -165,6 +184,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 +275,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 +455,49 @@ 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_create_plan",
             title: "Create test plan",
@@ -600,7 +700,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(),

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

@@ -1,4 +1,7 @@
-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 { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
@@ -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,7 @@ describe("defineTools", () => {
             "aximo_restore_case",
             "aximo_delete_case",
             "aximo_run_case",
+            "aximo_create_session",
             "aximo_create_plan",
             "aximo_add_case_to_plan",
             "aximo_remove_case_from_plan",
@@ -247,6 +254,72 @@ 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_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 () => {
@@ -1037,3 +1110,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 {};

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

@@ -0,0 +1,91 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
+import { isTerminalStatus, realClock, WAIT_POLL_INTERVAL_MS, waitForSession, } from "./wait.js";
+beforeAll(() => {
+    process.env["AXIMO_API_KEY"] = "test-key";
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    server.listen();
+});
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+const sessionId = "aaaaaaaa-aaaa-4aaa-9aaa-aaaaaaaaaaaa";
+// A clock where sleep advances time instantly, so the poll loop runs without waiting.
+function fakeClock() {
+    let t = 1_000_000;
+    const sleeps = [];
+    return {
+        sleeps,
+        now: () => t,
+        sleep: async (ms) => {
+            sleeps.push(ms);
+            t += ms;
+        },
+    };
+}
+function statusSequence(statuses) {
+    let calls = 0;
+    server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}`, () => {
+        const status = statuses[Math.min(calls, statuses.length - 1)];
+        calls += 1;
+        return HttpResponse.json({ id: sessionId, status });
+    }));
+    return () => calls;
+}
+describe("isTerminalStatus", () => {
+    it("matches the five final statuses and nothing else", () => {
+        for (const s of ["succeeded", "failed", "terminated", "error", "archived"]) {
+            expect(isTerminalStatus(s)).toBe(true);
+        }
+        for (const s of ["queued", "created", "preparing", "running", undefined]) {
+            expect(isTerminalStatus(s)).toBe(false);
+        }
+    });
+});
+describe("waitForSession", () => {
+    it("polls every 5 s and returns done once the status is final", async () => {
+        const calls = statusSequence(["running", "running", "succeeded"]);
+        const clock = fakeClock();
+        const result = await waitForSession(sessionId, 60, {}, clock);
+        expect(result.done).toBe(true);
+        expect(result.status).toBe("succeeded");
+        expect(result.waitedSeconds).toBe(10);
+        expect(result.session).toEqual({ id: sessionId, status: "succeeded" });
+        expect(result.hint).toBeUndefined();
+        expect(calls()).toBe(3);
+        expect(clock.sleeps).toEqual([WAIT_POLL_INTERVAL_MS, WAIT_POLL_INTERVAL_MS]);
+    });
+    it("returns done=false before the deadline instead of overrunning it", async () => {
+        const calls = statusSequence(["running"]);
+        const clock = fakeClock();
+        // 7 s: poll at 0 s, sleep to 5 s, poll, then 5 + 5 > 7 so stop.
+        const result = await waitForSession(sessionId, 7, {}, clock);
+        expect(result.done).toBe(false);
+        expect(result.status).toBe("running");
+        expect(result.waitedSeconds).toBe(5);
+        expect(result.hint).toMatch(/call aximo_wait_for_session again/i);
+        expect(calls()).toBe(2);
+    });
+    it("polls once and returns when the timeout is shorter than one interval", async () => {
+        const calls = statusSequence(["queued"]);
+        const clock = fakeClock();
+        const result = await waitForSession(sessionId, 1, {}, clock);
+        expect(result.done).toBe(false);
+        expect(result.status).toBe("queued");
+        expect(calls()).toBe(1);
+        expect(clock.sleeps).toEqual([]);
+    });
+    it("lets API errors through untouched so the tool layer can shape them", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}`, () => HttpResponse.json({ error: "Session not found" }, { status: 404 })));
+        await expect(waitForSession(sessionId, 10, {}, fakeClock())).rejects.toMatchObject({
+            status: 404,
+            message: "Session not found",
+        });
+    });
+});
+describe("realClock", () => {
+    it("sleeps for at least the requested time", async () => {
+        const before = realClock.now();
+        await realClock.sleep(20);
+        expect(realClock.now() - before).toBeGreaterThanOrEqual(15);
+    });
+});

package/dist/commands/session/export.d.ts

@@ -0,0 +1,30 @@
+import type { ClientDeps } from "../../client.js";
+import { type SessionExportResult } from "../../session-export.js";
+import type { Envelope } from "../../types.js";
+export interface SessionExportOptions {
+    sessionId?: unknown;
+    format?: unknown;
+    output?: unknown;
+    locale?: unknown;
+}
+export declare function runSessionExport(options: SessionExportOptions, deps?: ClientDeps): Promise<Envelope<SessionExportResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly sessionId: {
+        readonly type: "positional";
+        readonly description: "Session ID";
+        readonly required: true;
+    };
+    readonly format: {
+        readonly type: "string";
+        readonly description: "pdf | screenshots (default: pdf)";
+    };
+    readonly output: {
+        readonly type: "string";
+        readonly description: "File to write (default: <sessionId>.pdf or <sessionId>-screenshots.zip)";
+    };
+    readonly locale: {
+        readonly type: "string";
+        readonly description: "Report language: en | ja | ko (default: en)";
+    };
+}>;
+export default _default;

package/dist/commands/session/export.js

@@ -0,0 +1,58 @@
+import { defineCommand } from "citty";
+import { handleApiError } from "../../errors.js";
+import { formatSuccess, printResult, validationError } from "../../output.js";
+import { defaultExportFileName, exportSession, SESSION_EXPORT_FORMATS, SESSION_EXPORT_LOCALES, } from "../../session-export.js";
+import { optionalString, requireId } from "../../validate.js";
+function parseOneOf(name, allowed, value) {
+    const raw = optionalString(name, value);
+    if (raw === undefined)
+        return undefined;
+    if (!allowed.includes(raw)) {
+        throw new Error(`${name} must be one of: ${allowed.join(", ")}`);
+    }
+    return raw;
+}
+export async function runSessionExport(options, deps) {
+    let sessionId;
+    let format;
+    let locale;
+    let output;
+    try {
+        sessionId = requireId("sessionId", options.sessionId);
+        format = parseOneOf("format", SESSION_EXPORT_FORMATS, options.format) ?? "pdf";
+        locale = parseOneOf("locale", SESSION_EXPORT_LOCALES, options.locale);
+        output = optionalString("output", options.output) ?? defaultExportFileName(sessionId, format);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    try {
+        return formatSuccess(await exportSession({ sessionId, format, outputPath: output, locale }, deps));
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: {
+        name: "export",
+        description: "Download a session's result as a PDF report or a ZIP of its screenshots",
+    },
+    args: {
+        sessionId: { type: "positional", description: "Session ID", required: true },
+        format: { type: "string", description: "pdf | screenshots (default: pdf)" },
+        output: {
+            type: "string",
+            description: "File to write (default: <sessionId>.pdf or <sessionId>-screenshots.zip)",
+        },
+        locale: { type: "string", description: "Report language: en | ja | ko (default: en)" },
+    },
+    async run({ args }) {
+        printResult(await runSessionExport({
+            sessionId: args.sessionId,
+            format: args.format,
+            output: args.output,
+            locale: args.locale,
+        }));
+    },
+});

package/dist/commands/session/index.js

@@ -4,6 +4,7 @@ export default defineCommand({
     subCommands: {
         create: () => import("./create.js").then((m) => m.default),
         get: () => import("./get.js").then((m) => m.default),
+        export: () => import("./export.js").then((m) => m.default),
         "save-as-case": () => import("./save-as-case.js").then((m) => m.default),
     },
 });

package/dist/commands/session/session.test.js

@@ -1,6 +1,10 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import { server, http, HttpResponse, TEST_BASE_URL } from "../../test-utils.js";
 import { runSessionCreate } from "./create.js";
+import { runSessionExport } from "./export.js";
 import { runSessionGet } from "./get.js";
 beforeAll(() => {
     process.env["AXIMO_API_KEY"] = "test-key";
@@ -126,3 +130,61 @@ describe("runSessionGet", () => {
             expect(result.error.code).toBe("not_found");
     });
 });
+describe("runSessionExport", () => {
+    const sessionId = "44444444-4444-4444-9444-444444444444";
+    const defaultPdf = resolve(`${sessionId}.pdf`);
+    const dir = mkdtempSync(join(tmpdir(), "aximo-session-export-"));
+    afterEach(() => rmSync(defaultPdf, { force: true }));
+    afterAll(() => rmSync(dir, { recursive: true, force: true }));
+    it("defaults to a PDF named after the session in the working directory", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/pdf`, () => new HttpResponse("%PDF-1.3\n%%EOF\n")));
+        const result = await runSessionExport({ sessionId });
+        expect(result).toEqual({
+            ok: true,
+            data: { sessionId, format: "pdf", path: defaultPdf, sizeBytes: 15 },
+        });
+    });
+    it("downloads the screenshots archive in the requested locale to --output", async () => {
+        let locale = null;
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/screenshots`, ({ request }) => {
+            locale = new URL(request.url).searchParams.get("locale");
+            const eocd = Buffer.alloc(22);
+            eocd.writeUInt32LE(0x06054b50, 0);
+            return new HttpResponse(eocd);
+        }));
+        const output = join(dir, "shots.zip");
+        const result = await runSessionExport({
+            sessionId,
+            format: "screenshots",
+            output,
+            locale: "ja",
+        });
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(result.data.path).toBe(output);
+        expect(locale).toBe("ja");
+    });
+    it.each([
+        [{ format: "docx" }, /format must be one of: pdf, screenshots/],
+        [{ locale: "fr" }, /locale must be one of: en, ja, ko/],
+        [{ sessionId: "" }, /sessionId/],
+    ])("rejects %o", async (overrides, message) => {
+        const result = await runSessionExport({ sessionId, ...overrides });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("validation_error");
+            expect(result.error.message).toMatch(message);
+        }
+    });
+    it("maps the API's 409 to a conflict envelope", 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 result = await runSessionExport({
+            sessionId,
+            format: "screenshots",
+            output: join(dir, "x.zip"),
+        });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("conflict");
+    });
+});

package/dist/session-export.d.ts

@@ -0,0 +1,30 @@
+import { type ClientDeps } from "./client.js";
+export declare const SESSION_EXPORT_FORMATS: readonly ["pdf", "screenshots"];
+export type SessionExportFormat = (typeof SESSION_EXPORT_FORMATS)[number];
+export declare const SESSION_EXPORT_LOCALES: readonly ["en", "ja", "ko"];
+export type SessionExportLocale = (typeof SESSION_EXPORT_LOCALES)[number];
+export interface SessionExportInput {
+    sessionId: string;
+    format: SessionExportFormat;
+    outputPath: string;
+    locale?: SessionExportLocale | undefined;
+}
+export interface SessionExportResult {
+    sessionId: string;
+    format: SessionExportFormat;
+    path: string;
+    sizeBytes: number;
+}
+export declare function defaultExportFileName(sessionId: string, format: SessionExportFormat): string;
+/**
+ * Both exports stream, so a server failure after the first bytes are flushed
+ * reaches the client as HTTP 200 and a truncated body. Each format's trailer is
+ * written last, so its presence is what proves the download is whole.
+ */
+export declare function isCompleteExport(path: string, format: SessionExportFormat): Promise<boolean>;
+/**
+ * Downloads a session export to `outputPath`. The bytes land in a sibling
+ * `.part` file that is renamed into place only once verified complete, so a
+ * failed export neither leaves a corrupt file behind nor replaces an existing one.
+ */
+export declare function exportSession(input: SessionExportInput, deps?: ClientDeps): Promise<SessionExportResult>;

package/dist/session-export.js

@@ -0,0 +1,72 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, rename, rm, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { requestToFile } from "./client.js";
+export const SESSION_EXPORT_FORMATS = ["pdf", "screenshots"];
+export const SESSION_EXPORT_LOCALES = ["en", "ja", "ko"];
+export function defaultExportFileName(sessionId, format) {
+    return format === "pdf" ? `${sessionId}.pdf` : `${sessionId}-screenshots.zip`;
+}
+const EOCD_SIGNATURE = 0x06054b50;
+const EOCD_MIN_LENGTH = 22;
+const EOCD_MAX_LENGTH = EOCD_MIN_LENGTH + 0xffff;
+// PDF readers look for %%EOF within the last 1024 bytes.
+const PDF_TRAILER_WINDOW = 1024;
+async function readTail(path, maxBytes) {
+    const handle = await open(path, "r");
+    try {
+        const { size } = await handle.stat();
+        const length = Math.min(size, maxBytes);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, size - length);
+        return buffer;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Both exports stream, so a server failure after the first bytes are flushed
+ * reaches the client as HTTP 200 and a truncated body. Each format's trailer is
+ * written last, so its presence is what proves the download is whole.
+ */
+export async function isCompleteExport(path, format) {
+    if (format === "pdf") {
+        return (await readTail(path, PDF_TRAILER_WINDOW)).includes("%%EOF");
+    }
+    // The end-of-central-directory record must end the file exactly: its comment
+    // length has to account for every byte after it, which a signature that
+    // happens to appear inside compressed image data will not.
+    const tail = await readTail(path, EOCD_MAX_LENGTH);
+    for (let at = tail.length - EOCD_MIN_LENGTH; at >= 0; at--) {
+        if (tail.readUInt32LE(at) === EOCD_SIGNATURE &&
+            tail.readUInt16LE(at + 20) === tail.length - at - EOCD_MIN_LENGTH) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Downloads a session export to `outputPath`. The bytes land in a sibling
+ * `.part` file that is renamed into place only once verified complete, so a
+ * failed export neither leaves a corrupt file behind nor replaces an existing one.
+ */
+export async function exportSession(input, deps = {}) {
+    const path = resolve(input.outputPath);
+    await mkdir(dirname(path), { recursive: true });
+    const partialPath = `${path}.${randomUUID().slice(0, 8)}.part`;
+    const query = input.locale ? `?locale=${input.locale}` : "";
+    try {
+        await requestToFile(`/api/sessions/${encodeURIComponent(input.sessionId)}/export/${input.format}${query}`, partialPath, deps);
+        if (!(await isCompleteExport(partialPath, input.format))) {
+            throw new Error(`The ${input.format === "pdf" ? "PDF" : "screenshot archive"} download was truncated before it finished. Retry the export.`);
+        }
+        await rename(partialPath, path);
+    }
+    catch (error) {
+        await rm(partialPath, { force: true });
+        throw error;
+    }
+    const { size } = await stat(path);
+    return { sessionId: input.sessionId, format: input.format, path, sizeBytes: size };
+}

package/dist/session-export.test.d.ts

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

package/dist/session-export.test.js

@@ -0,0 +1,107 @@
+import { mkdtempSync, readdirSync, 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 { exportSession, isCompleteExport } from "./session-export.js";
+import { HttpResponse, http, server, TEST_BASE_URL } from "./test-utils.js";
+const SESSION_ID = "11111111-1111-4111-9111-111111111111";
+function eocd(comment = "") {
+    const record = Buffer.alloc(22);
+    record.writeUInt32LE(0x06054b50, 0);
+    record.writeUInt16LE(comment.length, 20);
+    return Buffer.concat([record, Buffer.from(comment)]);
+}
+let dir;
+beforeAll(() => {
+    process.env["AXIMO_API_KEY"] = "test-key";
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    server.listen();
+});
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "aximo-export-"));
+});
+afterEach(() => {
+    server.resetHandlers();
+    rmSync(dir, { recursive: true, force: true });
+});
+afterAll(() => server.close());
+function fileWith(bytes) {
+    const path = join(dir, "file");
+    writeFileSync(path, bytes);
+    return path;
+}
+describe("isCompleteExport", () => {
+    it("accepts a ZIP ending in its end-of-central-directory record", async () => {
+        const body = Buffer.concat([Buffer.from("PK\x03\x04 entries"), eocd()]);
+        expect(await isCompleteExport(fileWith(body), "screenshots")).toBe(true);
+    });
+    it("accepts a ZIP whose record carries a comment", async () => {
+        const body = Buffer.concat([Buffer.from("PK\x03\x04 entries"), eocd("made by aximo")]);
+        expect(await isCompleteExport(fileWith(body), "screenshots")).toBe(true);
+    });
+    it("rejects a ZIP cut off before its record", async () => {
+        const body = Buffer.concat([Buffer.from("PK\x03\x04 entries"), eocd()]).subarray(0, -1);
+        expect(await isCompleteExport(fileWith(body), "screenshots")).toBe(false);
+    });
+    it("rejects a signature inside entry data that does not end the file", async () => {
+        const body = Buffer.concat([
+            Buffer.from("PK\x03\x04"),
+            eocd(),
+            Buffer.from("more entry bytes"),
+        ]);
+        expect(await isCompleteExport(fileWith(body), "screenshots")).toBe(false);
+    });
+    it("rejects a file that starts with the signature but is shorter than the record", async () => {
+        expect(await isCompleteExport(fileWith(eocd().subarray(0, -1)), "screenshots")).toBe(false);
+    });
+    it("rejects an empty file", async () => {
+        expect(await isCompleteExport(fileWith(Buffer.alloc(0)), "screenshots")).toBe(false);
+        expect(await isCompleteExport(fileWith(Buffer.alloc(0)), "pdf")).toBe(false);
+    });
+    it("checks a PDF for its %%EOF trailer", async () => {
+        expect(await isCompleteExport(fileWith(Buffer.from("%PDF-1.3\n...\n%%EOF\n")), "pdf")).toBe(true);
+        expect(await isCompleteExport(fileWith(Buffer.from("%PDF-1.3\n...stream")), "pdf")).toBe(false);
+    });
+});
+describe("exportSession", () => {
+    it("streams the export to the path, creating parent directories", async () => {
+        let url;
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${SESSION_ID}/export/pdf`, ({ request }) => {
+            url = new URL(request.url);
+            return new HttpResponse("%PDF-1.3\n%%EOF\n", {
+                headers: { "Content-Type": "application/pdf" },
+            });
+        }));
+        const outputPath = join(dir, "nested", "report.pdf");
+        const result = await exportSession({
+            sessionId: SESSION_ID,
+            format: "pdf",
+            outputPath,
+            locale: "ja",
+        });
+        expect(result).toEqual({
+            sessionId: SESSION_ID,
+            format: "pdf",
+            path: outputPath,
+            sizeBytes: 15,
+        });
+        expect(url?.searchParams.get("locale")).toBe("ja");
+        expect(readdirSync(join(dir, "nested"))).toEqual(["report.pdf"]);
+    });
+    it("deletes a truncated download and keeps the file it would have replaced", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${SESSION_ID}/export/screenshots`, () => new HttpResponse(Buffer.from("PK\x03\x04 half an archive"))));
+        const outputPath = join(dir, "shots.zip");
+        writeFileSync(outputPath, "previous export");
+        await expect(exportSession({ sessionId: SESSION_ID, format: "screenshots", outputPath })).rejects.toThrow(/truncated/);
+        expect(readdirSync(dir)).toEqual(["shots.zip"]);
+    });
+    it("leaves nothing behind when the API refuses the export", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${SESSION_ID}/export/screenshots`, () => HttpResponse.json({ error: "Session has no screenshots to export" }, { status: 409 })));
+        await expect(exportSession({
+            sessionId: SESSION_ID,
+            format: "screenshots",
+            outputPath: join(dir, "s.zip"),
+        })).rejects.toMatchObject({ status: 409, message: "Session has no screenshots to export" });
+        expect(readdirSync(dir)).toEqual([]);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autifyhq/aximo-cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Autify Aximo Command Line Interface (CLI)",
   "keywords": [
     "autify",