@autifyhq/aximo-cli 0.13.0 → 0.15.0

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

@@ -1,4 +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 { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
 import { defineTools } from "./tools.js";
 beforeAll(() => {
@@ -22,25 +27,37 @@ describe("defineTools", () => {
         const names = defineTools().map((t) => t.name);
         expect(names).toEqual([
             "aximo_list_projects",
+            "aximo_list_devices",
+            "aximo_list_user_devices",
+            "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",
             "aximo_update_case",
+            "aximo_archive_case",
+            "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",
             "aximo_list_plans",
             "aximo_get_plan",
             "aximo_update_plan",
+            "aximo_archive_plan",
+            "aximo_restore_plan",
+            "aximo_delete_plan",
             "aximo_run_plan",
             "aximo_list_plan_runs",
             "aximo_get_plan_run",
@@ -180,6 +197,9 @@ describe("aximo_update_case", () => {
         expect(result.isError).toBeUndefined();
         expect(parsePayload(result)).toEqual(payload);
         expect(body).toEqual({ title: "Renamed", scenario: "Given a renamed page" });
+        // GEN-2844 regression guard: an omitted description must not be sent at
+        // all, or every partial update would clear the field server-side.
+        expect(body).not.toHaveProperty("description");
     });
     it("rejects an update with no fields instead of issuing an empty PATCH", async () => {
         let called = false;
@@ -204,6 +224,101 @@ describe("aximo_update_case", () => {
         expect(result.isError).toBeUndefined();
         expect(body).toEqual({ startUrl: null });
     });
+    it("passes description: null through as an explicit clear (GEN-2844)", async () => {
+        let body = null;
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, async ({ request: req }) => {
+            body = await req.json();
+            return HttpResponse.json({ success: true });
+        }));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({ caseId, description: null });
+        expect(result.isError).toBeUndefined();
+        expect(body).toEqual({ description: null });
+    });
+    // The tests above call handler() directly, which bypasses Zod entirely --
+    // the MCP SDK is what parses in production. These assertions are what
+    // actually pin the clearable fields to their schema.
+    it("accepts null for the clearable fields at schema time, and drops omitted keys", () => {
+        const tool = byName(defineTools(), "aximo_update_case");
+        // biome-ignore lint/suspicious/noExplicitAny: zod runtime check
+        const schemas = tool.inputSchema;
+        expect(schemas.description.safeParse(null).success).toBe(true);
+        expect(schemas.description.safeParse("").success).toBe(true);
+        expect(schemas.description.safeParse(5).success).toBe(false);
+        expect(schemas.startUrl.safeParse(null).success).toBe(true);
+        expect(schemas.startUrl.safeParse("not-a-url").success).toBe(false);
+        // The object schema must leave omitted keys absent rather than defaulting
+        // them to null, which would clear on every partial update.
+        const parsed = z.object(schemas).parse({ caseId, title: "Renamed" });
+        expect(parsed).not.toHaveProperty("description");
+        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";
@@ -704,6 +819,32 @@ describe("write tools", () => {
         expect(parsePayload(result)).toEqual({ success: true });
         expect(method).toBe("DELETE");
     });
+    it("aximo_archive_case POSTs the case archive path", async () => {
+        let method = null;
+        server.use(http.post(`${TEST_BASE_URL}/api/cases/c1/archive`, ({ request: req }) => {
+            method = req.method;
+            return HttpResponse.json({ archived: true });
+        }));
+        const tool = byName(defineTools(), "aximo_archive_case");
+        const result = await tool.handler({ caseId: "c1" });
+        expect(parsePayload(result)).toEqual({ archived: true });
+        expect(method).toBe("POST");
+    });
+    it("aximo_archive_plan POSTs the plan archive path", async () => {
+        let method = null;
+        server.use(http.post(`${TEST_BASE_URL}/api/plans/pl1/archive`, ({ request: req }) => {
+            method = req.method;
+            return HttpResponse.json({ archived: true });
+        }));
+        const tool = byName(defineTools(), "aximo_archive_plan");
+        const result = await tool.handler({ planId: "pl1" });
+        expect(parsePayload(result)).toEqual({ archived: true });
+        expect(method).toBe("POST");
+    });
+    it("aximo_delete_case describes itself as archive-first and permanent", () => {
+        const tool = byName(defineTools(), "aximo_delete_case");
+        expect(tool.description).toBe("Permanently delete an already-archived test case. Archive it first with aximo_archive_case. Requires an organization admin or owner API key. It is removed from any plans it belongs to, and its rows in past plan runs go with it, so those runs list fewer cases than their stored totals; the agent sessions themselves are kept but detached. This cannot be undone.");
+    });
     it("aximo_delete_case DELETEs the case path", async () => {
         let method = null;
         server.use(http.delete(`${TEST_BASE_URL}/api/cases/c1`, ({ request: req }) => {
@@ -727,3 +868,295 @@ describe("write tools", () => {
         expect(body).toEqual({ title: "Saved" });
     });
 });
+describe("aximo_update_case per-target config", () => {
+    const caseId = "55555555-5555-4555-9555-555555555555";
+    const userDeviceId = "77777777-7777-4777-9777-777777777777";
+    it("forwards the config objects untouched, including keys the CLI does not know about", async () => {
+        let body = null;
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, async ({ request: req }) => {
+            body = await req.json();
+            return HttpResponse.json({ success: true });
+        }));
+        const mobile = {
+            deviceArn: "enc-device",
+            deviceName: "Pixel 8",
+            platform: "ANDROID",
+            apps: [{ uploadArn: "enc-upload", uploadType: "own_app", appName: null, bundleId: "com.x" }],
+            futureField: "kept",
+        };
+        const multi = [
+            { kind: "web", name: "Buyer", startUrl: "https://shop.example" },
+            { kind: "mobile", name: "Seller", mobilePlatform: "ios", userDeviceId },
+        ];
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({
+            caseId,
+            type: "multi_device",
+            apiMobileConfig: mobile,
+            apiDesktopConfig: { userDeviceId },
+            apiMultiDeviceConfig: multi,
+            apiWebConfig: { hostnameOverrideIds: ["h1"] },
+        });
+        expect(result.isError).toBeUndefined();
+        expect(body).toEqual({
+            type: "multi_device",
+            apiMobileConfig: mobile,
+            apiDesktopConfig: { userDeviceId },
+            apiMultiDeviceConfig: multi,
+            apiWebConfig: { hostnameOverrideIds: ["h1"] },
+        });
+    });
+    it("passes null configs (and description) through as explicit clears", async () => {
+        let body = null;
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, async ({ request: req }) => {
+            body = await req.json();
+            return HttpResponse.json({ success: true });
+        }));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({
+            caseId,
+            description: null,
+            apiMobileConfig: null,
+            apiDesktopConfig: null,
+            apiMultiDeviceConfig: null,
+            apiWebConfig: null,
+        });
+        expect(result.isError).toBeUndefined();
+        expect(body).toEqual({
+            description: null,
+            apiMobileConfig: null,
+            apiDesktopConfig: null,
+            apiMultiDeviceConfig: null,
+            apiWebConfig: null,
+        });
+    });
+    it("keeps unknown nested keys at schema time and only pins userDeviceId's shape", () => {
+        const schema = z.object(byName(defineTools(), "aximo_update_case").inputSchema);
+        const parsed = schema.parse({
+            caseId,
+            apiMobileConfig: { deviceArn: "x", newKey: 1 },
+            apiMultiDeviceConfig: [{ kind: "web", extra: true }],
+            apiWebConfig: { hostnameOverrideIds: [], newKey: true },
+        });
+        expect(parsed["apiMobileConfig"]).toEqual({ deviceArn: "x", newKey: 1 });
+        expect(parsed["apiMultiDeviceConfig"]).toEqual([{ kind: "web", extra: true }]);
+        expect(parsed["apiWebConfig"]).toEqual({ hostnameOverrideIds: [], newKey: true });
+        expect(schema.safeParse({ caseId, apiDesktopConfig: { userDeviceId: "nope" } }).success).toBe(false);
+        expect(schema.safeParse({ caseId, apiMultiDeviceConfig: "web" }).success).toBe(false);
+    });
+    it("names the failing path from the API's error details", async () => {
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json({
+            error: "Upload not found",
+            details: { path: "apiMultiDeviceConfig[1].apps[0].uploadArn" },
+        }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({ caseId, apiMultiDeviceConfig: [{}, {}] });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("Upload not found (at apiMultiDeviceConfig[1].apps[0].uploadArn)");
+    });
+    it("renders zod issues from an Invalid request body tree", async () => {
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json({
+            error: "Invalid request body",
+            details: {
+                errors: [],
+                properties: {
+                    apiMobileConfig: {
+                        errors: [],
+                        properties: { deviceArn: { errors: ["Invalid input: expected string"] } },
+                    },
+                },
+            },
+        }, { status: 400 })));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({ caseId, apiMobileConfig: {} });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("HTTP 400: Invalid request body (apiMobileConfig.deviceArn: Invalid input: expected string)");
+    });
+    it("points at an org admin, not the API key, when a feature gate rejects the config", async () => {
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json({
+            error: "Desktop cases are not enabled for this organization",
+            details: { feature: "byodEnabled" },
+        }, { status: 403 })));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({ caseId, apiDesktopConfig: { userDeviceId } });
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toBe("Desktop cases are not enabled for this organization (requires feature byodEnabled)");
+        expect(payload.hint).toBe("Ask an Aximo organization admin to enable byodEnabled.");
+    });
+    it("recognises the feature-gate message even without details", async () => {
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json({ error: "Multi-device cases are not enabled for this organization" }, { status: 403 })));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({ caseId, apiMultiDeviceConfig: [{}, {}] });
+        const payload = parsePayload(result);
+        expect(payload.error).toBe("Multi-device cases are not enabled for this organization");
+        expect(payload.hint).toMatch(/organization admin/);
+        expect(payload.hint).not.toMatch(/API key/);
+    });
+});
+describe("device and upload read tools", () => {
+    it("aximo_list_devices GETs /api/devices with platform and availableOnly", async () => {
+        let url = null;
+        const payload = {
+            devices: [{ arn: "enc-device", name: "Pixel 8", platform: "ANDROID", os: "14" }],
+        };
+        server.use(http.get(`${TEST_BASE_URL}/api/devices`, ({ request: req }) => {
+            url = new URL(req.url);
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_list_devices");
+        const result = await tool.handler({ platform: "ANDROID", availableOnly: true });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(url.searchParams.get("platform")).toBe("ANDROID");
+        expect(url.searchParams.get("availableOnly")).toBe("true");
+    });
+    it("aximo_list_devices sends no filters when none are given", async () => {
+        let url = null;
+        server.use(http.get(`${TEST_BASE_URL}/api/devices`, ({ request: req }) => {
+            url = new URL(req.url);
+            return HttpResponse.json({ devices: [] });
+        }));
+        const tool = byName(defineTools(), "aximo_list_devices");
+        await tool.handler({ availableOnly: false });
+        expect([...url.searchParams.keys()]).toEqual([]);
+    });
+    it("aximo_list_user_devices GETs /api/devices/user", async () => {
+        const payload = {
+            devices: [{ id: "u1", name: "Abdul's Mac", platform: "macos", os: "15.0", status: "online" }],
+        };
+        let called = false;
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => {
+            called = true;
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_list_user_devices");
+        const result = await tool.handler({});
+        expect(called).toBe(true);
+        expect(parsePayload(result)).toEqual(payload);
+    });
+    it("aximo_list_user_devices explains the bare 404 the route returns when BYOD is disabled", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ error: "Not found" }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_list_user_devices");
+        const result = await tool.handler({});
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toContain("BYOD is not enabled for this organization");
+        expect(payload.hint).toContain("byodEnabled");
+    });
+    it("aximo_list_uploads GETs /api/uploads with fileType", async () => {
+        let url = null;
+        const payload = {
+            uploads: [
+                {
+                    id: "up1",
+                    uploadArn: "enc-upload",
+                    status: "succeeded",
+                    appName: "Shop",
+                    identifier: "com.example.shop",
+                    fileType: "IOS_APP",
+                },
+            ],
+        };
+        server.use(http.get(`${TEST_BASE_URL}/api/uploads`, ({ request: req }) => {
+            url = new URL(req.url);
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_list_uploads");
+        const result = await tool.handler({ fileType: "IOS_APP" });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(url.searchParams.get("fileType")).toBe("IOS_APP");
+    });
+});
+describe("409 handling parity between the CLI and MCP error mappers", () => {
+    const caseId = "11111111-1111-4111-8111-111111111111";
+    const ARCHIVE_409 = "Test case must be archived before it can be permanently deleted. Archive it first with POST /api/cases/{caseId}/archive, then retry the delete.";
+    const OTHER_409 = "Case already in plan";
+    function conflictOnDelete(message) {
+        server.use(http.delete(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json({ error: message }, { status: 409 })));
+    }
+    it("surfaces the archive hint on the MCP surface, not just the CLI", async () => {
+        conflictOnDelete(ARCHIVE_409);
+        const tool = byName(defineTools(), "aximo_delete_case");
+        const result = await tool.handler({ caseId });
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toMatch(/must be archived/);
+        // The hint names aximo_archive_case, so the MCP caller it names has to receive
+        // it. Before this branch existed the agent got a bare "HTTP 409: ..." pointing
+        // at a REST endpoint it cannot call.
+        expect(payload.hint).toBe(ARCHIVE_FIRST_HINT);
+        expect(payload.hint).toMatch(/aximo_archive_case/);
+    });
+    it("stays silent on a 409 that archiving would not fix", async () => {
+        conflictOnDelete(OTHER_409);
+        const tool = byName(defineTools(), "aximo_delete_case");
+        const result = await tool.handler({ caseId });
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toMatch(/already in plan/);
+        expect(payload.hint).toBeUndefined();
+    });
+    it("agrees with handleApiError on which 409s earn the hint", () => {
+        // Both mappers key off the same predicate and the same constant. If one side
+        // grows a rule the other lacks, this fails rather than silently diverging on
+        // the agent-facing surface.
+        for (const message of [ARCHIVE_409, OTHER_409]) {
+            const cliEnvelope = handleApiError(Object.assign(new Error(message), { status: 409 }));
+            const expectedHint = isArchiveFirstConflict(message) ? ARCHIVE_FIRST_HINT : undefined;
+            expect(cliEnvelope.error.code).toBe("conflict");
+            expect(cliEnvelope.error.hint).toBe(expectedHint);
+        }
+    });
+});
+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/plan/archive.d.ts

@@ -0,0 +1,20 @@
+import { type ClientDeps } from "../../client.js";
+import { type DryRunResult } from "../../mutate.js";
+import type { ArchivePlanResult, Envelope } from "../../types.js";
+export interface ArchivePlanOptions {
+    planId?: unknown;
+    dryRun?: unknown;
+}
+export declare function runPlanArchive(options: ArchivePlanOptions, deps?: ClientDeps): Promise<Envelope<ArchivePlanResult | DryRunResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly planId: {
+        readonly type: "positional";
+        readonly description: "Plan ID";
+        readonly required: true;
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+        readonly description: "Validate and show request without calling API";
+    };
+}>;
+export default _default;