@almyty/agents 1.2.0 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @almyty/agents
 
-List, run, and manage almyty agents from the command line.
+Run, inspect and debug almyty agents from the command line.
 
 ## Quick start
 
@@ -14,25 +14,99 @@ $ npx @almyty/agents run my-agent --input '{"text": "hello"}' --watch
 
 | Command | Description |
 |---------|-------------|
-| `list [--json]` | List all agents in your organization |
-| `get <name\|id>` | Show details for one agent |
-| `run <name\|id> [options]` | Invoke a workflow or start an autonomous run |
-| `runs <name\|id>` | List recent runs for an agent |
-| `cancel <name\|id> <runId>` | Cancel an in-flight run |
-
-`<name|id>` accepts an agent name (case-insensitive) or UUID.
+| `list` | Every agent in your organization, with mode and status |
+| `get <name\|id>` | One agent: mode, status, model config, 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 |
+
+`<name|id>` accepts an agent name (case-insensitive, spaces or dashes),
+a slug, or a UUID.
+
+A **workflow** agent's history lives under `executions` and `trace`; an
+**autonomous** agent's lives under `runs` and `inspect`. `get` tells you
+which mode an agent is in, and `runs`/`executions` point you at the
+other one when you ask the wrong pair.
 
 ## Run options
 
 | Flag | Description |
 |------|-------------|
-| `--input '<json>'` | Input payload (object for workflow, string or object for autonomous) |
-| `--resume <conversation-id>` | Resume a previous autonomous conversation |
-| `--watch` | Stream steps as they arrive |
-| `--json` | Print raw JSON output |
-| `--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) |
+| `--input '<json>'` | Input payload. Parsed as JSON; a plain string is passed through as-is, which is what an autonomous agent usually wants. |
+| `--resume <conversation-id>` | Autonomous: continue a previous conversation |
+| `--watch` | Autonomous: stream steps until the run reaches a terminal state |
+| `--timeout <s>` | Autonomous `--watch`: stop waiting after this long (default `300`) |
+| `--max-steps <n>` | Autonomous: step ceiling |
+| `--max-cost-cents <n>` | Autonomous: cost ceiling, in cents |
+| `--max-duration-ms <ms>` | Autonomous: wall-clock ceiling |
+| `--steps` | Workflow: print per-node detail even when the run succeeded |
+| `--json` | Print the run object and nothing else |
+
+`run` refuses a non-active agent before calling the API and tells you to
+activate it, rather than printing the 400 body.
+
+## List options
+
+| Flag | Applies to | Description |
+|------|-----------|-------------|
+| `--limit <n>` | `runs`, `executions` | Rows per page (default `20`) |
+| `--page <n>` | `runs`, `executions` | Page number (default `1`) |
+
+## Global options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Machine-readable output on every command |
+| `--help`, `-h` | Show help |
+| `--version`, `-v` | Print the version |
+
+Both `--flag value` and `--flag=value` are accepted, and everything
+after a bare `--` is treated as a positional argument.
+
+## What you can see about a run
+
+A routed call stamps attribution on whatever recorded it — the step for
+an autonomous run, the node result for a workflow one. The CLI surfaces
+it, so a multi-model agent can be read from a terminal:
+
+```
+$ npx @almyty/agents run research-bot --input "who acquired Figma" --watch
+  1. Searching for recent coverage…  [claude-sonnet-4-5 · $0.0021 · 900 in / 12 out · 1.8s]
+  2. llm_call → tools: web_search  [claude-sonnet-4-5 · $0.0009 · 1.2s]
+  3. Adobe's offer was abandoned in December 2023.  [gpt-5-mini · attempt 2 · primary rate limited · $0.0004]
+
+Run completed · answered by claude-sonnet-4-5, gpt-5-mini · $0.0034 · 5,120 tokens · 4.2s
+```
+
+A call with a pinned provider leaves no attribution, and the CLI prints
+none rather than inventing a model name.
+
+`trace` goes further, printing the hops the backend recorded: what the
+routing policy chose, what it passed over, what the provider served, and
+what each hop cost. A hop whose cost is not ours to know prints as
+`cost opaque`, never as `$0`.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | success |
+| `1` | unexpected error |
+| `2` | usage error (bad flags, unknown command, missing argument) |
+| `3` | not authenticated — run `npx @almyty/auth login` |
+| `4` | no such agent, run, or execution |
+| `5` | the run finished in a non-success state |
+
+`5` is the one that matters in CI. The invoke endpoint answers `200`
+with `status: "failed"`, and `--watch` returns on any terminal status,
+so a failed run has to be turned into a non-zero exit deliberately:
+
+```bash
+npx @almyty/agents run deploy-check --watch && ./ship.sh
+```
 
 ## Environment variables
 
@@ -40,10 +114,13 @@ $ npx @almyty/agents run my-agent --input '{"text": "hello"}' --watch
 |----------|-------------|
 | `ALMYTY_TOKEN` | Auth token override |
 | `ALMYTY_URL` | API URL override |
+| `NO_COLOR` | Honoured; this CLI emits no ANSI colour anyway |
 
 ## Authentication
 
-Requires `npx @almyty/auth login` first. Reads credentials from `~/.almyty/credentials.json`.
+Run `npx @almyty/auth login` once. Credentials come from
+`~/.almyty/credentials.json`, or from `ALMYTY_TOKEN`. With neither, every
+command prints the login instruction and exits `3`.
 
 ## About almyty
 
@@ -51,8 +128,10 @@ almyty is the full-stack platform for AI agents, agnostic by design: any LLM, an
 API turned into tools, served over MCP, A2A, UTCP, and Agent Skills. Open source,
 no lock-in.
 
-- Website — https://almyty.com
-- Docs — https://docs.almyty.com
-- Source — https://github.com/almyty-inc/almyty
+- Website: https://almyty.com
+- Docs: https://docs.almyty.com
+- Source: https://github.com/almyty-inc/almyty
+
+This CLI is part of the `@almyty/*` suite (versioned together at 1.x) and works with the almyty platform 0.1 and later.
 
 Apache-2.0 © Almyty Inc.

package/dist/args.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Argument parsing shared in shape (not in code) by every almyty CLI.
+ *
+ * Conventions, so `almyty agents …` and `almyty auth …` never disagree:
+ *   - long flags only for options: `--input`, `--json`, `--max-steps`
+ *   - `--flag value` and `--flag=value` are both accepted. Only the
+ *     space form used to work, so `--input='{"a":1}'` silently became a
+ *     flag literally named `input={"a":1}` and the input was dropped.
+ *   - `-h` / `--help` and `-v` / `--version` are the only short flags
+ *   - a flag declared boolean never swallows the next token
+ *   - the first bare word is the command; the rest are positional
+ */
+export interface ParsedArgs {
+    command?: string;
+    positional: string[];
+    flags: Record<string, string | boolean>;
+}
+/** Flags every almyty CLI understands, and which never take a value. */
+export declare const COMMON_BOOLEAN_FLAGS: readonly ["help", "version", "json"];
+export declare function parseArgs(argv: string[], booleanFlags?: readonly string[]): ParsedArgs;
+/** A flag's value as a string, or undefined when it was absent or bare. */
+export declare function flagString(flags: ParsedArgs['flags'], name: string): string | undefined;
+/**
+ * A flag's value as a finite number. Throws a usage message rather than
+ * letting `NaN` reach the API, which answered a 400 with a validation
+ * body the user had to decode.
+ */
+export declare function flagNumber(flags: ParsedArgs['flags'], name: string): number | undefined;

package/dist/args.js

@@ -0,0 +1,80 @@
+/**
+ * Argument parsing shared in shape (not in code) by every almyty CLI.
+ *
+ * Conventions, so `almyty agents …` and `almyty auth …` never disagree:
+ *   - long flags only for options: `--input`, `--json`, `--max-steps`
+ *   - `--flag value` and `--flag=value` are both accepted. Only the
+ *     space form used to work, so `--input='{"a":1}'` silently became a
+ *     flag literally named `input={"a":1}` and the input was dropped.
+ *   - `-h` / `--help` and `-v` / `--version` are the only short flags
+ *   - a flag declared boolean never swallows the next token
+ *   - the first bare word is the command; the rest are positional
+ */
+/** Flags every almyty CLI understands, and which never take a value. */
+export const COMMON_BOOLEAN_FLAGS = ['help', 'version', 'json'];
+export function parseArgs(argv, booleanFlags = COMMON_BOOLEAN_FLAGS) {
+    const booleans = new Set([...COMMON_BOOLEAN_FLAGS, ...booleanFlags]);
+    const result = { positional: [], flags: {} };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h') {
+            result.flags.help = true;
+            continue;
+        }
+        if (arg === '-v') {
+            result.flags.version = true;
+            continue;
+        }
+        if (arg === '--') {
+            // Everything after `--` is positional, flags included.
+            result.positional.push(...argv.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith('--')) {
+            const body = arg.slice(2);
+            const eq = body.indexOf('=');
+            if (eq !== -1) {
+                result.flags[body.slice(0, eq)] = body.slice(eq + 1);
+                continue;
+            }
+            if (booleans.has(body)) {
+                result.flags[body] = true;
+                continue;
+            }
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                result.flags[body] = next;
+                i++;
+            }
+            else {
+                result.flags[body] = true;
+            }
+            continue;
+        }
+        if (!result.command)
+            result.command = arg;
+        else
+            result.positional.push(arg);
+    }
+    return result;
+}
+/** A flag's value as a string, or undefined when it was absent or bare. */
+export function flagString(flags, name) {
+    const value = flags[name];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * A flag's value as a finite number. Throws a usage message rather than
+ * letting `NaN` reach the API, which answered a 400 with a validation
+ * body the user had to decode.
+ */
+export function flagNumber(flags, name) {
+    const raw = flagString(flags, name);
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new Error(`--${name} needs a number, got ${JSON.stringify(raw)}`);
+    }
+    return value;
+}

package/dist/exit-codes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Exit codes shared by every almyty CLI.
+ *
+ * Scripts need to tell "you are not logged in" apart from "that agent
+ * does not exist" apart from "the run you asked for failed" without
+ * grepping stderr. Every almyty CLI uses this same table, so
+ * `almyty agents run x || case $? in 3) almyty login;; esac` behaves
+ * the same whichever binary produced the code.
+ */
+export declare const EXIT: {
+    /** Success. */
+    readonly OK: 0;
+    /** Unexpected failure (a thrown error with no better classification). */
+    readonly ERROR: 1;
+    /** Bad or missing arguments, or an unknown command. */
+    readonly USAGE: 2;
+    /** No stored credential, or the API rejected the one we had. */
+    readonly AUTH: 3;
+    /** The named agent / gateway / skill / run does not exist. */
+    readonly NOT_FOUND: 4;
+    /** The command ran; the operation it asked for failed. */
+    readonly FAILED: 5;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** One line per code, for `--help` output and READMEs. */
+export declare const EXIT_CODE_HELP: string;

package/dist/exit-codes.js

@@ -0,0 +1,32 @@
+/**
+ * Exit codes shared by every almyty CLI.
+ *
+ * Scripts need to tell "you are not logged in" apart from "that agent
+ * does not exist" apart from "the run you asked for failed" without
+ * grepping stderr. Every almyty CLI uses this same table, so
+ * `almyty agents run x || case $? in 3) almyty login;; esac` behaves
+ * the same whichever binary produced the code.
+ */
+export const EXIT = {
+    /** Success. */
+    OK: 0,
+    /** Unexpected failure (a thrown error with no better classification). */
+    ERROR: 1,
+    /** Bad or missing arguments, or an unknown command. */
+    USAGE: 2,
+    /** No stored credential, or the API rejected the one we had. */
+    AUTH: 3,
+    /** The named agent / gateway / skill / run does not exist. */
+    NOT_FOUND: 4,
+    /** The command ran; the operation it asked for failed. */
+    FAILED: 5,
+};
+/** One line per code, for `--help` output and READMEs. */
+export const EXIT_CODE_HELP = [
+    '  0  success',
+    '  1  unexpected error',
+    '  2  usage error (bad flags, unknown command)',
+    '  3  not authenticated — run `almyty login`',
+    '  4  not found (agent, gateway, skill, or run)',
+    '  5  the operation ran and failed',
+].join('\n');

package/dist/format.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Rendering for @almyty/agents.
+ *
+ * Pure functions, no I/O, so the shape of what a user sees is testable
+ * without a backend. The interesting part is attribution: a routed call
+ * stamps `routing` on the step / node result, and the CLI used to throw
+ * all of it away — so `agents run` could not answer "which model
+ * answered this, and what did it cost", which is the first question
+ * anyone asks about a multi-model agent.
+ */
+export interface RoutingAttribution {
+    modelId?: string;
+    modelVersionId?: string | null;
+    vendorModelId?: string;
+    providerId?: string | null;
+    rationale?: string;
+    attempt?: number;
+    tried?: Array<{
+        modelId: string;
+        reason: string;
+    }>;
+    rejected?: Array<{
+        modelId: string;
+        reason: string;
+    }>;
+}
+export interface RunStep {
+    type?: string;
+    input?: any;
+    output?: any;
+    cost?: number;
+    tokens?: {
+        input?: number;
+        output?: number;
+    };
+    duration?: number;
+    timestamp?: string;
+    error?: string;
+}
+export interface AgentSummary {
+    id: string;
+    name: string;
+    slug?: string;
+    description?: string;
+    mode?: string;
+    status?: string;
+    pipeline?: {
+        nodes?: Array<{
+            id: string;
+            type: string;
+            label?: string;
+        }>;
+    };
+    modelConfig?: Record<string, unknown>;
+    tools?: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/** Terminal statuses that mean the run did what was asked. */
+export declare const RUN_SUCCEEDED: Set<string>;
+/** A status that will never change on its own. */
+export declare const RUN_TERMINAL: Set<string>;
+export declare function runSucceeded(status: string | undefined): boolean;
+/** `$0.0042`, or `—` when nothing was recorded. A zero cost prints as $0. */
+export declare function formatCost(cost: unknown): string;
+export declare function formatTokens(tokens: unknown): string;
+export declare function formatDuration(ms: unknown): string;
+/** Whichever name a routed call gives for the model that answered. */
+export declare function modelOf(routing: RoutingAttribution | undefined): string | null;
+/**
+ * One line naming the model that answered and why it was picked.
+ * `null` when the call was not routed (a pinned provider leaves no
+ * attribution, and inventing one would be worse than saying nothing).
+ */
+export declare function formatRouting(routing: RoutingAttribution | undefined): string | null;
+/** The routing attribution a step carries, wherever it was stamped. */
+export declare function routingOfStep(step: RunStep | undefined): RoutingAttribution | undefined;
+/**
+ * One line per step, as `run --watch` streams them.
+ * Returns null for a step with nothing worth showing.
+ */
+export declare function formatStep(step: RunStep | undefined, index?: number): string | null;
+/**
+ * The closing line of a run: status, what it cost, and which models
+ * answered. Someone reading a CI log should not have to open the UI to
+ * learn any of the three.
+ */
+export declare function formatRunSummary(run: {
+    status?: string;
+    totalCost?: number;
+    totalTokens?: number;
+    executionTime?: number;
+    steps?: RunStep[];
+}): string;
+/**
+ * The same closing line for a workflow execution, whose attribution
+ * lives per node rather than per step.
+ */
+export declare function formatExecutionSummary(execution: {
+    status?: string;
+    totalCost?: number;
+    totalTokens?: number;
+    executionTime?: number;
+    nodeResults?: Record<string, any>;
+}): string;
+/**
+ * Per-node detail for a workflow run: which node failed, what was tried,
+ * and what answered. This is what you would otherwise open the UI for.
+ */
+export declare function formatNodeResults(nodeResults: Record<string, any> | undefined): string[];
+/** The full detail of one autonomous run, for `agents inspect`. */
+export declare function formatRunDetail(run: {
+    id?: string;
+    agentId?: string;
+    status?: string;
+    mode?: string;
+    conversationId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    currentStep?: number;
+    maxSteps?: number;
+    totalCost?: number;
+    totalTokens?: number;
+    executionTime?: number;
+    error?: string;
+    output?: unknown;
+    steps?: RunStep[];
+    limits?: Record<string, unknown>;
+}): string;
+/**
+ * The hop-by-hop trace the backend assembles at
+ * /agents/:id/executions/:executionId/trace. An opaque hop is printed
+ * as opaque, never as zero — the backend is deliberate about that and
+ * flattening it here would undo the point.
+ */
+export declare function formatTrace(trace: {
+    executionId?: string;
+    strategyKey?: string;
+    strategyChosenBy?: string;
+    strategyFallbackReason?: string;
+    steps?: Array<{
+        nodeId: string;
+        type?: string;
+        durationMs?: number;
+        error?: string;
+        hops?: Array<{
+            layer?: string;
+            decidedBy?: string;
+            chosen?: string;
+            reason?: string;
+            alternatives?: string[];
+            latencyMs?: number;
+            costEstimateCents?: number | null;
+            opaqueCost?: boolean;
+            requestedModel?: string;
+            servedModel?: string;
+            divergent?: boolean;
+            capabilitiesDropped?: string[];
+        }>;
+    }>;
+    summary?: {
+        knownCostCents?: number;
+        opaqueHops?: number;
+        divergences?: unknown[];
+        capabilitiesDropped?: string[];
+    };
+}): string;
+/** One agent per block, for `agents list`. */
+export declare function formatAgentLine(agent: AgentSummary): string;
+/** Everything `agents get` knows, so the next question is not "and then?". */
+export declare function formatAgentDetail(agent: AgentSummary): string;
+/**
+ * The message for trying to run a non-active agent.
+ *
+ * The API answers 400 with a JSON body, and the CLI printed the body:
+ * `API error 400: {"success":false,"message":"Agent must be active to
+ * invoke","error":"AGENT_NOT_ACTIVE"}`. The agent's status is already
+ * in hand before the call, so say it plainly and skip the round trip.
+ */
+export declare function notActiveMessage(agent: {
+    name: string;
+    id: string;
+    status?: string;
+}): string;