@autifyhq/aximo-cli 0.12.0 → 0.14.0

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

@@ -1,4 +1,6 @@
 import { afterAll, afterEach, beforeAll, 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,6 +24,9 @@ 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_get_session_messages",
@@ -33,13 +38,20 @@ describe("defineTools", () => {
             "aximo_get_case",
             "aximo_create_case",
             "aximo_update_case",
+            "aximo_archive_case",
+            "aximo_restore_case",
             "aximo_delete_case",
+            "aximo_run_case",
             "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",
             "aximo_save_session_as_case",
@@ -178,6 +190,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;
@@ -202,6 +217,104 @@ 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_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 () => {
+        let body = null;
+        let apiKey = null;
+        const payload = { success: true, sessionId: "88888888-8888-4888-9888-888888888888" };
+        server.use(http.post(`${TEST_BASE_URL}/api/triggers/cases/${caseId}/run`, 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_run_case");
+        const result = await tool.handler({
+            caseId,
+            model: "sonnet",
+            hostnameOverrideIds: ["99999999-9999-4999-9999-999999999999"],
+            apps: [{ uploadArn: "tok-1", uploadType: "own_app", appName: null }],
+        });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(apiKey).toBe("test-key");
+        expect(body).toEqual({
+            model: "sonnet",
+            hostnameOverrideIds: ["99999999-9999-4999-9999-999999999999"],
+            apps: [{ uploadArn: "tok-1", uploadType: "own_app", appName: null }],
+        });
+    });
+    it("sends an empty body when only caseId is given, so the saved config applies", async () => {
+        let body = null;
+        server.use(http.post(`${TEST_BASE_URL}/api/triggers/cases/${caseId}/run`, async ({ request: req }) => {
+            body = await req.json();
+            return HttpResponse.json({ success: true, sessionId: "s" }, { status: 201 });
+        }));
+        const tool = byName(defineTools(), "aximo_run_case");
+        const result = await tool.handler({ caseId });
+        expect(result.isError).toBeUndefined();
+        expect(body).toEqual({});
+    });
+    it("surfaces the apiEnabled rejection as the error message", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/triggers/cases/${caseId}/run`, () => HttpResponse.json({ error: "API access is not enabled for this case" }, { status: 403 })));
+        const tool = byName(defineTools(), "aximo_run_case");
+        const result = await tool.handler({ caseId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("API access is not enabled for this case");
+    });
+    it("surfaces the insufficient-credits rejection distinctly", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/triggers/cases/${caseId}/run`, () => HttpResponse.json({ error: "Insufficient credits to start session" }, { status: 403 })));
+        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");
+    });
+    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" } })));
+        const tool = byName(defineTools(), "aximo_run_case");
+        const result = await tool.handler({ caseId });
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toMatch(/Rate limited/);
+        expect(payload.hint).toBe("Back off and retry after 60 seconds.");
+    });
+    it("returns the API's 404 for a case outside the organization without leaking existence", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/triggers/cases/${caseId}/run`, () => HttpResponse.json({ error: "Test case not found" }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_run_case");
+        const result = await tool.handler({ caseId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("Test case not found");
+    });
 });
 describe("aximo_list_plans", () => {
     const projectId = "44444444-4444-4444-8444-444444444444";
@@ -304,6 +417,63 @@ describe("aximo_update_plan", () => {
         expect(called).toBe(false);
     });
 });
+describe("aximo_run_plan", () => {
+    const planId = "aaaaaaaa-aaaa-4aaa-9aaa-aaaaaaaaaaaa";
+    it("POSTs /api/triggers/plans/:id/run with the per-run overrides and returns planRunId", async () => {
+        let body = null;
+        const payload = {
+            success: true,
+            planRunId: "bbbbbbbb-bbbb-4bbb-9bbb-bbbbbbbbbbbb",
+            totalCases: 3,
+            executionMode: "sequential",
+        };
+        server.use(http.post(`${TEST_BASE_URL}/api/triggers/plans/${planId}/run`, async ({ request: req }) => {
+            body = await req.json();
+            return HttpResponse.json(payload, { status: 201 });
+        }));
+        const tool = byName(defineTools(), "aximo_run_plan");
+        const result = await tool.handler({
+            planId,
+            executionMode: "sequential",
+            mobileConfig: { deviceArn: "tok-device", deviceName: "Pixel 8", platform: "ANDROID" },
+            desktopConfig: { devices: [{ userDeviceId: "cccccccc-cccc-4ccc-9ccc-cccccccccccc" }] },
+            variables: [{ name: "BASE_URL", value: "https://staging.example.com" }],
+        });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(body).toEqual({
+            executionMode: "sequential",
+            mobileConfig: { deviceArn: "tok-device", deviceName: "Pixel 8", platform: "ANDROID" },
+            desktopConfig: { devices: [{ userDeviceId: "cccccccc-cccc-4ccc-9ccc-cccccccccccc" }] },
+            variables: [{ name: "BASE_URL", value: "https://staging.example.com" }],
+        });
+    });
+    it("sends an empty body when only planId is given, so the plan's stored settings apply", async () => {
+        let body = null;
+        server.use(http.post(`${TEST_BASE_URL}/api/triggers/plans/${planId}/run`, async ({ request: req }) => {
+            body = await req.json();
+            return HttpResponse.json({ success: true, planRunId: "r", totalCases: 1 }, { status: 201 });
+        }));
+        const tool = byName(defineTools(), "aximo_run_plan");
+        const result = await tool.handler({ planId });
+        expect(result.isError).toBeUndefined();
+        expect(body).toEqual({});
+    });
+    it("surfaces the apiEnabled rejection as the error message", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/triggers/plans/${planId}/run`, () => HttpResponse.json({ error: "API access is not enabled for this plan" }, { status: 403 })));
+        const tool = byName(defineTools(), "aximo_run_plan");
+        const result = await tool.handler({ planId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("API access is not enabled for this plan");
+    });
+    it("returns the API's 404 for a plan outside the organization without leaking existence", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/triggers/plans/${planId}/run`, () => HttpResponse.json({ error: "Test plan not found" }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_run_plan");
+        const result = await tool.handler({ planId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("Test plan not found");
+    });
+});
 describe("aximo_list_plan_runs", () => {
     const planId = "77777777-7777-4777-9777-777777777777";
     it("calls /api/triggers/plans/:id/runs, passing limit and cursor through", async () => {
@@ -471,14 +641,23 @@ describe("call() error mapping", () => {
         const payload = parsePayload(result);
         expect(payload.error).toBe("Session was archived");
     });
-    it("flags 429 with the rate-limit hint", async () => {
+    it("flags 429 with a back-off hint when no Retry-After header is present", async () => {
         server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/timeline`, () => HttpResponse.json({ error: "Too many requests" }, { status: 429 })));
         const tool = byName(defineTools(), "aximo_get_session_timeline");
         const result = await tool.handler({ sessionId });
         expect(result.isError).toBe(true);
         const payload = parsePayload(result);
         expect(payload.error).toBe("Rate limited");
-        expect(payload.hint).toMatch(/daily/i);
+        expect(payload.hint).toMatch(/back off/i);
+    });
+    it("carries the Retry-After value into the 429 hint so an agent knows how long to wait", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/timeline`, () => HttpResponse.json({ error: "Too many requests" }, { status: 429, headers: { "Retry-After": "42" } })));
+        const tool = byName(defineTools(), "aximo_get_session_timeline");
+        const result = await tool.handler({ sessionId });
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toBe("Rate limited");
+        expect(payload.hint).toBe("Back off and retry after 42 seconds.");
     });
     it("distinguishes a 500 with the HTTP-prefixed message", async () => {
         server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/timeline`, () => HttpResponse.json({ error: "Internal server error" }, { status: 500 })));
@@ -567,6 +746,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 }) => {
@@ -590,3 +795,245 @@ 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);
+        }
+    });
+});

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;

package/dist/commands/plan/archive.js

@@ -0,0 +1,42 @@
+import { defineCommand } from "citty";
+import { request } from "../../client.js";
+import { handleApiError } from "../../errors.js";
+import { dryRunEnvelope } from "../../mutate.js";
+import { formatSuccess, printResult, validationError } from "../../output.js";
+import { requireId } from "../../validate.js";
+export async function runPlanArchive(options, deps) {
+    let planId;
+    try {
+        planId = requireId("planId", options.planId);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    const path = `/api/plans/${encodeURIComponent(planId)}/archive`;
+    if (options.dryRun) {
+        return dryRunEnvelope("POST", path);
+    }
+    try {
+        const res = await request(path, { method: "POST" }, deps ?? {});
+        return formatSuccess(res);
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: {
+        name: "archive",
+        description: "Archive a test plan (hides it from lists; cases, run history, and its schedule are kept)",
+    },
+    args: {
+        planId: { type: "positional", description: "Plan ID", required: true },
+        "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
+    },
+    async run({ args }) {
+        printResult(await runPlanArchive({
+            planId: args.planId,
+            dryRun: args["dry-run"],
+        }));
+    },
+});

package/dist/commands/plan/delete.d.ts

@@ -0,0 +1,20 @@
+import { type ClientDeps } from "../../client.js";
+import { type DryRunResult } from "../../mutate.js";
+import type { DeletePlanResult, Envelope } from "../../types.js";
+export interface DeletePlanOptions {
+    planId?: unknown;
+    dryRun?: unknown;
+}
+export declare function runPlanDelete(options: DeletePlanOptions, deps?: ClientDeps): Promise<Envelope<DeletePlanResult | 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;

package/dist/commands/plan/delete.js

@@ -0,0 +1,42 @@
+import { defineCommand } from "citty";
+import { request } from "../../client.js";
+import { handleApiError } from "../../errors.js";
+import { dryRunEnvelope } from "../../mutate.js";
+import { formatSuccess, printResult, validationError } from "../../output.js";
+import { requireId } from "../../validate.js";
+export async function runPlanDelete(options, deps) {
+    let planId;
+    try {
+        planId = requireId("planId", options.planId);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    const path = `/api/plans/${encodeURIComponent(planId)}`;
+    if (options.dryRun) {
+        return dryRunEnvelope("DELETE", path);
+    }
+    try {
+        const res = await request(path, { method: "DELETE" }, deps ?? {});
+        return formatSuccess(res);
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: {
+        name: "delete",
+        description: "Permanently delete an archived test plan (archive it first with `aximo plan archive`). Requires an org admin or owner. Member cases and run history are kept; the runs are detached from the plan",
+    },
+    args: {
+        planId: { type: "positional", description: "Plan ID", required: true },
+        "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
+    },
+    async run({ args }) {
+        printResult(await runPlanDelete({
+            planId: args.planId,
+            dryRun: args["dry-run"],
+        }));
+    },
+});

package/dist/commands/plan/index.js

@@ -4,6 +4,9 @@ export default defineCommand({
     subCommands: {
         create: () => import("./create.js").then((m) => m.default),
         update: () => import("./update.js").then((m) => m.default),
+        archive: () => import("./archive.js").then((m) => m.default),
+        restore: () => import("./restore.js").then((m) => m.default),
+        delete: () => import("./delete.js").then((m) => m.default),
         "add-case": () => import("./add-case.js").then((m) => m.default),
         "remove-case": () => import("./remove-case.js").then((m) => m.default),
     },