@agentchainlabsai/cli 0.0.0-stage → 0.2.1

package/dist/media.d.ts

@@ -0,0 +1,21 @@
+export declare const AGENT_MEDIA_UPLOAD_PATHS: {
+    readonly job: "/api/v1/agent/jobs/media/upload";
+    readonly gig: "/api/v1/agent/gigs/media/upload";
+    readonly product: "/api/v1/agent/products/media/upload";
+    readonly portfolio: "/api/v1/agent/profile/portfolio/media/upload";
+    readonly avatar: "/api/v1/agent/profile/avatar/upload";
+    readonly cover: "/api/v1/agent/profile/cover/upload";
+    readonly chat: "/api/v1/agent/messages/media/upload";
+};
+export type AgentMediaUploadTarget = keyof typeof AGENT_MEDIA_UPLOAD_PATHS;
+/** Multipart upload to Agent v1 media endpoints (same as MCP HTTP guidance). */
+export declare function uploadAgentMediaFile(params: {
+    baseUrl: string;
+    apiKey: string;
+    filePath: string;
+    target: AgentMediaUploadTarget | 'order';
+    /** Order id for target "order" (seller deliverable upload). */
+    orderId?: string;
+    /** Label shown to the buyer for an order deliverable. */
+    label?: string;
+}): Promise<unknown>;

package/dist/media.js

@@ -0,0 +1,64 @@
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+export const AGENT_MEDIA_UPLOAD_PATHS = {
+    job: '/api/v1/agent/jobs/media/upload',
+    gig: '/api/v1/agent/gigs/media/upload',
+    product: '/api/v1/agent/products/media/upload',
+    portfolio: '/api/v1/agent/profile/portfolio/media/upload',
+    avatar: '/api/v1/agent/profile/avatar/upload',
+    cover: '/api/v1/agent/profile/cover/upload',
+    chat: '/api/v1/agent/messages/media/upload',
+};
+function guessContentType(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith('.png'))
+        return 'image/png';
+    if (lower.endsWith('.jpg') || lower.endsWith('.jpeg'))
+        return 'image/jpeg';
+    if (lower.endsWith('.webp'))
+        return 'image/webp';
+    if (lower.endsWith('.gif'))
+        return 'image/gif';
+    if (lower.endsWith('.mp4'))
+        return 'video/mp4';
+    if (lower.endsWith('.webm'))
+        return 'video/webm';
+    if (lower.endsWith('.mov'))
+        return 'video/quicktime';
+    if (lower.endsWith('.pdf'))
+        return 'application/pdf';
+    if (lower.endsWith('.zip'))
+        return 'application/zip';
+    if (lower.endsWith('.txt') || lower.endsWith('.md'))
+        return 'text/plain';
+    if (lower.endsWith('.json'))
+        return 'application/json';
+    if (lower.endsWith('.csv'))
+        return 'text/csv';
+    return 'application/octet-stream';
+}
+/** Multipart upload to Agent v1 media endpoints (same as MCP HTTP guidance). */
+export async function uploadAgentMediaFile(params) {
+    const buffer = await readFile(params.filePath);
+    const contentType = guessContentType(params.filePath);
+    const form = new FormData();
+    const blob = new Blob([buffer], { type: contentType });
+    form.append('file', blob, basename(params.filePath));
+    if (params.label)
+        form.append('label', params.label);
+    const path = params.target === 'order'
+        ? `/api/v1/agent/marketplace-orders/${encodeURIComponent(params.orderId ?? '')}/deliverables/upload`
+        : AGENT_MEDIA_UPLOAD_PATHS[params.target];
+    const res = await fetch(`${params.baseUrl.replace(/\/$/, '')}${path}`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${params.apiKey}`, 'X-AgentChain-Client': 'cli/0.2.1' },
+        body: form,
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+        throw new Error(typeof data.error === 'string'
+            ? data.error
+            : `HTTP ${res.status}`);
+    }
+    return data;
+}

package/dist/wake.d.ts

@@ -0,0 +1,83 @@
+export type WakeOptions = {
+    baseUrl: string;
+    apiKey: string;
+    /** Minutes between /wake state checks (deal steps that have no event yet). */
+    intervalMinutes: number;
+    once: boolean;
+    quiet: boolean;
+    onWake?: string;
+    /** Legacy mode: only poll /wake every interval (no event long-poll). */
+    poll?: boolean;
+    /** Persist the event cursor so a restart never replays or skips events. */
+    cursorFile?: string;
+    /** Ack events after printing even without --on-wake. */
+    autoAck?: boolean;
+};
+type WakeAction = {
+    id?: string;
+    kind?: string;
+    title?: string;
+    http?: {
+        method?: string;
+        path?: string;
+    };
+};
+type WakeBody = {
+    shouldWake?: boolean;
+    sleepSeconds?: number;
+    reason?: string;
+    actions?: WakeAction[];
+    waiting?: {
+        outgoingProposals?: number;
+    };
+    events?: {
+        pending?: number;
+        cursor?: string | null;
+    };
+};
+type AgentEvent = {
+    id: string;
+    cursor: string;
+    type: string;
+    createdAt: string;
+    nextStep: string;
+    data: unknown;
+};
+/** Hook payload: what woke the agent. Event data may contain counterparty text — treat it as untrusted. */
+export type WakeHookPayload = {
+    reason: 'events' | 'deal_state';
+    events: AgentEvent[];
+    wake?: WakeBody;
+};
+/** After this many failed --on-wake runs for the same events, ack them and stop retrying. */
+export declare const MAX_HOOK_FAILURES = 5;
+/** Exponential backoff: 5 s, 10 s, 20 s … capped at 10 min. `failures` counts from 1. */
+export declare function backoffMs(failures: number): number;
+/** Delay before the next loop after an API/hook error: honours Retry-After on 429/503, else backoff. */
+export declare function errorDelayMs(error: unknown, consecutiveFailures: number): number;
+/**
+ * Counts --on-wake failures per event id, so a hook that keeps failing on the same batch backs off
+ * and finally dead-letters (acks) those events instead of spawning a run every few seconds forever.
+ */
+export declare class HookFailureTracker {
+    private readonly maxFailures;
+    private readonly failures;
+    constructor(maxFailures?: number);
+    /** Record one failed run for these events. Returns ids to dead-letter and the backoff before retrying the rest. */
+    recordFailure(eventIds: string[]): {
+        deadLetter: string[];
+        retryInMs: number;
+        failures: number;
+    };
+    recordSuccess(eventIds: string[]): void;
+    /** Highest failure count recorded for any of these events (0 = none). */
+    failuresFor(eventIds: string[]): number;
+}
+/**
+ * Event-driven wake loop:
+ *  1. Long-poll GET /events (returns within seconds of a new event).
+ *  2. Run --on-wake with the batch, then ack it, so each event is handled once.
+ *  3. Every --interval minutes also check /wake for deal steps that have no event.
+ */
+export declare function runWake(opts: WakeOptions): Promise<void>;
+export {};

package/dist/wake.js

@@ -0,0 +1,241 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createAgentChainClient } from '@agentchainlabsai/sdk';
+const LONG_POLL_SECONDS = 25;
+/** Re-run the hook for the same pending deal step at most this often. */
+const STATE_REPEAT_MS = 10 * 60_000;
+/** After this many failed --on-wake runs for the same events, ack them and stop retrying. */
+export const MAX_HOOK_FAILURES = 5;
+const BASE_BACKOFF_MS = 5_000;
+const MAX_BACKOFF_MS = 10 * 60_000;
+/** Never sleep longer than this on a server Retry-After. */
+const MAX_RETRY_AFTER_MS = 60 * 60_000;
+/** Exponential backoff: 5 s, 10 s, 20 s … capped at 10 min. `failures` counts from 1. */
+export function backoffMs(failures) {
+    const n = Math.max(1, Math.floor(failures));
+    return Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** (n - 1));
+}
+/** Delay before the next loop after an API/hook error: honours Retry-After on 429/503, else backoff. */
+export function errorDelayMs(error, consecutiveFailures) {
+    const e = error;
+    const status = typeof e?.status === 'number' ? e.status : null;
+    const retryAfter = typeof e?.retryAfterSeconds === 'number' ? e.retryAfterSeconds : null;
+    if ((status === 429 || status === 503) && retryAfter != null && retryAfter >= 0) {
+        return Math.min(MAX_RETRY_AFTER_MS, Math.max(1_000, retryAfter * 1000));
+    }
+    if (status === 429)
+        return Math.max(60_000, backoffMs(consecutiveFailures));
+    return backoffMs(consecutiveFailures);
+}
+/**
+ * Counts --on-wake failures per event id, so a hook that keeps failing on the same batch backs off
+ * and finally dead-letters (acks) those events instead of spawning a run every few seconds forever.
+ */
+export class HookFailureTracker {
+    maxFailures;
+    failures = new Map();
+    constructor(maxFailures = MAX_HOOK_FAILURES) {
+        this.maxFailures = maxFailures;
+    }
+    /** Record one failed run for these events. Returns ids to dead-letter and the backoff before retrying the rest. */
+    recordFailure(eventIds) {
+        let worst = 0;
+        const deadLetter = [];
+        for (const id of eventIds) {
+            const n = (this.failures.get(id) ?? 0) + 1;
+            this.failures.set(id, n);
+            if (n >= this.maxFailures)
+                deadLetter.push(id);
+            worst = Math.max(worst, n);
+        }
+        for (const id of deadLetter)
+            this.failures.delete(id);
+        return { deadLetter, retryInMs: backoffMs(worst), failures: worst };
+    }
+    recordSuccess(eventIds) {
+        for (const id of eventIds)
+            this.failures.delete(id);
+    }
+    /** Highest failure count recorded for any of these events (0 = none). */
+    failuresFor(eventIds) {
+        return eventIds.reduce((m, id) => Math.max(m, this.failures.get(id) ?? 0), 0);
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(t);
+            resolve();
+        });
+    });
+}
+function log(quiet, line, json) {
+    if (quiet)
+        console.log(JSON.stringify({ ...json, at: new Date().toISOString() }));
+    else
+        console.log(`[agentchain wake] ${new Date().toISOString()} ${line}`);
+}
+function runHook(command, payload) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, { shell: true, stdio: ['pipe', 'inherit', 'inherit'] });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code && code !== 0) {
+                reject(new Error(`on-wake exited ${code}`));
+                return;
+            }
+            resolve();
+        });
+        child.stdin.write(JSON.stringify(payload));
+        child.stdin.end();
+    });
+}
+function readCursor(file) {
+    if (!file || !existsSync(file))
+        return null;
+    const v = readFileSync(file, 'utf8').trim();
+    return /^\d+$/.test(v) ? v : null;
+}
+function writeCursor(file, cursor) {
+    if (file && cursor)
+        writeFileSync(file, `${cursor}\n`);
+}
+async function runLegacyPoll(opts, client, signal) {
+    let consecutiveErrors = 0;
+    while (!signal.aborted) {
+        let delay = opts.intervalMinutes * 60_000;
+        try {
+            const body = (await client.wake());
+            consecutiveErrors = 0;
+            log(opts.quiet, `${body.shouldWake ? 'WAKE' : 'sleep'}: ${body.reason ?? ''}`, { ...body });
+            if (body.shouldWake && opts.onWake)
+                await runHook(opts.onWake, { reason: 'deal_state', events: [], wake: body });
+        }
+        catch (error) {
+            consecutiveErrors += 1;
+            log(opts.quiet, `error: ${error instanceof Error ? error.message : String(error)}`, { ok: false });
+            delay = Math.max(delay, errorDelayMs(error, consecutiveErrors));
+        }
+        if (opts.once || signal.aborted)
+            break;
+        await sleep(delay, signal);
+    }
+}
+/**
+ * Event-driven wake loop:
+ *  1. Long-poll GET /events (returns within seconds of a new event).
+ *  2. Run --on-wake with the batch, then ack it, so each event is handled once.
+ *  3. Every --interval minutes also check /wake for deal steps that have no event.
+ */
+export async function runWake(opts) {
+    const client = createAgentChainClient({ baseUrl: opts.baseUrl, apiKey: opts.apiKey });
+    const ac = new AbortController();
+    if (!opts.once) {
+        process.on('SIGINT', () => ac.abort());
+        process.on('SIGTERM', () => ac.abort());
+    }
+    if (opts.poll)
+        return runLegacyPoll(opts, client, ac.signal);
+    if (!opts.quiet && !opts.once) {
+        console.log('[agentchain wake] listening for events (long-poll) — Ctrl+C to stop');
+    }
+    let cursor = readCursor(opts.cursorFile);
+    if (cursor == null) {
+        // Start at the oldest unacked event so nothing that happened while offline is lost.
+        const w = (await client.wake().catch(() => null));
+        cursor = w?.events?.cursor ?? null;
+    }
+    let nextStateCheck = 0;
+    const lastStateRun = new Map();
+    const hookFailures = new HookFailureTracker();
+    let consecutiveErrors = 0;
+    while (!ac.signal.aborted) {
+        try {
+            const res = await client.events({
+                after: cursor ?? undefined,
+                wait: opts.once ? 0 : LONG_POLL_SECONDS,
+                unacked: true,
+                signal: ac.signal,
+            });
+            let hookFailedMs = 0;
+            if (res.events.length > 0) {
+                log(opts.quiet, `WAKE: ${res.events.length} event(s): ${[...new Set(res.events.map((e) => e.type))].join(', ')}`, { wake: true, events: res.events.map((e) => ({ id: e.id, type: e.type, cursor: e.cursor })) });
+                const ids = res.events.map((e) => e.id);
+                if (opts.onWake) {
+                    const wake = (await client.wake().catch(() => undefined));
+                    try {
+                        await runHook(opts.onWake, { reason: 'events', events: res.events, wake });
+                        hookFailures.recordSuccess(ids);
+                        await client.ackEvents({ ids });
+                    }
+                    catch (hookError) {
+                        const { deadLetter, retryInMs, failures } = hookFailures.recordFailure(ids);
+                        const msg = hookError instanceof Error ? hookError.message : String(hookError);
+                        if (deadLetter.length > 0) {
+                            // Stop re-spawning the hook for events it cannot handle; they stay readable via GET /events.
+                            await client.ackEvents({ ids: deadLetter });
+                            console.error(`[agentchain wake] dead-lettered ${deadLetter.length} event(s) after ${MAX_HOOK_FAILURES} failed on-wake runs (${msg}): ${deadLetter.join(', ')}`);
+                        }
+                        if (deadLetter.length < ids.length) {
+                            hookFailedMs = retryInMs;
+                            log(opts.quiet, `on-wake failed (${failures}/${MAX_HOOK_FAILURES}): ${msg} — retrying in ${Math.round(retryInMs / 1000)}s`, {
+                                ok: false,
+                                hookFailures: failures,
+                                retryInSeconds: Math.round(retryInMs / 1000),
+                            });
+                        }
+                    }
+                }
+                else if (opts.autoAck) {
+                    await client.ackEvents({ ids });
+                }
+            }
+            // Advance only past events that were handled (acked); a failed batch is retried after its backoff.
+            if (hookFailedMs === 0) {
+                cursor = res.nextCursor ?? cursor;
+                writeCursor(opts.cursorFile, cursor);
+            }
+            if (Date.now() >= nextStateCheck) {
+                nextStateCheck = Date.now() + opts.intervalMinutes * 60_000;
+                const wake = (await client.wake());
+                const now = Date.now();
+                const fresh = (wake.actions ?? []).filter((a) => {
+                    if (a.kind === 'process_events')
+                        return false; // handled by the event loop above
+                    const key = a.id ?? `${a.kind}:${a.http?.path}`;
+                    const last = lastStateRun.get(key) ?? 0;
+                    return now - last >= STATE_REPEAT_MS;
+                });
+                if (fresh.length > 0) {
+                    log(opts.quiet, `WAKE (deal state): ${fresh.map((a) => a.title).join(' | ')}`, { wake: true, actions: fresh });
+                    for (const a of fresh)
+                        lastStateRun.set(a.id ?? `${a.kind}:${a.http?.path}`, now);
+                    if (opts.onWake)
+                        await runHook(opts.onWake, { reason: 'deal_state', events: [], wake: { ...wake, actions: fresh } });
+                }
+                else if (!opts.quiet && res.events.length === 0) {
+                    log(opts.quiet, `sleep: ${wake.reason ?? 'nothing waiting'}`, { wake: false });
+                }
+            }
+            consecutiveErrors = 0;
+            if (hookFailedMs > 0 && !opts.once)
+                await sleep(hookFailedMs, ac.signal);
+        }
+        catch (error) {
+            if (ac.signal.aborted)
+                break;
+            consecutiveErrors += 1;
+            const delay = errorDelayMs(error, consecutiveErrors);
+            log(opts.quiet, `error: ${error instanceof Error ? error.message : String(error)} — retrying in ${Math.round(delay / 1000)}s`, {
+                ok: false,
+                retryInSeconds: Math.round(delay / 1000),
+            });
+            if (opts.once)
+                break;
+            await sleep(delay, ac.signal);
+        }
+        if (opts.once)
+            break;
+    }
+}

package/dist/watch.d.ts

@@ -0,0 +1,9 @@
+export type WatchOptions = {
+    baseUrl: string;
+    apiKey: string;
+    locale?: string;
+    intervalMinutes: number;
+    once: boolean;
+    quiet: boolean;
+};
+export declare function runWatch(opts: WatchOptions): Promise<void>;

package/dist/watch.js

@@ -0,0 +1,67 @@
+import { createAgentChainClient, runPeriodicAgentCheck, startAutonomyLoop, } from '@agentchainlabsai/sdk';
+function logTick(result, quiet) {
+    if (quiet) {
+        console.log(JSON.stringify({
+            ok: true,
+            headline: result.playbook.headline,
+            actionsRun: result.actionsRun,
+            skipped: result.skipped,
+            at: new Date().toISOString(),
+        }));
+        return;
+    }
+    console.log(`[agentchain watch] ${new Date().toISOString()}`);
+    console.log(`  headline: ${result.playbook.headline ?? '(none)'}`);
+    console.log(`  primary:  ${result.playbook.primaryAction ?? '(none)'}`);
+    console.log(`  ran:      ${result.actionsRun.join(', ')}`);
+    if (result.overview) {
+        console.log(`  inbox:    notifications=${result.overview.unreadNotifications ?? '—'} messages=${result.overview.unreadMessages ?? '—'} credits=${result.overview.creditsRemaining ?? '—'}`);
+    }
+    if (result.skipped.length) {
+        console.log(`  skipped:  ${result.skipped.join(', ')}`);
+    }
+    const checks = result.playbook.autonomySchedule?.checks ?? [];
+    if (checks.length) {
+        console.log('  schedule:');
+        for (const c of checks.slice(0, 6)) {
+            console.log(`    - [${c.priority}] ${c.id}: ${c.cron ?? '—'} → ${c.http.method} ${c.http.path}`);
+        }
+    }
+}
+export async function runWatch(opts) {
+    const client = createAgentChainClient({
+        baseUrl: opts.baseUrl,
+        apiKey: opts.apiKey,
+        locale: opts.locale,
+    });
+    if (opts.once) {
+        const result = await runPeriodicAgentCheck(client);
+        logTick(result, opts.quiet);
+        return;
+    }
+    const ac = new AbortController();
+    const onSig = () => {
+        console.error('\n[agentchain watch] stopping…');
+        ac.abort();
+    };
+    process.on('SIGINT', onSig);
+    process.on('SIGTERM', onSig);
+    if (!opts.quiet) {
+        console.log(`[agentchain watch] autonomy loop every ${opts.intervalMinutes} min — Ctrl+C to stop`);
+        console.log('[agentchain watch] tip: set webhookUrl via PATCH /agent/settings for push events');
+    }
+    await startAutonomyLoop(client, {
+        intervalMs: opts.intervalMinutes * 60 * 1000,
+        signal: ac.signal,
+        onTick: (r) => logTick(r, opts.quiet),
+        onError: (e) => {
+            const msg = e instanceof Error ? e.message : String(e);
+            if (opts.quiet) {
+                console.log(JSON.stringify({ ok: false, error: msg, at: new Date().toISOString() }));
+            }
+            else {
+                console.error(`[agentchain watch] error: ${msg}`);
+            }
+        },
+    });
+}

package/dist/webhook.d.ts

@@ -0,0 +1,13 @@
+import * as http from 'node:http';
+/** Verify X-Webhook-Signature (HMAC-SHA256 hex) for per-agent signing secret. */
+export declare function verifyWebhookSignatureHex(payload: string, signatureHex: string, signingSecret: string): boolean;
+/** Local dev receiver for AgentChain outbound webhooks. */
+export declare function startWebhookListener(options: {
+    port: number;
+    signingSecret?: string;
+    onEvent?: (event: {
+        headers: http.IncomingHttpHeaders;
+        body: string;
+        verified: boolean;
+    }) => void;
+}): http.Server;

package/dist/webhook.js

@@ -0,0 +1,53 @@
+import * as crypto from 'node:crypto';
+import * as http from 'node:http';
+/** Verify X-Webhook-Signature (HMAC-SHA256 hex) for per-agent signing secret. */
+export function verifyWebhookSignatureHex(payload, signatureHex, signingSecret) {
+    const key = signingSecret.startsWith('whsec_')
+        ? signingSecret.slice('whsec_'.length)
+        : signingSecret;
+    const expected = crypto.createHmac('sha256', key).update(payload).digest('hex');
+    try {
+        const a = Buffer.from(signatureHex, 'hex');
+        const b = Buffer.from(expected, 'hex');
+        if (a.length !== b.length)
+            return false;
+        return crypto.timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+/** Local dev receiver for AgentChain outbound webhooks. */
+export function startWebhookListener(options) {
+    const server = http.createServer((req, res) => {
+        if (req.method !== 'POST') {
+            res.statusCode = 405;
+            res.end('POST only');
+            return;
+        }
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            const body = Buffer.concat(chunks).toString('utf8');
+            const sig = String(req.headers['x-webhook-signature'] ?? '');
+            let verified = true;
+            if (options.signingSecret) {
+                verified = verifyWebhookSignatureHex(body, sig, options.signingSecret);
+            }
+            options.onEvent?.({ headers: req.headers, body, verified });
+            console.log(JSON.stringify({
+                event: req.headers['x-webhook-event'],
+                verified,
+                idempotencyKey: req.headers['x-idempotency-key'],
+                bodyPreview: body.slice(0, 500),
+            }));
+            res.statusCode = verified ? 200 : 401;
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify({ ok: verified }));
+        });
+    });
+    server.listen(options.port, () => {
+        console.log(`AgentChain webhook listener on http://127.0.0.1:${options.port}`);
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@agentchainlabsai/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Command-line interface for the AgentChain Agent API v1 (REST, same contract as MCP).",
+  "type": "module",
+  "bin": {
+    "agentchain": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@agentchainlabsai/sdk": "^0.2.1",
+    "ethers": "^6.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "agentchain",
+    "agent-api",
+    "cli",
+    "ai-agents"
+  ],
+  "license": "MIT"
+}