@almyty/agents 1.2.0 → 1.3.0

package/dist/index.js

@@ -1,146 +1,174 @@
 #!/usr/bin/env node
 /**
- * @almyty/agents — list, get, run, and inspect almyty agents.
+ * @almyty/agents — list, inspect, and run almyty agents.
  *
  *   npx @almyty/agents list
  *   npx @almyty/agents get <name|id>
- *   npx @almyty/agents run <name|id> [--input '<json>']
+ *   npx @almyty/agents run <name|id> --input '<json>' --watch
  *   npx @almyty/agents runs <name|id>
- *   npx @almyty/agents cancel <name|id> <runId>
+ *   npx @almyty/agents inspect <name|id> <runId>
+ *   npx @almyty/agents trace <name|id> <executionId>
  *
  * Reads credentials from ~/.almyty/credentials.json (created by
  * `npx @almyty/auth login`).
  */
-import { AlmytyClient, resolveCredentialsOrExit } from '@almyty/client';
-const VERSION = '0.1.0';
+import { AlmytyClient, resolveCredentials, } from '@almyty/client';
+import { parseArgs, flagNumber, flagString } from './args.js';
+import { EXIT } from './exit-codes.js';
+import { VERSION } from './version.js';
+import { formatAgentDetail, formatAgentLine, formatExecutionSummary, formatNodeResults, formatRunDetail, formatRunSummary, formatStep, formatTrace, notActiveMessage, runSucceeded, } from './format.js';
+/** Flags that are switches, so they never swallow the next token. */
+const BOOLEAN_FLAGS = ['watch', 'steps'];
 function printHelp() {
-    console.log(`
-@almyty/agents v${VERSION}
+    console.log(`@almyty/agents v${VERSION}
 
 Usage:
   npx @almyty/agents <command> [options]
 
 Commands:
-  list                          List all agents in your organization
-  get <name|id>                 Show details for one agent
-  run <name|id>                 Invoke a workflow agent or start an autonomous run
-  runs <name|id>                List recent runs for an agent
-  cancel <name|id> <runId>      Cancel a running autonomous run
+  list                          List the agents in your organization
+  get <name|id>                 One agent: mode, status, pipeline shape, tools
+  run <name|id>                 Invoke a workflow agent, or start an autonomous run
+  runs <name|id>                Recent autonomous runs, newest first
+  inspect <name|id> <runId>     One autonomous run in full: steps, models, cost, error
+  executions <name|id>          Recent workflow executions, newest first
+  trace <name|id> <execId>      Where a workflow execution's calls went, hop by hop
+  cancel <name|id> <runId>      Cancel an in-flight autonomous run
   help                          Show this help
 
 Run options:
   --input '<json>'              Input payload (workflow: object; autonomous: string or object)
-  --resume <conversation-id>    Resume a previous conversation
-  --max-steps <n>               Autonomous: max steps (default 50)
-  --max-cost-cents <n>          Autonomous: max cost in cents (default 100)
-  --max-duration-ms <ms>        Autonomous: max wall time in ms (default 3600000)
-  --watch                       Autonomous: stream steps as they arrive
-  --json                        Print raw JSON instead of pretty output
+  --resume <conversation-id>    Autonomous: continue a previous conversation
+  --max-steps <n>               Autonomous: step ceiling
+  --max-cost-cents <n>          Autonomous: cost ceiling, in cents
+  --max-duration-ms <ms>        Autonomous: wall-clock ceiling
+  --watch                       Autonomous: stream steps until the run ends
+  --timeout <s>                 Autonomous --watch: give up waiting after this long (default 300)
+
+List options (runs, executions):
+  --limit <n>                   Rows per page (default 20)
+  --page <n>                    Page number (default 1)
+
+Inspect options:
+  --steps                       run: also print per-node detail for a workflow run
+
+Global options:
+  --json                        Machine-readable output, no decoration
+  --help, -h                    Show this help
+  --version, -v                 Print the version
 
 Environment:
   ALMYTY_TOKEN                  Token override (skips ~/.almyty/credentials.json)
   ALMYTY_URL                    API URL override
+  NO_COLOR                      Honoured; these commands emit no ANSI colour anyway
+
+Exit codes:
+  0  success
+  1  unexpected error
+  2  usage error (bad flags, unknown command)
+  3  not authenticated — run \`npx @almyty/auth login\`
+  4  no such agent, run, or execution
+  5  the run finished in a non-success state
+
+Notes:
+  A workflow agent's history is under \`executions\` and \`trace\`; an
+  autonomous agent's is under \`runs\` and \`inspect\`. \`get\` tells you
+  which mode an agent is in.
 
 Login:
   npx @almyty/auth login        Browser-based login (writes ~/.almyty/credentials.json)
 `);
 }
-function parseArgs(argv) {
-    const result = { positional: [], flags: {} };
-    let i = 0;
-    while (i < argv.length) {
-        const arg = argv[i];
-        if (arg === '--help' || arg === '-h') {
-            result.flags.help = true;
-        }
-        else if (arg === '--version' || arg === '-v') {
-            result.flags.version = true;
-        }
-        else if (arg === '--watch') {
-            result.flags.watch = true;
-        }
-        else if (arg === '--json') {
-            result.flags.json = true;
-        }
-        else if (arg.startsWith('--')) {
-            const key = arg.slice(2);
-            const next = argv[i + 1];
-            if (next && !next.startsWith('--')) {
-                result.flags[key] = next;
-                i++;
-            }
-            else {
-                result.flags[key] = true;
-            }
-        }
-        else if (!result.command) {
-            result.command = arg;
-        }
-        else {
-            result.positional.push(arg);
+function emitJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+function fail(message, code) {
+    console.error(message);
+    process.exit(code);
+}
+/**
+ * The credential, or a clear instruction. Every command in every almyty
+ * CLI answers a missing credential the same way and with the same exit
+ * code, so a script can branch on 3 instead of matching stderr.
+ */
+function newClient(args) {
+    const creds = resolveCredentials();
+    if (!creds?.token) {
+        if (args?.flags.json) {
+            // A --json consumer gets a parseable answer on stdout too, not
+            // only an exit code and prose on stderr.
+            emitJson({
+                error: 'NOT_AUTHENTICATED',
+                message: 'Run `npx @almyty/auth login`, or set ALMYTY_TOKEN.',
+            });
         }
-        i++;
+        console.error('Not authenticated. Run one of:');
+        console.error('  npx @almyty/auth login');
+        console.error('  export ALMYTY_TOKEN=<your-token>');
+        process.exit(EXIT.AUTH);
     }
-    return result;
-}
-function newClient() {
-    const creds = resolveCredentialsOrExit();
     return new AlmytyClient(creds.url, creds.token);
 }
-function formatAgent(a, prefix = '') {
-    const mode = a.mode ? ` [${a.mode}]` : '';
-    const status = a.status ? ` (${a.status})` : '';
-    const desc = a.description ? `\n${prefix}    ${a.description}` : '';
-    return `${prefix}${a.name}${mode}${status}${desc}`;
+function requireArg(value, usage) {
+    if (!value)
+        fail(`Usage: npx @almyty/agents ${usage}`, EXIT.USAGE);
+    return value;
+}
+async function findAgentOrExit(client, ref) {
+    const agent = await client.findAgentByNameOrId(ref);
+    if (!agent) {
+        console.error(`Agent not found: ${ref}`);
+        console.error('Run `npx @almyty/agents list` to see what exists.');
+        process.exit(EXIT.NOT_FOUND);
+    }
+    return agent;
+}
+/** `?page=&limit=` from the shared list flags. */
+function pageQuery(args) {
+    return {
+        page: flagNumber(args.flags, 'page') ?? 1,
+        limit: flagNumber(args.flags, 'limit') ?? 20,
+    };
 }
 async function cmdList(args) {
-    const client = newClient();
+    const client = newClient(args);
     const agents = await client.listAgents();
     if (args.flags.json) {
-        console.log(JSON.stringify(agents, null, 2));
+        emitJson(agents);
         return;
     }
     if (agents.length === 0) {
         console.log('No agents found. Create one at https://app.almyty.com/agents');
         return;
     }
-    console.log(`\n${agents.length} agent(s):\n`);
-    for (const a of agents) {
-        console.log('  ' + formatAgent(a, '  ').trimStart());
+    console.log('');
+    console.log(`${agents.length} agent(s):`);
+    console.log('');
+    for (const agent of agents) {
+        console.log(formatAgentLine(agent));
         console.log('');
     }
 }
 async function cmdGet(args) {
-    const ref = args.positional[0];
-    if (!ref) {
-        console.error('Usage: npx @almyty/agents get <name|id>');
-        process.exit(1);
-    }
-    const client = newClient();
-    const agent = await client.findAgentByNameOrId(ref);
-    if (!agent) {
-        console.error(`Agent not found: ${ref}`);
-        process.exit(1);
-    }
+    const ref = requireArg(args.positional[0], 'get <name|id>');
+    const client = newClient(args);
+    const found = await findAgentOrExit(client, ref);
+    // The list endpoint drops tools and the pipeline; fetch the full row
+    // so `get` can answer what the agent is actually wired to.
+    const agent = await client.getAgent(found.id).catch(() => found);
     if (args.flags.json) {
-        console.log(JSON.stringify(agent, null, 2));
+        emitJson(agent);
         return;
     }
     console.log('');
-    console.log(`  ${agent.name}`);
-    console.log(`  id:     ${agent.id}`);
-    if (agent.mode)
-        console.log(`  mode:   ${agent.mode}`);
-    if (agent.status)
-        console.log(`  status: ${agent.status}`);
-    if (agent.description)
-        console.log(`  desc:   ${agent.description}`);
+    console.log(formatAgentDetail(agent));
     console.log('');
 }
 function parseInputFlag(value) {
-    if (value === undefined || value === true || value === false)
+    if (typeof value !== 'string')
         return undefined;
-    // Try JSON first; fall back to raw string.
+    // Try JSON first; fall back to the raw string (an autonomous agent's
+    // input is usually a plain sentence).
     try {
         return JSON.parse(value);
     }
@@ -148,147 +176,260 @@ function parseInputFlag(value) {
         return value;
     }
 }
-function formatStep(step) {
-    if (!step)
-        return null;
-    switch (step.type) {
-        case 'llm_call':
-            if (step.output?.content) {
-                return `  ${step.output.content}`;
-            }
-            return `  · llm_call (${step.tokens?.input ?? 0}↓ / ${step.tokens?.output ?? 0}↑)`;
-        case 'tool_call':
-            return `  · tool_call → ${step.input?.tool ?? '?'}`;
-        case 'sub_agent_call':
-            return `  · sub_agent_call → ${step.input?.agentId ?? '?'}`;
-        case 'error':
-            return `  ! error: ${step.error}`;
-        default:
-            return null;
-    }
-}
 async function cmdRun(args) {
-    const ref = args.positional[0];
-    if (!ref) {
-        console.error('Usage: npx @almyty/agents run <name|id> [--input <json>]');
-        process.exit(1);
-    }
-    const client = newClient();
-    const agent = await client.findAgentByNameOrId(ref);
-    if (!agent) {
-        console.error(`Agent not found: ${ref}`);
-        process.exit(1);
+    const ref = requireArg(args.positional[0], "run <name|id> [--input '<json>']");
+    const client = newClient(args);
+    const agent = await findAgentOrExit(client, ref);
+    // A DRAFT agent answers 400 with a JSON body. The status is already
+    // here, so say what to do about it instead of printing the body.
+    if (agent.status && agent.status.toLowerCase() !== 'active') {
+        if (args.flags.json) {
+            emitJson({
+                error: 'AGENT_NOT_ACTIVE',
+                agentId: agent.id,
+                agentName: agent.name,
+                status: agent.status,
+                message: 'Agent must be active to run',
+            });
+            process.exit(EXIT.FAILED);
+        }
+        fail(notActiveMessage(agent), EXIT.FAILED);
     }
     const rawInput = parseInputFlag(args.flags.input);
     if (agent.mode === 'autonomous') {
         const limits = {};
-        if (args.flags['max-steps'])
-            limits.maxSteps = Number(args.flags['max-steps']);
-        if (args.flags['max-cost-cents'])
-            limits.maxCostCents = Number(args.flags['max-cost-cents']);
-        if (args.flags['max-duration-ms'])
-            limits.maxDurationMs = Number(args.flags['max-duration-ms']);
-        if (typeof args.flags.resume === 'string')
-            limits.conversationId = args.flags.resume;
+        const maxSteps = flagNumber(args.flags, 'max-steps');
+        const maxCostCents = flagNumber(args.flags, 'max-cost-cents');
+        const maxDurationMs = flagNumber(args.flags, 'max-duration-ms');
+        if (maxSteps !== undefined)
+            limits.maxSteps = maxSteps;
+        if (maxCostCents !== undefined)
+            limits.maxCostCents = maxCostCents;
+        if (maxDurationMs !== undefined)
+            limits.maxDurationMs = maxDurationMs;
+        const resume = flagString(args.flags, 'resume');
+        if (resume)
+            limits.conversationId = resume;
         const runStub = await client.startRun(agent.id, rawInput ?? '', limits);
         if (!args.flags.watch) {
             if (args.flags.json) {
-                console.log(JSON.stringify(runStub, null, 2));
+                emitJson(runStub);
             }
             else {
                 console.log(`Started run ${runStub.id}`);
-                console.log(`Watch:  npx @almyty/agents runs ${ref}`);
-                console.log(`Cancel: npx @almyty/agents cancel ${ref} ${runStub.id}`);
+                console.log(`Watch:   npx @almyty/agents inspect ${ref} ${runStub.id}`);
+                console.log(`Cancel:  npx @almyty/agents cancel ${ref} ${runStub.id}`);
             }
             return;
         }
         let printed = 0;
+        const timeoutSeconds = flagNumber(args.flags, 'timeout') ?? 300;
         const final = await client.pollRun(agent.id, runStub.id, {
+            timeoutMs: timeoutSeconds * 1000,
             onStep: (run) => {
-                const newSteps = (run.steps ?? []).slice(printed);
-                for (const step of newSteps) {
-                    const line = formatStep(step);
+                if (args.flags.json)
+                    return;
+                const steps = (run.steps ?? []);
+                for (let i = printed; i < steps.length; i++) {
+                    const line = formatStep(steps[i], i);
                     if (line)
                         console.log(line);
                 }
-                printed = run.steps?.length ?? printed;
+                printed = steps.length;
             },
         });
+        // A failed run is a failed command.
+        //
+        // pollRun returns on ANY terminal status, and this printed
+        // "Run failed." and exited 0 -- so `almyty agents run deploy-check
+        // --watch && ./ship.sh` shipped on a failed check.
+        if (!runSucceeded(final.status))
+            process.exitCode = EXIT.FAILED;
         if (args.flags.json) {
-            console.log(JSON.stringify(final, null, 2));
+            emitJson(final);
             return;
         }
         console.log('');
-        console.log(`Run ${final.status}.`);
+        console.log(formatRunSummary(final));
         if (final.output != null) {
             console.log('');
-            console.log(typeof final.output === 'string' ? final.output : JSON.stringify(final.output, null, 2));
+            console.log(typeof final.output === 'string'
+                ? final.output
+                : JSON.stringify(final.output, null, 2));
         }
-        if (final.error)
+        if (final.error) {
+            console.error('');
             console.error(`Error: ${final.error}`);
+            console.error(`Detail: npx @almyty/agents inspect ${ref} ${final.id}`);
+        }
         return;
     }
     // workflow mode
     const result = await client.invokeAgent(agent.id, rawInput ?? {});
+    // Same rule: the endpoint answers 200 with status 'failed'.
+    if (result?.status && !runSucceeded(result.status))
+        process.exitCode = EXIT.FAILED;
     if (args.flags.json) {
-        console.log(JSON.stringify(result, null, 2));
+        emitJson(result);
         return;
     }
-    const output = result?.output ?? result;
-    if (output == null) {
+    const output = result?.output ?? null;
+    if (output == null)
         console.log('(no output)');
-    }
-    else if (typeof output === 'string') {
+    else if (typeof output === 'string')
         console.log(output);
-    }
-    else {
+    else
         console.log(JSON.stringify(output, null, 2));
+    // Attribution and cost, always — a routed workflow answers from
+    // whichever model the policy picked, and that has to be visible.
+    if (result?.status) {
+        console.log('');
+        console.log(formatExecutionSummary(result));
+    }
+    if (args.flags.steps || (result?.status && !runSucceeded(result.status))) {
+        const lines = formatNodeResults(result?.nodeResults);
+        if (lines.length) {
+            console.log('');
+            console.log('Nodes:');
+            for (const line of lines)
+                console.log(line);
+        }
+    }
+    if (result?.error) {
+        console.error('');
+        console.error(`Error: ${result.error}`);
+        if (result.id) {
+            console.error(`Detail: npx @almyty/agents trace ${ref} ${result.id}`);
+        }
     }
 }
 async function cmdRuns(args) {
-    const ref = args.positional[0];
-    if (!ref) {
-        console.error('Usage: npx @almyty/agents runs <name|id>');
-        process.exit(1);
+    const ref = requireArg(args.positional[0], 'runs <name|id>');
+    const client = newClient(args);
+    const agent = await findAgentOrExit(client, ref);
+    const { page, limit } = pageQuery(args);
+    const { data, total } = await client.listRuns(agent.id, page, limit);
+    if (args.flags.json) {
+        emitJson({ total, page, limit, data });
+        return;
     }
-    const client = newClient();
-    const agent = await client.findAgentByNameOrId(ref);
-    if (!agent) {
-        console.error(`Agent not found: ${ref}`);
-        process.exit(1);
+    if (data.length === 0) {
+        console.log(agent.mode === 'workflow'
+            ? `No autonomous runs — ${agent.name} is a workflow agent. Try: npx @almyty/agents executions ${ref}`
+            : 'No runs yet.');
+        return;
+    }
+    console.log('');
+    console.log(`${total} run(s), showing page ${page}:`);
+    console.log('');
+    for (const run of data) {
+        const bits = [run.id, (run.status ?? '?').padEnd(10)];
+        if (run.createdAt)
+            bits.push(run.createdAt);
+        console.log(`  ${bits.join('  ')}`);
+        console.log(`      ${formatRunSummary(run)}`);
+    }
+    console.log('');
+    console.log(`Detail: npx @almyty/agents inspect ${ref} <runId>`);
+}
+async function cmdInspect(args) {
+    const ref = requireArg(args.positional[0], 'inspect <name|id> <runId>');
+    const runId = requireArg(args.positional[1], 'inspect <name|id> <runId>');
+    const client = newClient(args);
+    const agent = await findAgentOrExit(client, ref);
+    let run;
+    try {
+        run = await client.getRun(agent.id, runId);
+    }
+    catch (err) {
+        fail(`Run not found on ${agent.name}: ${runId}\n${err.message}`, EXIT.NOT_FOUND);
     }
-    const { data, total } = await client.listRuns(agent.id);
     if (args.flags.json) {
-        console.log(JSON.stringify({ total, data }, null, 2));
+        emitJson(run);
+    }
+    else {
+        console.log('');
+        console.log(formatRunDetail(run));
+        console.log('');
+    }
+    if (!runSucceeded(run.status))
+        process.exitCode = EXIT.FAILED;
+}
+async function cmdExecutions(args) {
+    const ref = requireArg(args.positional[0], 'executions <name|id>');
+    const client = newClient(args);
+    const agent = await findAgentOrExit(client, ref);
+    const { page, limit } = pageQuery(args);
+    const body = await client.request(`/agents/${encodeURIComponent(agent.id)}/executions?page=${page}&limit=${limit}`);
+    const data = body?.data ?? [];
+    const total = body?.pagination?.total ?? data.length;
+    if (args.flags.json) {
+        emitJson({ total, page, limit, data });
         return;
     }
     if (data.length === 0) {
-        console.log('No runs yet.');
+        console.log(agent.mode === 'autonomous'
+            ? `No workflow executions — ${agent.name} is an autonomous agent. Try: npx @almyty/agents runs ${ref}`
+            : 'No executions yet.');
         return;
     }
-    console.log(`\n${total} run(s):\n`);
-    for (const run of data) {
-        console.log(`  ${run.id}  ${run.status}`);
+    console.log('');
+    console.log(`${total} execution(s), showing page ${page}:`);
+    console.log('');
+    for (const execution of data) {
+        const bits = [execution.id, (execution.status ?? '?').padEnd(10)];
+        if (execution.createdAt)
+            bits.push(execution.createdAt);
+        console.log(`  ${bits.join('  ')}`);
+        console.log(`      ${formatExecutionSummary(execution)}`);
     }
+    console.log('');
+    console.log(`Detail: npx @almyty/agents trace ${ref} <executionId>`);
 }
-async function cmdCancel(args) {
-    const ref = args.positional[0];
-    const runId = args.positional[1];
-    if (!ref || !runId) {
-        console.error('Usage: npx @almyty/agents cancel <name|id> <runId>');
-        process.exit(1);
+async function cmdTrace(args) {
+    const ref = requireArg(args.positional[0], 'trace <name|id> <executionId>');
+    const executionId = requireArg(args.positional[1], 'trace <name|id> <executionId>');
+    const client = newClient(args);
+    const agent = await findAgentOrExit(client, ref);
+    let body;
+    try {
+        body = await client.request(`/agents/${encodeURIComponent(agent.id)}/executions/${encodeURIComponent(executionId)}/trace`);
     }
-    const client = newClient();
-    const agent = await client.findAgentByNameOrId(ref);
-    if (!agent) {
-        console.error(`Agent not found: ${ref}`);
-        process.exit(1);
+    catch (err) {
+        fail(`No trace for execution ${executionId} on ${agent.name}.\n${err.message}`, EXIT.NOT_FOUND);
     }
+    const trace = body?.data ?? body;
+    if (args.flags.json) {
+        emitJson(trace);
+        return;
+    }
+    console.log('');
+    console.log(formatTrace(trace));
+    console.log('');
+}
+async function cmdCancel(args) {
+    const ref = requireArg(args.positional[0], 'cancel <name|id> <runId>');
+    const runId = requireArg(args.positional[1], 'cancel <name|id> <runId>');
+    const client = newClient(args);
+    const agent = await findAgentOrExit(client, ref);
     await client.cancelRun(agent.id, runId);
-    console.log(`Cancelled ${runId}`);
+    if (args.flags.json)
+        emitJson({ cancelled: true, agentId: agent.id, runId });
+    else
+        console.log(`Cancelled ${runId}`);
 }
+const COMMANDS = {
+    list: cmdList,
+    get: cmdGet,
+    run: cmdRun,
+    runs: cmdRuns,
+    inspect: cmdInspect,
+    executions: cmdExecutions,
+    trace: cmdTrace,
+    cancel: cmdCancel,
+};
 async function main() {
-    const args = parseArgs(process.argv.slice(2));
+    const args = parseArgs(process.argv.slice(2), BOOLEAN_FLAGS);
     if (args.flags.version) {
         console.log(VERSION);
         return;
@@ -297,29 +438,18 @@ async function main() {
         printHelp();
         return;
     }
-    switch (args.command) {
-        case 'list':
-            await cmdList(args);
-            return;
-        case 'get':
-            await cmdGet(args);
-            return;
-        case 'run':
-            await cmdRun(args);
-            return;
-        case 'runs':
-            await cmdRuns(args);
-            return;
-        case 'cancel':
-            await cmdCancel(args);
-            return;
-        default:
-            console.error(`Unknown command: ${args.command}`);
-            printHelp();
-            process.exit(1);
+    const handler = COMMANDS[args.command];
+    if (!handler) {
+        console.error(`Unknown command: ${args.command}`);
+        console.error(`Commands: ${Object.keys(COMMANDS).join(', ')}. Run --help for detail.`);
+        process.exit(EXIT.USAGE);
     }
+    await handler(args);
 }
 main().catch((err) => {
     console.error(`Error: ${err.message}`);
-    process.exit(1);
+    // An auth failure from anywhere in the client gets the auth code, so
+    // `|| almyty login` works whichever call discovered the dead token.
+    const authFailure = /Authentication failed|401/.test(err.message ?? '');
+    process.exit(authFailure ? EXIT.AUTH : EXIT.ERROR);
 });

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare function readVersion(fallback?: string): string;
+export declare const VERSION: string;