@autifyhq/aximo-cli 0.15.0 → 0.17.0

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

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { z } from "zod";
-import { ARCHIVE_FIRST_HINT, handleApiError, isArchiveFirstConflict } from "../../errors.js";
+import { ARCHIVE_FIRST_HINT, CREDIT_HINT, handleApiError, isArchiveFirstConflict, } from "../../errors.js";
 import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
 import { defineTools } from "./tools.js";
 beforeAll(() => {
@@ -27,6 +27,7 @@ describe("defineTools", () => {
         const names = defineTools().map((t) => t.name);
         expect(names).toEqual([
             "aximo_list_projects",
+            "aximo_get_credits",
             "aximo_list_devices",
             "aximo_list_user_devices",
             "aximo_list_uploads",
@@ -49,6 +50,7 @@ describe("defineTools", () => {
             "aximo_delete_case",
             "aximo_run_case",
             "aximo_create_session",
+            "aximo_cancel_session",
             "aximo_create_plan",
             "aximo_add_case_to_plan",
             "aximo_remove_case_from_plan",
@@ -62,6 +64,9 @@ describe("defineTools", () => {
             "aximo_list_plan_runs",
             "aximo_get_plan_run",
             "aximo_save_session_as_case",
+            "aximo_start_testbox",
+            "aximo_get_testbox",
+            "aximo_stop_testbox",
         ]);
     });
 });
@@ -149,6 +154,37 @@ describe("aximo_list_cases", () => {
         expect(parsed.success).toBe(false);
     });
 });
+describe("aximo_get_credits", () => {
+    it("calls /api/organizations/credits and returns the payload", async () => {
+        const payload = {
+            creditUnit: "platform",
+            granted: 1000,
+            used: 250.5,
+            remaining: 749.5,
+            onDemandRemaining: 0,
+            metered: true,
+            blocked: false,
+        };
+        let captured = null;
+        server.use(http.get(`${TEST_BASE_URL}/api/organizations/credits`, ({ request: req }) => {
+            captured = { method: req.method, url: req.url };
+            return HttpResponse.json(payload);
+        }));
+        const result = await byName(defineTools(), "aximo_get_credits").handler({});
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(captured.method).toBe("GET");
+        expect(new URL(captured.url).pathname).toBe("/api/organizations/credits");
+    });
+    it("says the server is too old instead of returning its HTML 404 page", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/organizations/credits`, () => new HttpResponse("<!DOCTYPE html><html>404</html>", { status: 404 })));
+        const result = await byName(defineTools(), "aximo_get_credits").handler({});
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result)).toEqual({
+            error: "This Aximo server does not support the credit balance yet",
+        });
+    });
+});
 describe("aximo_list_projects", () => {
     it("calls /api/organizations/projects and returns the payload", async () => {
         const payload = { projects: [{ id: "p1", name: "Default" }] };
@@ -288,6 +324,24 @@ describe("aximo_wait_for_session", () => {
         expect(parsePayload(result)).toEqual({ error: "Session not found" });
     });
 });
+describe("aximo_cancel_session", () => {
+    const sessionId = "78787878-7878-4787-9787-787878787878";
+    it("POSTs the cancel endpoint and returns the terminated session", async () => {
+        const payload = { success: true, sessionId, status: "terminated" };
+        server.use(http.post(`${TEST_BASE_URL}/api/sessions/${sessionId}/cancel`, () => HttpResponse.json(payload)));
+        const result = await byName(defineTools(), "aximo_cancel_session").handler({ sessionId });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+    });
+    it("reports a finished session as an error with no archive hint", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/sessions/${sessionId}/cancel`, () => HttpResponse.json({ error: "Cannot cancel a session that has already finished" }, { status: 409 })));
+        const result = await byName(defineTools(), "aximo_cancel_session").handler({ sessionId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result)).toEqual({
+            error: "Cannot cancel a session that has already finished",
+        });
+    });
+});
 describe("aximo_create_session", () => {
     const projectId = "12121212-1212-4212-9212-121212121212";
     it("POSTs /api/sessions with the prompt and device and returns sessionId", async () => {
@@ -370,7 +424,10 @@ describe("aximo_run_case", () => {
         const tool = byName(defineTools(), "aximo_run_case");
         const result = await tool.handler({ caseId });
         expect(result.isError).toBe(true);
-        expect(parsePayload(result).error).toBe("Insufficient credits to start session");
+        expect(parsePayload(result)).toEqual({
+            error: "Insufficient credits to start session",
+            hint: CREDIT_HINT,
+        });
     });
     it("maps a 429 to a rate-limit error an agent can back off on", async () => {
         server.use(http.post(`${TEST_BASE_URL}/api/triggers/cases/${caseId}/run`, () => HttpResponse.json({ error: "Rate limit exceeded. Try again later." }, { status: 429, headers: { "Retry-After": "60" } })));

package/dist/commands/schema.js

@@ -42,6 +42,10 @@ export function getSchema() {
                 cmd("get", "GET /api/sessions/{sessionId}", [
                     arg("sessionId", "positional", "Session ID", true),
                 ]),
+                cmd("cancel", "POST /api/sessions/{sessionId}/cancel", [
+                    arg("sessionId", "positional", "Session ID", true),
+                    arg("dry-run", "boolean", "Validate and show request without calling API"),
+                ]),
                 cmd("save-as-case", "POST /api/sessions/{sessionId}/save-as-case", [
                     arg("sessionId", "positional", "Session ID", true),
                     arg("title", "string", ""),
@@ -105,7 +109,7 @@ export function getSchema() {
                     cmd("run", "POST /api/triggers/plans/{planId}/run", [
                         arg("planId", "positional", "Plan ID", true),
                         arg("model", "string", ""),
-                        arg("mobile-config", "string", "JSON object string"),
+                        arg("mobile-config", "string", "JSON object string: fallback device + app, used only for mobile cases with no device saved on the plan or the case"),
                         ...MUTATE_ARGS,
                     ]),
                     cmd("get", "GET /api/triggers/plans/{planId}/runs/{planRunId}", [

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

@@ -0,0 +1,20 @@
+import { type ClientDeps } from "../../client.js";
+import { type DryRunResult } from "../../mutate.js";
+import type { CancelSessionResult, Envelope } from "../../types.js";
+export interface SessionCancelOptions {
+    sessionId?: unknown;
+    dryRun?: unknown;
+}
+export declare function runSessionCancel(options: SessionCancelOptions, deps?: ClientDeps): Promise<Envelope<CancelSessionResult | DryRunResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly sessionId: {
+        readonly type: "positional";
+        readonly description: "Session 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/session/cancel.js

@@ -0,0 +1,39 @@
+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 runSessionCancel(options, deps) {
+    let sessionId;
+    try {
+        sessionId = requireId("sessionId", options.sessionId);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    const path = `/api/sessions/${encodeURIComponent(sessionId)}/cancel`;
+    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: "cancel",
+        description: "Cancel a queued or running session (stops it on its device)",
+    },
+    args: {
+        sessionId: { type: "positional", description: "Session ID", required: true },
+        "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
+    },
+    async run({ args }) {
+        printResult(await runSessionCancel({ sessionId: args.sessionId, dryRun: args["dry-run"] }));
+    },
+});

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),
+        cancel: () => import("./cancel.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

@@ -3,6 +3,7 @@ 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 { runSessionCancel } from "./cancel.js";
 import { runSessionCreate } from "./create.js";
 import { runSessionExport } from "./export.js";
 import { runSessionGet } from "./get.js";
@@ -130,6 +131,43 @@ describe("runSessionGet", () => {
             expect(result.error.code).toBe("not_found");
     });
 });
+describe("runSessionCancel", () => {
+    it("POSTs the cancel endpoint and returns the terminated session", async () => {
+        let method;
+        server.use(http.post(`${TEST_BASE_URL}/api/sessions/s1/cancel`, ({ request: req }) => {
+            method = req.method;
+            return HttpResponse.json({ success: true, sessionId: "s1", status: "terminated" });
+        }));
+        const result = await runSessionCancel({ sessionId: "s1" });
+        expect(method).toBe("POST");
+        expect(result).toEqual({
+            ok: true,
+            data: { success: true, sessionId: "s1", status: "terminated" },
+        });
+    });
+    it("shows the request without calling the API on --dry-run", async () => {
+        const result = await runSessionCancel({ sessionId: "s1", dryRun: true });
+        expect(result).toEqual({
+            ok: true,
+            data: { dryRun: true, method: "POST", url: `${TEST_BASE_URL}/api/sessions/s1/cancel` },
+        });
+    });
+    it("rejects an empty id", async () => {
+        const result = await runSessionCancel({ sessionId: "" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+    it("maps a finished session to conflict without the archive hint", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/sessions/s1/cancel`, () => HttpResponse.json({ error: "Cannot cancel a session that has already finished" }, { status: 409 })));
+        const result = await runSessionCancel({ sessionId: "s1" });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("conflict");
+            expect(result.error.hint).toBeUndefined();
+        }
+    });
+});
 describe("runSessionExport", () => {
     const sessionId = "44444444-4444-4444-9444-444444444444";
     const defaultPdf = resolve(`${sessionId}.pdf`);

package/dist/commands/trigger/plan/run.d.ts

@@ -20,7 +20,7 @@ declare const _default: import("citty").CommandDef<{
     };
     readonly "mobile-config": {
         readonly type: "string";
-        readonly description: "JSON object string";
+        readonly description: "JSON object string: fallback device + app, used only for mobile cases with no device saved on the plan or the case";
     };
     readonly "execution-mode": {
         readonly type: "string";

package/dist/commands/trigger/plan/run.js

@@ -48,7 +48,10 @@ export default defineCommand({
     args: {
         planId: { type: "positional", required: true },
         model: { type: "string" },
-        "mobile-config": { type: "string", description: "JSON object string" },
+        "mobile-config": {
+            type: "string",
+            description: "JSON object string: fallback device + app, used only for mobile cases with no device saved on the plan or the case",
+        },
         "execution-mode": {
             type: "string",
             description: "parallel or sequential (defaults to the plan's stored setting)",

package/dist/errors.d.ts

@@ -2,6 +2,8 @@ import type { ErrorEnvelope } from "./types.js";
 export declare function describeDetails(details: unknown): string | undefined;
 export declare function withDetails(message: string, details: unknown): string;
 export declare function featureHint(message: string, details: unknown): string | undefined;
+export declare const CREDIT_HINT = "The organization is out of credits. Ask an Aximo organization admin to add credits, then retry.";
+export declare function creditHint(message: string): string | undefined;
 export declare const ARCHIVE_FIRST_HINT = "Archive the resource first, then retry: `aximo case archive <caseId>` / `aximo plan archive <planId>` (MCP: aximo_archive_case / aximo_archive_plan).";
 export declare function isArchiveFirstConflict(message: string): boolean;
 export declare function handleApiError(error: unknown): ErrorEnvelope;

package/dist/errors.js

@@ -85,6 +85,10 @@ export function featureHint(message, details) {
     }
     return undefined;
 }
+export const CREDIT_HINT = "The organization is out of credits. Ask an Aximo organization admin to add credits, then retry.";
+export function creditHint(message) {
+    return /insufficient credits/i.test(message) ? CREDIT_HINT : undefined;
+}
 const NOT_FOUND_HINT = "Check the ID exists and you have access. List resources: aximo project list / aximo device list / aximo upload list";
 const AUTH_HINT = "Run `aximo configure` to save credentials, or set AXIMO_API_KEY via `export AXIMO_API_KEY=your-key` or `node --env-file=.env`.";
 // 403 is a permission outcome, not a credentials problem, so it no longer routes
@@ -142,6 +146,7 @@ export function handleApiError(error) {
             // when the server says which role is missing. Never the credentials hint: a
             // 403 means the key is valid.
             const hint = featureHint(error.message, details) ??
+                creditHint(error.message) ??
                 (/admin|owner/i.test(message) ? ADMIN_ROLE_HINT : undefined);
             return formatError("forbidden", message, false, hint);
         }

package/dist/errors.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { describeDetails, featureHint, handleApiError, withDetails } from "./errors.js";
+import { CREDIT_HINT, describeDetails, featureHint, handleApiError, withDetails, } from "./errors.js";
 function httpErr(status, message = `status ${status}`, retryAfter) {
     const err = Object.assign(new Error(message), { status });
     if (retryAfter !== undefined)
@@ -27,6 +27,11 @@ describe("handleApiError", () => {
         expect(r.error.code).toBe("forbidden");
         expect(r.error.hint).toContain("admin or owner");
     });
+    it("adds the credit hint when the organization is out of credits", () => {
+        const r = handleApiError(httpErr(403, "Insufficient credits to start session"));
+        expect(r.error.code).toBe("forbidden");
+        expect(r.error.hint).toBe(CREDIT_HINT);
+    });
     it("maps 404 to not_found with list hint", () => {
         const r = handleApiError(httpErr(404));
         expect(r.error.code).toBe("not_found");

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { runPlanRemoveCase } from "./commands/plan/remove-case.js";
 export { runProjectList } from "./commands/project/list.js";
 export { runSessionCreate } from "./commands/session/create.js";
 export { runSessionGet } from "./commands/session/get.js";
+export { runSessionCancel } from "./commands/session/cancel.js";
 export { runSessionSaveAsCase } from "./commands/session/save-as-case.js";
 export { runTriggerCaseGet } from "./commands/trigger/case/get.js";
 export { runTriggerCaseRun } from "./commands/trigger/case/run.js";

package/dist/index.js

@@ -11,6 +11,7 @@ export { runPlanRemoveCase } from "./commands/plan/remove-case.js";
 export { runProjectList } from "./commands/project/list.js";
 export { runSessionCreate } from "./commands/session/create.js";
 export { runSessionGet } from "./commands/session/get.js";
+export { runSessionCancel } from "./commands/session/cancel.js";
 export { runSessionSaveAsCase } from "./commands/session/save-as-case.js";
 export { runTriggerCaseGet } from "./commands/trigger/case/get.js";
 export { runTriggerCaseRun } from "./commands/trigger/case/run.js";

package/dist/types.d.ts

@@ -231,6 +231,15 @@ export interface Project {
     name?: string | undefined;
     [key: string]: unknown;
 }
+export interface CreditBalance {
+    creditUnit: "legacy" | "platform";
+    granted: number;
+    used: number;
+    remaining: number;
+    onDemandRemaining: number;
+    metered: boolean;
+    blocked: boolean;
+}
 export interface CreateCaseInput {
     projectId: string;
     scenario: string;
@@ -305,6 +314,11 @@ export interface CreatePlanResult {
 export interface PlanCaseResult {
     success: boolean;
 }
+export interface CancelSessionResult {
+    success: boolean;
+    sessionId: string;
+    status: "terminated";
+}
 export interface SaveSessionAsCaseInput {
     title?: string | undefined;
     type?: Exclude<CaseType, "multi_device"> | undefined;

package/package.json

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