@autifyhq/aximo-cli 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,6 +1,18 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from "citty";
 import pkg from "../package.json" with { type: "json" };
+// citty's --help prints to stdout; route to stderr for `mcp` since its stdout
+// is JSON-RPC.
+const args = process.argv.slice(2);
+if (args[0] === "mcp" && args.some((a) => a === "--help" || a === "-h")) {
+    process.stderr.write(`aximo mcp — stdio MCP server exposing read-only Aximo data.\n` +
+        `\n` +
+        `Wire into an MCP client (e.g. Claude Desktop, Claude Code) by pointing it\n` +
+        `at this binary. Auth uses ~/.aximo/config.json (run \`aximo configure\`).\n` +
+        `\n` +
+        `Stdout is reserved for JSON-RPC messages — diagnostics go to stderr.\n`);
+    process.exit(0);
+}
 const main = defineCommand({
     meta: {
         name: "aximo",
@@ -16,6 +28,7 @@ const main = defineCommand({
         upload: () => import("./commands/upload/index.js").then((m) => m.default),
         project: () => import("./commands/project/index.js").then((m) => m.default),
         schema: () => import("./commands/schema.js").then((m) => m.default),
+        mcp: () => import("./commands/mcp/index.js").then((m) => m.default),
     },
 });
 runMain(main);

package/dist/commands/device/index.js

@@ -1,6 +1,9 @@
 import { defineCommand } from "citty";
 export default defineCommand({
-    meta: { name: "device", description: "Device commands" },
+    meta: {
+        name: "device",
+        description: "BYOD device commands (register/connect/status/...); 'device list' lists Device Farm mobile devices",
+    },
     subCommands: {
         list: () => import("./list.js").then((m) => m.default),
         register: () => import("./register.js").then((m) => m.default),

package/dist/commands/device/list.js

@@ -26,7 +26,10 @@ export async function runDeviceList(options = {}, deps) {
     }
 }
 export default defineCommand({
-    meta: { name: "list", description: "List Aximo devices" },
+    meta: {
+        name: "list",
+        description: "List Device Farm mobile devices (ANDROID/IOS) — not BYOD; for your registered machines use 'device status'",
+    },
     args: {
         platform: { type: "string", description: "ANDROID | IOS" },
         "available-only": { type: "boolean", description: "Only available devices" },

package/dist/commands/device/register.js

@@ -65,7 +65,7 @@ export async function runDeviceRegister(options, deps) {
     }
 }
 export default defineCommand({
-    meta: { name: "register", description: "Register this machine as an Aximo device" },
+    meta: { name: "register", description: "Register this machine as a BYOD device" },
     args: {
         name: {
             type: "string",

package/dist/commands/device/status.js

@@ -13,7 +13,10 @@ export async function runDeviceStatus(deps) {
     }
 }
 export default defineCommand({
-    meta: { name: "status", description: "List your registered devices" },
+    meta: {
+        name: "status",
+        description: "List your registered BYOD devices with online/offline status — not Device Farm (see 'device list')",
+    },
     async run() {
         printResult(await runDeviceStatus());
     },

package/dist/commands/mcp/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("citty").CommandDef<{}>;
+export default _default;

package/dist/commands/mcp/index.js

@@ -0,0 +1,29 @@
+import { defineCommand } from "citty";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "./server.js";
+import { getApiKey, getBaseUrl } from "../../client.js";
+// --help / -h are intercepted in cli.ts before citty parses argv.
+export default defineCommand({
+    meta: {
+        name: "mcp",
+        description: "Run an MCP server exposing Aximo data over stdio",
+    },
+    args: {},
+    async run() {
+        // Fail fast before the JSON-RPC handshake; diagnostics go to stderr only.
+        try {
+            getApiKey();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`aximo mcp: ${message}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const baseUrl = getBaseUrl();
+        process.stderr.write(`aximo mcp: serving stdio MCP against ${baseUrl}\n`);
+        const server = createMcpServer();
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    },
+});

package/dist/commands/mcp/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ClientDeps } from "../../client.js";
+export declare function createMcpServer(deps?: ClientDeps): McpServer;

package/dist/commands/mcp/server.js

@@ -0,0 +1,19 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { defineTools } from "./tools.js";
+import pkg from "../../../package.json" with { type: "json" };
+export function createMcpServer(deps = {}) {
+    const server = new McpServer({
+        name: "aximo",
+        version: pkg.version,
+    });
+    for (const tool of defineTools(deps)) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, 
+        // biome-ignore lint/suspicious/noExplicitAny: SDK's registerTool signature is generic over schema; safe at runtime
+        tool.handler);
+    }
+    return server;
+}

package/dist/commands/mcp/server.test.d.ts

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

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

@@ -0,0 +1,84 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { HttpResponse, TEST_BASE_URL, http, server } from "../../test-utils.js";
+import { createMcpServer } from "./server.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());
+async function connect() {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const mcpServer = createMcpServer();
+    const client = new Client({ name: "test-client", version: "0.0.0" }, { capabilities: {} });
+    await Promise.all([mcpServer.connect(serverTransport), client.connect(clientTransport)]);
+    return {
+        client,
+        cleanup: async () => {
+            await client.close();
+            await mcpServer.close();
+        },
+    };
+}
+describe("createMcpServer wiring", () => {
+    it("exposes all 10 tools through tools/list with valid JSON Schema", async () => {
+        const { client, cleanup } = await connect();
+        try {
+            const { tools } = await client.listTools();
+            expect(tools.map((t) => t.name).sort()).toEqual([
+                "aximo_get_case",
+                "aximo_get_session",
+                "aximo_get_session_capture",
+                "aximo_get_session_snapshot",
+                "aximo_get_session_messages",
+                "aximo_get_session_screenshots",
+                "aximo_get_session_timeline",
+                "aximo_list_cases",
+                "aximo_list_projects",
+                "aximo_list_sessions",
+            ].sort());
+            const timeline = tools.find((t) => t.name === "aximo_get_session_timeline");
+            expect(timeline?.inputSchema?.required).toContain("sessionId");
+        }
+        finally {
+            await cleanup();
+        }
+    });
+    it("dispatches a tools/call and returns the backend payload", async () => {
+        const sessionId = "77777777-7777-4777-9777-777777777777";
+        const payload = { sessionId, stepCount: 0, steps: [] };
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/timeline`, () => HttpResponse.json(payload)));
+        const { client, cleanup } = await connect();
+        try {
+            const result = await client.callTool({
+                name: "aximo_get_session_timeline",
+                arguments: { sessionId },
+            });
+            expect(result.isError).toBeFalsy();
+            const content = result.content;
+            const text = content[0].text;
+            expect(JSON.parse(text)).toEqual(payload);
+        }
+        finally {
+            await cleanup();
+        }
+    });
+    it("returns isError with a validation message when input fails the schema", async () => {
+        const { client, cleanup } = await connect();
+        try {
+            const result = await client.callTool({
+                name: "aximo_get_session_timeline",
+                arguments: { sessionId: "not-a-uuid" },
+            });
+            expect(result.isError).toBe(true);
+            const content = result.content;
+            expect(content[0].text).toMatch(/Invalid uuid|Input validation/);
+        }
+        finally {
+            await cleanup();
+        }
+    });
+});

package/dist/commands/mcp/tools.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { type ClientDeps } from "../../client.js";
+interface ToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export interface Tool<TInput extends z.ZodRawShape = z.ZodRawShape> {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: TInput;
+    handler: (input: z.infer<z.ZodObject<TInput>>) => Promise<ToolResult>;
+}
+export declare function defineTools(deps?: ClientDeps): Tool[];
+export {};

package/dist/commands/mcp/tools.js

@@ -0,0 +1,198 @@
+import { z } from "zod";
+import { request } from "../../client.js";
+function ok(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+}
+function err(message, hint) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: message, ...(hint ? { hint } : {}) }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+async function call(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (e) {
+        if (!(e instanceof Error))
+            return err(String(e));
+        const status = e.status;
+        if (status === 401)
+            return err("Unauthorized: check AXIMO_API_KEY", "Run `aximo configure`.");
+        if (status === 403) {
+            return err(e.message || "Forbidden", "API key may not have access to this resource.");
+        }
+        if (status === 404)
+            return err(e.message || "Not found");
+        if (status === 429)
+            return err("Rate limited", "Aximo enforces a daily session limit.");
+        if (typeof status === "number")
+            return err(`HTTP ${status}: ${e.message}`);
+        if (e.message.startsWith("No API key configured")) {
+            return err("API key not configured", "Run `aximo configure` and restart the MCP server.");
+        }
+        const cause = e.cause;
+        const networkCode = cause?.code;
+        if (networkCode) {
+            return err(`Network error (${networkCode}): ${cause?.message ?? e.message}`, "Check AXIMO_BASE_URL and your network connection.");
+        }
+        return err(e.message);
+    }
+}
+function buildQuery(params) {
+    const out = {};
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== "")
+            out[k] = v;
+    }
+    return out;
+}
+export function defineTools(deps = {}) {
+    return [
+        {
+            name: "aximo_list_projects",
+            title: "List workspaces",
+            description: "List workspaces (projects) available to your organization. Use a project's id when listing sessions or cases.",
+            inputSchema: {},
+            handler: async () => call(async () => {
+                const res = await request("/api/organizations/projects", {}, deps);
+                return res;
+            }),
+        },
+        {
+            name: "aximo_list_sessions",
+            title: "List sessions",
+            description: "List sessions visible to your organization, newest first. Filter by projectId, caseId, or status. Paginated.",
+            inputSchema: {
+                projectId: z.string().uuid().optional(),
+                caseId: z.string().uuid().optional(),
+                status: z.string().optional(),
+                page: z.number().int().positive().optional(),
+                pageSize: z.number().int().positive().max(100).optional(),
+            },
+            handler: async (input) => call(async () => {
+                return await request("/api/sessions", { query: buildQuery(input) }, deps);
+            }),
+        },
+        {
+            name: "aximo_get_session",
+            title: "Get session",
+            description: "Get session metadata, status, summary, observations, credits used, and counts (screenshots, tool calls).",
+            inputSchema: {
+                sessionId: z.string().uuid(),
+            },
+            handler: async ({ sessionId }) => call(async () => {
+                return await request(`/api/sessions/${encodeURIComponent(sessionId)}`, {}, deps);
+            }),
+        },
+        {
+            name: "aximo_get_session_messages",
+            title: "Get session messages",
+            description: "Get the message timeline (tool calls, assistant text, user input) for a session. Cursor-paginated.",
+            inputSchema: {
+                sessionId: z.string().uuid(),
+                cursor: z.string().optional(),
+                limit: z.number().int().positive().max(100).optional(),
+                order: z.enum(["asc", "desc"]).optional(),
+            },
+            handler: async ({ sessionId, ...rest }) => call(async () => {
+                return await request(`/api/sessions/${encodeURIComponent(sessionId)}/messages`, { query: buildQuery(rest) }, deps);
+            }),
+        },
+        {
+            name: "aximo_get_session_screenshots",
+            title: "Get session screenshots",
+            description: "Get screenshots captured during a session, ordered by capture time. URLs are presigned (S3) or relative.",
+            inputSchema: {
+                sessionId: z.string().uuid(),
+                cursor: z.string().optional(),
+                limit: z.number().int().positive().max(100).optional(),
+                order: z.enum(["asc", "desc"]).optional(),
+            },
+            handler: async ({ sessionId, ...rest }) => call(async () => {
+                return await request(`/api/sessions/${encodeURIComponent(sessionId)}/screenshots`, { query: buildQuery(rest) }, deps);
+            }),
+        },
+        {
+            name: "aximo_get_session_timeline",
+            title: "Get session timeline",
+            description: "Get the merged step timeline: each step pairs a message (tool call, assistant turn, user input) with its screenshots. This is the recommended endpoint when generating a Playwright spec from a session.",
+            inputSchema: {
+                sessionId: z.string().uuid(),
+            },
+            handler: async ({ sessionId }) => call(async () => {
+                return await request(`/api/sessions/${encodeURIComponent(sessionId)}/timeline`, {}, deps);
+            }),
+        },
+        {
+            name: "aximo_get_session_capture",
+            title: "Get session CDP capture",
+            description: "Get the CDP-derived capture metadata for a session: ordered timestamped events (actions, navigations, network XHR/fetch, console, exceptions, snapshot triggers), browser context, and post-session storage state. By default snapshots[] contains metadata only (id, url, title, domBytes, axBytes) — call aximo_get_session_snapshot to fetch a single snapshot's DOM/AX content, or pass includeSnapshots: 'full' to inline all of them (can be multi-MB). Cookie values are redacted by default — pass includeCookieValues: true only when you genuinely need them (e.g. to emit a Playwright context.storageState()). Returns 404 if the org doesn't have the CDP capture feature flag enabled or the session ran without capture.",
+            inputSchema: {
+                sessionId: z.string().uuid(),
+                includeSnapshots: z
+                    .enum(["none", "metadata", "full"])
+                    .optional()
+                    .describe("Default 'metadata'. Use 'full' only when you need DOM/AX content inline."),
+                includeCookieValues: z
+                    .boolean()
+                    .optional()
+                    .describe("Default false. When true, cookie 'value' fields are returned unmasked — needed for Playwright storageState export."),
+            },
+            handler: async ({ sessionId, includeSnapshots, includeCookieValues }) => call(async () => {
+                const query = {};
+                if (includeSnapshots)
+                    query["includeSnapshots"] = includeSnapshots;
+                if (includeCookieValues)
+                    query["includeCookieValues"] = "true";
+                return await request(`/api/sessions/${encodeURIComponent(sessionId)}/capture`, { query }, deps);
+            }),
+        },
+        {
+            name: "aximo_get_session_snapshot",
+            title: "Get one DOM+AX snapshot",
+            description: "Fetch a single DOM + accessibility-tree snapshot by id (from aximo_get_session_capture's snapshots[] list). Use this instead of pulling the whole capture blob when you only need one page's structure (a single snapshot can be 100 KB – 5 MB).",
+            inputSchema: {
+                sessionId: z.string().uuid(),
+                snapshotId: z.string().uuid(),
+            },
+            handler: async ({ sessionId, snapshotId }) => call(async () => {
+                return await request(`/api/sessions/${encodeURIComponent(sessionId)}/snapshots/${encodeURIComponent(snapshotId)}`, {}, deps);
+            }),
+        },
+        {
+            name: "aximo_list_cases",
+            title: "List test cases",
+            description: "List saved test cases for a workspace. Filter by type, search, or directory.",
+            inputSchema: {
+                projectId: z.string().uuid(),
+                type: z.enum(["web", "mobile"]).optional(),
+                search: z.string().optional(),
+                directoryId: z.string().optional(),
+                page: z.number().int().positive().optional(),
+                pageSize: z.number().int().positive().max(100).optional(),
+            },
+            handler: async (input) => call(async () => {
+                return await request("/api/cases", { query: buildQuery(input) }, deps);
+            }),
+        },
+        {
+            name: "aximo_get_case",
+            title: "Get test case",
+            description: "Get the full scenario text and metadata for a saved test case. Useful for grounding generated Playwright specs.",
+            inputSchema: {
+                caseId: z.string().uuid(),
+            },
+            handler: async ({ caseId }) => call(async () => {
+                return await request(`/api/cases/${encodeURIComponent(caseId)}`, {}, deps);
+            }),
+        },
+    ];
+}

package/dist/commands/mcp/tools.test.d.ts

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

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

@@ -0,0 +1,205 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { HttpResponse, TEST_BASE_URL, http, server } from "../../test-utils.js";
+import { defineTools } from "./tools.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());
+function byName(tools, name) {
+    const t = tools.find((x) => x.name === name);
+    if (!t)
+        throw new Error(`tool ${name} not found`);
+    return t;
+}
+function parsePayload(result) {
+    return JSON.parse(result.content[0].text);
+}
+describe("defineTools", () => {
+    it("registers the expected tool names", () => {
+        const names = defineTools().map((t) => t.name);
+        expect(names).toEqual([
+            "aximo_list_projects",
+            "aximo_list_sessions",
+            "aximo_get_session",
+            "aximo_get_session_messages",
+            "aximo_get_session_screenshots",
+            "aximo_get_session_timeline",
+            "aximo_get_session_capture",
+            "aximo_get_session_snapshot",
+            "aximo_list_cases",
+            "aximo_get_case",
+        ]);
+    });
+});
+describe("aximo_get_session_timeline", () => {
+    it("calls /api/sessions/:id/timeline and returns the JSON payload", async () => {
+        const sessionId = "11111111-1111-4111-9111-111111111111";
+        const payload = { sessionId, stepCount: 1, steps: [] };
+        let captured = null;
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/timeline`, ({ request: req }) => {
+            captured = req.headers.get("x-api-key");
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_get_session_timeline");
+        const result = await tool.handler({ sessionId });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(captured).toBe("test-key");
+    });
+    it("returns a structured error when the API returns 404", async () => {
+        const sessionId = "22222222-2222-4222-9222-222222222222";
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/timeline`, () => HttpResponse.json({ error: "Session not found" }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_get_session_timeline");
+        const result = await tool.handler({ sessionId });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result)).toMatchObject({ error: "Session not found" });
+    });
+    it("returns a structured error when the API returns 401", async () => {
+        const sessionId = "33333333-3333-4333-9333-333333333333";
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/timeline`, () => HttpResponse.json({ error: "Unauthorized" }, { status: 401 })));
+        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).toMatch(/Unauthorized/);
+        expect(payload.hint).toMatch(/configure/);
+    });
+});
+describe("aximo_list_sessions", () => {
+    it("passes through query parameters", async () => {
+        let url = null;
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions`, ({ request: req }) => {
+            url = new URL(req.url);
+            return HttpResponse.json({
+                items: [],
+                totalCount: 0,
+                page: 1,
+                pageSize: 25,
+                totalPages: 0,
+            });
+        }));
+        const tool = byName(defineTools(), "aximo_list_sessions");
+        await tool.handler({
+            projectId: "44444444-4444-4444-8444-444444444444",
+            status: "succeeded",
+            page: 2,
+        });
+        expect(url).not.toBeNull();
+        expect(url.searchParams.get("projectId")).toBe("44444444-4444-4444-8444-444444444444");
+        expect(url.searchParams.get("status")).toBe("succeeded");
+        expect(url.searchParams.get("page")).toBe("2");
+    });
+});
+describe("aximo_get_case", () => {
+    it("returns the case scenario payload", async () => {
+        const caseId = "55555555-5555-4555-9555-555555555555";
+        const payload = {
+            id: caseId,
+            projectId: "p1",
+            type: "web",
+            title: "Login flow",
+            scenario: "Given I navigate to login\nThen I am logged in",
+            format: "gherkin",
+        };
+        server.use(http.get(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json(payload)));
+        const tool = byName(defineTools(), "aximo_get_case");
+        const result = await tool.handler({ caseId });
+        expect(parsePayload(result)).toEqual(payload);
+    });
+});
+describe("aximo_list_cases", () => {
+    it("requires projectId at schema time", () => {
+        const tool = byName(defineTools(), "aximo_list_cases");
+        // biome-ignore lint/suspicious/noExplicitAny: zod runtime check
+        const parsed = tool.inputSchema.projectId.safeParse(undefined);
+        expect(parsed.success).toBe(false);
+    });
+});
+describe("aximo_list_projects", () => {
+    it("calls /api/organizations/projects and returns the payload", async () => {
+        const payload = { projects: [{ id: "p1", name: "Default" }] };
+        let captured = null;
+        server.use(http.get(`${TEST_BASE_URL}/api/organizations/projects`, ({ request: req }) => {
+            captured = { method: req.method, url: req.url };
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_list_projects");
+        const result = await tool.handler({});
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(captured).not.toBeNull();
+        expect(captured.method).toBe("GET");
+        expect(new URL(captured.url).pathname).toBe("/api/organizations/projects");
+    });
+});
+describe("call() error mapping", () => {
+    const sessionId = "66666666-6666-4666-9666-666666666666";
+    it("maps 403 with the original message and a hint", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/timeline`, () => HttpResponse.json({ error: "Forbidden by policy" }, { status: 403 })));
+        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).toMatch(/Forbidden by policy|Forbidden/);
+        expect(payload.hint).toMatch(/access/i);
+    });
+    it("preserves the backend's 404 message instead of squashing to 'Not found'", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/timeline`, () => HttpResponse.json({ error: "Session was archived" }, { status: 404 })));
+        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("Session was archived");
+    });
+    it("flags 429 with the rate-limit hint", 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);
+    });
+    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 })));
+        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).toMatch(/^HTTP 500/);
+    });
+    it("returns a config-error hint when the API key is missing mid-session", async () => {
+        const prev = process.env["AXIMO_API_KEY"];
+        delete process.env["AXIMO_API_KEY"];
+        try {
+            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("API key not configured");
+            expect(payload.hint).toMatch(/aximo configure/);
+        }
+        finally {
+            process.env["AXIMO_API_KEY"] = prev;
+        }
+    });
+    it("surfaces network failures with code + remediation hint", async () => {
+        // MSW intercepts and reshapes thrown errors, so inject a fetch that throws
+        // a fetch-style network error directly via ClientDeps.
+        const networkErr = new TypeError("fetch failed");
+        networkErr.cause = {
+            code: "ENOTFOUND",
+            message: "getaddrinfo ENOTFOUND aximo.test",
+        };
+        const fetchImpl = (() => Promise.reject(networkErr));
+        const tool = byName(defineTools({ fetchImpl }), "aximo_get_session_timeline");
+        const result = await tool.handler({ sessionId });
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toMatch(/Network error \(ENOTFOUND\)/);
+        expect(payload.hint).toMatch(/AXIMO_BASE_URL/);
+    });
+});

package/dist/commands/schema.js

@@ -74,8 +74,8 @@ export function getSchema() {
                     ]),
                 ]),
             ]),
-            cmd("device", "Device commands", [], [
-                cmd("list", "GET /api/devices", [
+            cmd("device", "Device Farm mobile device listing (BYOD device commands are not exposed via schema)", [], [
+                cmd("list", "GET /api/devices — list Device Farm mobile devices (ANDROID/IOS)", [
                     arg("platform", "string", "ANDROID | IOS"),
                     arg("available-only", "boolean", ""),
                 ]),

package/dist/types.d.ts

@@ -119,3 +119,113 @@ export interface Project {
     name?: string | undefined;
     [key: string]: unknown;
 }
+export interface PaginatedList<T> {
+    items: T[];
+    totalCount: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+export interface CursorPage<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+export interface SessionListItem {
+    id: string;
+    projectId: string | null;
+    caseId: string | null;
+    title: string;
+    prompt: string;
+    platform: string;
+    status: string;
+    result: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    createdAt: string;
+    durationMs: number | null;
+}
+export interface SessionMessage {
+    id: string;
+    role: string;
+    content: string;
+    metadata?: unknown;
+    createdAt: string;
+}
+export interface SessionScreenshot {
+    id: string;
+    url: string;
+    messageId: string | null;
+    width: number | null;
+    height: number | null;
+    resizedWidth: number | null;
+    resizedHeight: number | null;
+    capturedAt: string;
+}
+export interface TimelineStep {
+    index: number;
+    messageId: string;
+    role: string;
+    toolName: string | null;
+    toolInput: unknown;
+    toolOutput: unknown;
+    text: string | null;
+    createdAt: string;
+    screenshots: SessionScreenshot[];
+}
+export interface SessionTimeline {
+    sessionId: string;
+    stepCount: number;
+    steps: TimelineStep[];
+}
+export interface CaseListItem {
+    id: string;
+    projectId: string;
+    type: string;
+    title: string | null;
+    description: string | null;
+    startUrl: string | null;
+    lastRunAt: string | null;
+    lastStatus: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CaptureSnapshot {
+    id: string;
+    ts: number;
+    messageId: string | null;
+    trigger: "screenshot" | "page_load";
+    targetId: string;
+    url: string;
+    title: string;
+    dom: unknown;
+    axTree: unknown;
+}
+export interface SessionCapture {
+    sessionId: string;
+    platform: string;
+    startedAt: string | null;
+    endedAt: string | null;
+    browserContext: Record<string, unknown> | null;
+    events: Array<Record<string, unknown>>;
+    storageState: Record<string, unknown> | null;
+    snapshotCount: number;
+    snapshotsPrefix: string | null;
+    truncated: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CaseDetail {
+    id: string;
+    projectId: string;
+    type: string;
+    title: string | null;
+    description: string | null;
+    scenario: string;
+    format: string;
+    startUrl: string | null;
+    apiEnabled: boolean;
+    lastRunAt: string | null;
+    lastStatus: string | null;
+    createdAt: string;
+    updatedAt: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autifyhq/aximo-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Autify Aximo Command Line Interface (CLI)",
   "keywords": [
     "autify",
@@ -36,8 +36,10 @@
     "access": "public"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "citty": "0.2.2",
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@commitlint/cli": "20.5.0",