@autifyhq/aximo-cli 0.12.0 → 0.13.0

package/README.md

@@ -660,7 +660,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 22 tools: 14 read-only ones for inspecting sessions, cases, plans, and plan runs (`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) plus 8 that author content (create, update, and delete cases, create and update plans, save a session as a case). 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 24 tools: 14 read-only ones for inspecting sessions, cases, plans, and plan runs (`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), 8 that author content (create, update, and delete cases, create and update 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.
 
 ## Agent Skills
 

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

@@ -24,7 +24,7 @@ async function connect() {
     };
 }
 describe("createMcpServer wiring", () => {
-    it("exposes all 22 tools through tools/list with valid JSON Schema", async () => {
+    it("exposes all 24 tools through tools/list with valid JSON Schema", async () => {
         const { client, cleanup } = await connect();
         try {
             const { tools } = await client.listTools();
@@ -42,12 +42,14 @@ describe("createMcpServer wiring", () => {
                 "aximo_create_case",
                 "aximo_update_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_run_plan",
                 "aximo_list_plan_runs",
                 "aximo_get_plan_run",
                 "aximo_save_session_as_case",

package/dist/commands/mcp/tools.js

@@ -31,8 +31,12 @@ async function call(fn) {
         }
         if (status === 404)
             return err(e.message || "Not found");
-        if (status === 429)
-            return err("Rate limited", "Aximo enforces a daily session limit.");
+        if (status === 429) {
+            const retryAfter = e.retryAfter;
+            return err("Rate limited", retryAfter
+                ? `Back off and retry after ${retryAfter} seconds.`
+                : "Back off before retrying; Aximo rate-limits requests per organization.");
+        }
         if (typeof status === "number")
             return err(`HTTP ${status}: ${e.message}`);
         if (e.message.startsWith("No API key configured")) {
@@ -54,6 +58,18 @@ function buildQuery(params) {
     }
     return out;
 }
+// Mobile app selection accepted by the run triggers (multi-app, max 3).
+// ARN fields are the encrypted tokens Aximo returns, never raw AWS ARNs.
+const runAppsSchema = z
+    .array(z.object({
+    uploadArn: z
+        .string()
+        .describe("Encrypted upload token (from aximo_get_case config or `aximo upload`)."),
+    uploadType: z.enum(["own_app", "existing", "sample"]),
+    appName: z.string().nullable(),
+    bundleId: z.string().optional(),
+}))
+    .max(3);
 export function defineTools(deps = {}) {
     return [
         {
@@ -243,6 +259,45 @@ export function defineTools(deps = {}) {
                 return await request(`/api/cases/${encodeURIComponent(caseId)}`, { method: "DELETE" }, deps);
             }),
         },
+        {
+            name: "aximo_run_case",
+            title: "Run test case",
+            description: "Start a run of a saved test case and return the new sessionId. The case must be apiEnabled (aximo_get_case shows this). All fields except caseId are per-run overrides of the case's stored per-target configuration: omit them to run with the saved defaults. Poll aximo_get_session with the returned sessionId to follow the run; wait at least 5 seconds between polls.",
+            inputSchema: {
+                caseId: z.string().uuid(),
+                model: z
+                    .string()
+                    .optional()
+                    .describe("Agent model override (e.g. 'sonnet', 'haiku', 'auto'). Server-validated."),
+                hostnameOverrideIds: z
+                    .array(z.string().uuid())
+                    .optional()
+                    .describe("Web cases: hostname override ids to apply for this run."),
+                userDeviceId: z
+                    .string()
+                    .uuid()
+                    .optional()
+                    .describe("A user-owned (BYOD) device id; overrides the device bound on the case."),
+                deviceArn: z
+                    .string()
+                    .optional()
+                    .describe("Mobile cases: encrypted device token; overrides the saved device."),
+                deviceName: z.string().optional(),
+                platform: z.enum(["ANDROID", "IOS"]).optional(),
+                uploadArn: z
+                    .string()
+                    .optional()
+                    .describe("Mobile cases: encrypted app upload token; overrides the saved app."),
+                uploadType: z.enum(["own_app", "existing", "sample"]).optional(),
+                appName: z.string().optional(),
+                apps: runAppsSchema
+                    .optional()
+                    .describe("Mobile multi-app runs: up to 3 apps to install; overrides the saved apps and takes precedence over the single-app uploadArn/uploadType/appName fields."),
+            },
+            handler: async ({ caseId, ...body }) => call(async () => {
+                return await request(`/api/triggers/cases/${encodeURIComponent(caseId)}/run`, { method: "POST", body }, deps);
+            }),
+        },
         {
             name: "aximo_create_plan",
             title: "Create test plan",
@@ -323,6 +378,54 @@ export function defineTools(deps = {}) {
                 return await request(`/api/plans/${encodeURIComponent(planId)}`, { method: "PATCH", body }, deps);
             }),
         },
+        {
+            name: "aximo_run_plan",
+            title: "Run test plan",
+            description: "Start a run of a test plan (all its cases) and return the new planRunId, totalCases, and the effective executionMode. The plan must be apiEnabled (aximo_get_plan shows this). All fields except planId are per-run overrides of the plan's stored settings: omit them to run with the saved defaults. Poll aximo_get_plan_run with the returned planRunId to follow the run; wait at least 5 seconds between polls.",
+            inputSchema: {
+                planId: z.string().uuid(),
+                model: z
+                    .string()
+                    .optional()
+                    .describe("Agent model override (e.g. 'sonnet', 'haiku', 'auto'). Server-validated."),
+                executionMode: z
+                    .enum(["parallel", "sequential"])
+                    .optional()
+                    .describe("Override the plan's stored Execution setting for this run only."),
+                mobileConfig: z
+                    .object({
+                    deviceArn: z.string().describe("Encrypted device token."),
+                    deviceName: z.string(),
+                    platform: z.enum(["ANDROID", "IOS"]).optional(),
+                    uploadArn: z.string().optional().describe("Encrypted app upload token."),
+                    uploadType: z.enum(["own_app", "existing", "sample"]).optional(),
+                    appName: z.string().optional(),
+                    apps: runAppsSchema
+                        .optional()
+                        .describe("Takes precedence over the single-app uploadArn/uploadType/appName fields."),
+                })
+                    .optional()
+                    .describe("Device + app for the plan's mobile cases; overrides the plan's stored config."),
+                desktopConfig: z
+                    .object({
+                    devices: z.array(z.object({ userDeviceId: z.string().uuid() })).min(1),
+                })
+                    .optional()
+                    .describe("User-owned (BYOD) desktop devices to run desktop cases on; overrides the plan's stored desktop config."),
+                variables: z
+                    .array(z.object({
+                    name: z
+                        .string()
+                        .describe("Uppercase letters, digits, underscores; must start with a letter."),
+                    value: z.string(),
+                }))
+                    .optional()
+                    .describe("Per-run variable values merged over the plan's stored variables by name; never persisted on the plan."),
+            },
+            handler: async ({ planId, ...body }) => call(async () => {
+                return await request(`/api/triggers/plans/${encodeURIComponent(planId)}/run`, { method: "POST", body }, deps);
+            }),
+        },
         {
             name: "aximo_list_plan_runs",
             title: "List plan runs",

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

@@ -34,12 +34,14 @@ describe("defineTools", () => {
             "aximo_create_case",
             "aximo_update_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_run_plan",
             "aximo_list_plan_runs",
             "aximo_get_plan_run",
             "aximo_save_session_as_case",
@@ -203,6 +205,75 @@ describe("aximo_update_case", () => {
         expect(body).toEqual({ startUrl: null });
     });
 });
+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";
     it("calls /api/plans, passing filters through as query params", async () => {
@@ -304,6 +375,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 +599,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 })));

package/package.json

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