@almyty/agents 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @almyty/agents
+
+List, run, and manage almyty agents from the command line.
+
+## Quick start
+
+```bash
+$ npx @almyty/auth login
+$ npx @almyty/agents list
+$ npx @almyty/agents run my-agent --input '{"text": "hello"}' --watch
+```
+
+## Commands
+
+| 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.
+
+## Run options
+
+| Flag | Description |
+|------|-------------|
+| `--input '<json>'` | Input payload (object for workflow, string or object for autonomous) |
+| `--watch` | Stream steps as they arrive |
+| `--json` | Print raw JSON output |
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `ALMYTY_TOKEN` | Auth token override |
+| `ALMYTY_URL` | API URL override |
+
+## Authentication
+
+Requires `npx @almyty/auth login` first. Reads credentials from `~/.almyty/credentials.json`.
+
+## Docs
+
+https://almyty.com/docs
+
+## License
+
+BSL-1.1

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Tiny HTTP client for the almyty REST API, scoped to the surface
+ * needed by @almyty/agents (list / get / invoke / runs).
+ */
+export interface AgentInfo {
+    id: string;
+    name: string;
+    description?: string;
+    mode?: 'workflow' | 'autonomous';
+    status?: string;
+}
+export interface AgentRun {
+    id: string;
+    status: string;
+    output?: any;
+    error?: string;
+    steps?: any[];
+    totalCost?: number;
+    totalTokens?: number;
+}
+export declare class AlmytyClient {
+    private readonly baseUrl;
+    private readonly token;
+    constructor(baseUrl: string, token: string);
+    private request;
+    listAgents(): Promise<AgentInfo[]>;
+    findAgentByNameOrId(nameOrId: string): Promise<AgentInfo | null>;
+    invokeAgent(agentId: string, input: Record<string, any>): Promise<any>;
+    startAgentRun(agentId: string, input: any, limits?: {
+        maxSteps?: number;
+        maxCostCents?: number;
+        maxDurationMs?: number;
+    }): Promise<AgentRun>;
+    getRun(agentId: string, runId: string): Promise<AgentRun>;
+    listRuns(agentId: string, page?: number, limit?: number): Promise<{
+        data: AgentRun[];
+        total: number;
+    }>;
+    sendRunInput(agentId: string, runId: string, input: string): Promise<void>;
+    cancelRun(agentId: string, runId: string): Promise<void>;
+    /**
+     * Poll a run until it reaches a terminal status (or waiting_input).
+     * Calls onStep whenever new steps appear so callers can stream output.
+     */
+    pollRun(agentId: string, runId: string, options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        onStep?: (run: AgentRun) => void;
+    }): Promise<AgentRun>;
+}

package/dist/client.js

@@ -0,0 +1,121 @@
+/**
+ * Tiny HTTP client for the almyty REST API, scoped to the surface
+ * needed by @almyty/agents (list / get / invoke / runs).
+ */
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled', 'timeout']);
+export class AlmytyClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.token = token;
+    }
+    async request(path, init = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            'Content-Type': 'application/json',
+            ...(init.headers || {}),
+        };
+        const res = await fetch(url, { ...init, headers });
+        if (!res.ok) {
+            if (res.status === 401) {
+                throw new Error('Authentication failed. Run: npx @almyty/auth login');
+            }
+            const text = await res.text().catch(() => '');
+            throw new Error(`API error ${res.status}: ${text}`);
+        }
+        if (res.status === 204)
+            return null;
+        return res.json();
+    }
+    async listAgents() {
+        const data = await this.request('/agents');
+        const agents = data?.data?.data || data?.data || data || [];
+        return agents.map((a) => ({
+            id: a.id,
+            name: a.name,
+            description: a.description,
+            mode: a.mode,
+            status: a.status,
+        }));
+    }
+    async findAgentByNameOrId(nameOrId) {
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        if (uuidRegex.test(nameOrId)) {
+            try {
+                const data = await this.request(`/agents/${nameOrId}`);
+                const a = data?.data ?? data;
+                if (a?.id) {
+                    return { id: a.id, name: a.name, description: a.description, mode: a.mode, status: a.status };
+                }
+            }
+            catch {
+                // fall through to name search
+            }
+        }
+        const all = await this.listAgents();
+        const lower = nameOrId.toLowerCase();
+        return (all.find((a) => a.name === nameOrId) ||
+            all.find((a) => a.name.toLowerCase() === lower) ||
+            all.find((a) => a.name.toLowerCase().replace(/\s+/g, '-') === lower) ||
+            null);
+    }
+    async invokeAgent(agentId, input) {
+        const data = await this.request(`/agents/${agentId}/invoke`, {
+            method: 'POST',
+            body: JSON.stringify({ input }),
+        });
+        return data?.data ?? data;
+    }
+    async startAgentRun(agentId, input, limits) {
+        const data = await this.request(`/agents/${agentId}/runs`, {
+            method: 'POST',
+            body: JSON.stringify({ input, ...(limits || {}) }),
+        });
+        const run = data?.data ?? data;
+        return { id: run.id, status: run.status };
+    }
+    async getRun(agentId, runId) {
+        const data = await this.request(`/agents/${agentId}/runs/${runId}`);
+        return (data?.data ?? data);
+    }
+    async listRuns(agentId, page = 1, limit = 20) {
+        const data = await this.request(`/agents/${agentId}/runs?page=${page}&limit=${limit}`);
+        return {
+            data: data?.data ?? [],
+            total: data?.pagination?.total ?? 0,
+        };
+    }
+    async sendRunInput(agentId, runId, input) {
+        await this.request(`/agents/${agentId}/runs/${runId}/input`, {
+            method: 'POST',
+            body: JSON.stringify({ input }),
+        });
+    }
+    async cancelRun(agentId, runId) {
+        await this.request(`/agents/${agentId}/runs/${runId}/cancel`, { method: 'POST' });
+    }
+    /**
+     * Poll a run until it reaches a terminal status (or waiting_input).
+     * Calls onStep whenever new steps appear so callers can stream output.
+     */
+    async pollRun(agentId, runId, options = {}) {
+        const intervalMs = options.intervalMs ?? 1500;
+        const timeoutMs = options.timeoutMs ?? 5 * 60_000;
+        const deadline = Date.now() + timeoutMs;
+        let lastStepCount = -1;
+        while (Date.now() < deadline) {
+            const run = await this.getRun(agentId, runId);
+            if (Array.isArray(run.steps) && run.steps.length !== lastStepCount) {
+                lastStepCount = run.steps.length;
+                options.onStep?.(run);
+            }
+            if (run.status && (TERMINAL_STATUSES.has(run.status) || run.status === 'waiting_input')) {
+                return run;
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+        throw new Error(`Run ${runId} did not finish within ${Math.round(timeoutMs / 1000)}s`);
+    }
+}

package/dist/credentials.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Read shared almyty credentials from ~/.almyty/credentials.json.
+ *
+ * Identical to packages/auth-cli/src/credentials.ts (intentional copy
+ * to keep each CLI package self-contained — these few helpers don't
+ * justify a workspace dependency).
+ */
+export declare const CREDENTIALS_FILE: string;
+export interface StoredCredentials {
+    url: string;
+    token: string;
+    email?: string;
+    frontendUrl?: string;
+}
+export declare function loadCredentials(): StoredCredentials | null;
+export declare function resolveCredentialsOrExit(): StoredCredentials;

package/dist/credentials.js

@@ -0,0 +1,34 @@
+/**
+ * Read shared almyty credentials from ~/.almyty/credentials.json.
+ *
+ * Identical to packages/auth-cli/src/credentials.ts (intentional copy
+ * to keep each CLI package self-contained — these few helpers don't
+ * justify a workspace dependency).
+ */
+import { readFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+export const CREDENTIALS_FILE = join(homedir(), '.almyty', 'credentials.json');
+export function loadCredentials() {
+    try {
+        if (!existsSync(CREDENTIALS_FILE))
+            return null;
+        return JSON.parse(readFileSync(CREDENTIALS_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveCredentialsOrExit() {
+    const envToken = process.env.ALMYTY_TOKEN;
+    const envUrl = process.env.ALMYTY_URL || 'https://api.almyty.com';
+    if (envToken)
+        return { url: envUrl, token: envToken };
+    const stored = loadCredentials();
+    if (stored?.token)
+        return stored;
+    console.error('Not authenticated. Run one of:');
+    console.error('  npx @almyty/auth login');
+    console.error('  export ALMYTY_TOKEN=<your-token>');
+    process.exit(1);
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * @almyty/agents — list, get, run, and inspect almyty agents.
+ *
+ *   npx @almyty/agents list
+ *   npx @almyty/agents get <name|id>
+ *   npx @almyty/agents run <name|id> [--input '<json>']
+ *   npx @almyty/agents runs <name|id>
+ *   npx @almyty/agents cancel <name|id> <runId>
+ *
+ * Reads credentials from ~/.almyty/credentials.json (created by
+ * `npx @almyty/auth login`).
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+/**
+ * @almyty/agents — list, get, run, and inspect almyty agents.
+ *
+ *   npx @almyty/agents list
+ *   npx @almyty/agents get <name|id>
+ *   npx @almyty/agents run <name|id> [--input '<json>']
+ *   npx @almyty/agents runs <name|id>
+ *   npx @almyty/agents cancel <name|id> <runId>
+ *
+ * Reads credentials from ~/.almyty/credentials.json (created by
+ * `npx @almyty/auth login`).
+ */
+import { AlmytyClient } from './client.js';
+import { resolveCredentialsOrExit } from './credentials.js';
+const VERSION = '0.1.0';
+function printHelp() {
+    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
+  help                          Show this help
+
+Run options:
+  --input '<json>'              Input payload (workflow: object; autonomous: string or object)
+  --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
+
+Environment:
+  ALMYTY_TOKEN                  Token override (skips ~/.almyty/credentials.json)
+  ALMYTY_URL                    API URL override
+
+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);
+        }
+        i++;
+    }
+    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}`;
+}
+async function cmdList(args) {
+    const client = newClient();
+    const agents = await client.listAgents();
+    if (args.flags.json) {
+        console.log(JSON.stringify(agents, null, 2));
+        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('');
+    }
+}
+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);
+    }
+    if (args.flags.json) {
+        console.log(JSON.stringify(agent, null, 2));
+        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('');
+}
+function parseInputFlag(value) {
+    if (value === undefined || value === true || value === false)
+        return undefined;
+    // Try JSON first; fall back to raw string.
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        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 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']);
+        const runStub = await client.startAgentRun(agent.id, rawInput ?? '', limits);
+        if (!args.flags.watch) {
+            if (args.flags.json) {
+                console.log(JSON.stringify(runStub, null, 2));
+            }
+            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}`);
+            }
+            return;
+        }
+        let printed = 0;
+        const final = await client.pollRun(agent.id, runStub.id, {
+            onStep: (run) => {
+                const newSteps = (run.steps ?? []).slice(printed);
+                for (const step of newSteps) {
+                    const line = formatStep(step);
+                    if (line)
+                        console.log(line);
+                }
+                printed = run.steps?.length ?? printed;
+            },
+        });
+        if (args.flags.json) {
+            console.log(JSON.stringify(final, null, 2));
+            return;
+        }
+        console.log('');
+        console.log(`Run ${final.status}.`);
+        if (final.output != null) {
+            console.log('');
+            console.log(typeof final.output === 'string' ? final.output : JSON.stringify(final.output, null, 2));
+        }
+        if (final.error)
+            console.error(`Error: ${final.error}`);
+        return;
+    }
+    // workflow mode
+    const result = await client.invokeAgent(agent.id, rawInput ?? {});
+    if (args.flags.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const output = result?.output ?? result;
+    if (output == null) {
+        console.log('(no output)');
+    }
+    else if (typeof output === 'string') {
+        console.log(output);
+    }
+    else {
+        console.log(JSON.stringify(output, null, 2));
+    }
+}
+async function cmdRuns(args) {
+    const ref = args.positional[0];
+    if (!ref) {
+        console.error('Usage: npx @almyty/agents runs <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 { data, total } = await client.listRuns(agent.id);
+    if (args.flags.json) {
+        console.log(JSON.stringify({ total, data }, null, 2));
+        return;
+    }
+    if (data.length === 0) {
+        console.log('No runs yet.');
+        return;
+    }
+    console.log(`\n${total} run(s):\n`);
+    for (const run of data) {
+        console.log(`  ${run.id}  ${run.status}`);
+    }
+}
+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);
+    }
+    const client = newClient();
+    const agent = await client.findAgentByNameOrId(ref);
+    if (!agent) {
+        console.error(`Agent not found: ${ref}`);
+        process.exit(1);
+    }
+    await client.cancelRun(agent.id, runId);
+    console.log(`Cancelled ${runId}`);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.flags.version) {
+        console.log(VERSION);
+        return;
+    }
+    if (args.flags.help || !args.command || args.command === 'help') {
+        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);
+    }
+}
+main().catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@almyty/agents",
+  "version": "0.1.0",
+  "description": "List, run, and manage almyty agents from the command line",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "almyty-agents": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "almyty",
+    "agents",
+    "cli"
+  ],
+  "author": "almyty",
+  "license": "BSL-1.1",
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.0"
+  }
+}