@argentic-ai/client 0.0.0-stage → 0.1.14

package/dist/argentic.js

@@ -0,0 +1,564 @@
+// Argentic core: a small client and a durable tool loop. No dependencies, Node 22+.
+// Argentic runs the agent loop; your code carries out the tool calls it asks for.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const defaultBaseUrl = 'https://api.getargentic.com';
+/** A wake can run a long time, so a try waits five minutes, as Python's client does. */
+export const defaultTimeoutMs = 300_000;
+/** The free default model. */
+export const freeModel = {
+    provider: 'nvidia',
+    id: 'nvidia/nemotron-3.5-lightning-30b-a3b',
+    prices: { in: 0, out: 0 },
+};
+const propKeys = ['type', 'description', 'enum'];
+/** True when any top-level property is an object, or an array of objects (or of anything that is not a plain scalar). */
+function isNested(schema) {
+    const flat = ['string', 'number', 'integer', 'boolean'];
+    return Object.values(schema?.properties ?? {}).some((p) => {
+        if (p?.type === 'object' || p?.properties)
+            return true;
+        return p?.type === 'array' && p.items && !flat.includes(p.items.type);
+    });
+}
+/**
+ * Trim a JSON schema to the subset Argentic accepts: an object of string, number,
+ * integer, boolean or array-of-those properties, with description, enum and required.
+ * Framework extras ($schema, additionalProperties, title, defaults) are dropped.
+ */
+export function toArgenticSchema(schema) {
+    // A nested argument (an object, or an array of objects) cannot be trimmed to the flat subset without losing what is inside it. The API reads such a schema as a
+    // JSON Schema for the arguments, so it goes through as it is, less the framework's `$schema` marker.
+    if (isNested(schema)) {
+        const { $schema: _, ...rest } = schema;
+        return rest;
+    }
+    const properties = {};
+    for (const [name, prop] of Object.entries(schema?.properties ?? {})) {
+        const out = {};
+        for (const k of propKeys)
+            if (prop[k] !== undefined)
+                out[k] = prop[k];
+        if (prop.type === 'array' && prop.items?.type)
+            out.items = { type: prop.items.type };
+        properties[name] = out;
+    }
+    const result = { type: 'object', properties };
+    if (Array.isArray(schema?.required) && schema.required.length)
+        result.required = schema.required;
+    return result;
+}
+const ONCE_PER_PLACEHOLDER = /\{([A-Za-z_][A-Za-z0-9_]{0,39})\}/g;
+/**
+ * Check a `once_per` template the way the API does, so a mistake fails here with a clear message instead of as a refused wake.
+ * `parameters` is the tool's JSON schema (before or after `toArgenticSchema`). Throws; returns nothing.
+ */
+export function checkOncePer(tool, template, parameters) {
+    const who = `tool "${tool}": `;
+    if (typeof template !== 'string')
+        throw new Error(`${who}once_per must be a string, such as "refund:{order_id}"`);
+    if (template.length < 3 || template.length > 120)
+        throw new Error(`${who}once_per must be 3 to 120 characters`);
+    if (!/^[A-Za-z0-9_:.\-{}]+$/.test(template))
+        throw new Error(`${who}once_per: letters, digits and _ : . - plus {argument} placeholders`);
+    const names = [...template.matchAll(ONCE_PER_PLACEHOLDER)].map((m) => m[1]);
+    if (names.length === 0)
+        throw new Error(`${who}once_per needs at least one {argument}, such as "refund:{order_id}"`);
+    if (/[{}]/.test(template.replace(ONCE_PER_PLACEHOLDER, '')))
+        throw new Error(`${who}once_per has an unmatched brace`);
+    const props = (parameters?.properties ?? {});
+    const required = parameters?.required;
+    for (const n of names) {
+        const p = Object.hasOwn(props, n) ? props[n] : undefined;
+        if (!p || p.type === 'array')
+            throw new Error(`${who}once_per {${n}} must be a string, number, integer or boolean property of this tool`);
+        if (!Array.isArray(required) || !required.includes(n))
+            throw new Error(`${who}once_per {${n}} must be a required property, so every call has a key`);
+    }
+}
+/** Set `once_per` on tools by name (for the AI SDK and Mastra adapters, whose tools have nowhere to carry it). Throws on a name that is not a tool or a template the API would refuse. */
+export function withOncePer(tools, oncePer) {
+    if (!oncePer)
+        return tools;
+    const names = new Set(tools.map((t) => t.name));
+    for (const k of Object.keys(oncePer))
+        if (!names.has(k))
+            throw new Error(`oncePer names "${k}", which is not one of the tools`);
+    return tools.map((t) => {
+        if (!Object.hasOwn(oncePer, t.name))
+            return t;
+        checkOncePer(t.name, oncePer[t.name], toArgenticSchema(t.parameters));
+        return { ...t, once_per: oncePer[t.name] };
+    });
+}
+export class ArgenticError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'ArgenticError';
+    }
+}
+/** True for a 400 whose detail names `results`: a server that does not know the field yet (strict body validation). */
+function refusesResults(e) {
+    if (!(e instanceof ArgenticError) || e.status !== 400)
+        return false;
+    const detail = e.body?.detail;
+    if (detail === undefined)
+        return false;
+    return (typeof detail === 'string' ? detail : JSON.stringify(detail)).includes('results');
+}
+/** A next step for an error a first run tends to hit, or undefined. Examples print it instead of a stack trace. */
+export function hintFor(e) {
+    if (!(e instanceof ArgenticError))
+        return undefined;
+    const code = e.body?.error;
+    if (e.status === 401)
+        return 'Check ARGENTIC_API_KEY. A key only works on the API it was made for, so if you set ARGENTIC_BASE_URL, make the key in that dashboard.';
+    if (code === 'model_key_rejected')
+        return 'Your model provider refused MODEL_KEY. Check it is a key for the provider in the error (a free NVIDIA key starts with nvapi-).';
+    if (code === 'bad_model')
+        return 'Your provider does not know this model id. Set ARGENTIC_MODEL_ID to one it serves, or unset it for the free default.';
+    if (e.status === 402)
+        return 'This account hit its usage limit. Argentic is free in beta, so there is nothing to buy: email hi@getargentic.com and we will raise it.';
+    if (e.status === 429)
+        return 'Too many requests a minute for this key. Wait for the time in the error and run the same command again.';
+    if (e.status === undefined || e.status >= 500)
+        return 'The API did not answer. Run the same command again in a minute: it picks up where it stopped.';
+    return undefined;
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+export class Argentic {
+    apiKey;
+    modelKey;
+    baseUrl;
+    timeoutMs;
+    doFetch;
+    backoffMs;
+    maxQueuedWaits;
+    sleep;
+    /** Set once a server has refused `results` as an unknown field; later wakes of this client leave it out. */
+    resultsRefused = false;
+    constructor(opts = {}) {
+        this.apiKey = opts.apiKey ?? process.env.ARGENTIC_API_KEY ?? '';
+        this.modelKey = opts.modelKey || process.env.MODEL_KEY || undefined;
+        this.timeoutMs = opts.timeoutMs ?? defaultTimeoutMs;
+        this.baseUrl = (opts.baseUrl ?? process.env.ARGENTIC_BASE_URL ?? defaultBaseUrl).replace(/\/+$/, '');
+        this.doFetch = opts.fetch ?? fetch;
+        this.backoffMs = opts.backoffMs ?? [1000, 2000, 4000, 8000];
+        this.maxQueuedWaits = opts.maxQueuedWaits ?? 60;
+        this.sleep = opts.sleep ?? wait;
+    }
+    /**
+     * Wake an agent with a message. Safe to call again with the same key:
+     * a queued (409) answer waits and resends, a 5xx or network error retries
+     * with backoff, and a reused key with a different body throws. If the server answers 400 and names `results`, it does
+     * not know that field yet: the same wake goes out once more under the same key without `results`, and this client leaves
+     * `results` out from then on.
+     */
+    async wake(agent, body, idempotencyKey) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+            'Idempotency-Key': idempotencyKey,
+        };
+        if (this.modelKey)
+            headers['X-Model-Key'] = this.modelKey;
+        const path = `/v1/agents/${encodeURIComponent(agent)}/wake`;
+        const { results, ...plain } = body;
+        let res;
+        if (results === undefined || this.resultsRefused) {
+            res = await this.send(path, JSON.stringify(plain), headers);
+        }
+        else {
+            try {
+                res = await this.send(path, JSON.stringify(body), headers);
+            }
+            catch (e) {
+                if (!refusesResults(e))
+                    throw e;
+                this.resultsRefused = true;
+                res = await this.send(path, JSON.stringify(plain), headers);
+            }
+        }
+        const json = (await res.json());
+        return { ...json, idempotentReplay: res.headers.get('Idempotent-Replay') === 'true' };
+    }
+    /** Re-render a wake's prompts from the journal and compare them to what the model was shown. Spends nothing. */
+    async replay(agent, wakeId) {
+        const headers = { Authorization: `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' };
+        const res = await this.send(`/v1/agents/${encodeURIComponent(agent)}/replay`, JSON.stringify({ wake: wakeId }), headers);
+        const json = (await res.json());
+        const turns = json.turns ?? [];
+        const count = (pred) => turns.filter(pred).length;
+        return {
+            ...json,
+            turns,
+            matched: json.matched ?? count((t) => t.match === true),
+            mismatched: json.mismatched ?? count((t) => t.match === false),
+            unverifiable: json.unverifiable ?? count((t) => t.match === null),
+        };
+    }
+    /** What is due now: plans past their wake_at, schedules and timers whose time has come, and agents waiting on an answered approval or a hook. Read only; costs nothing. */
+    async due(opts = {}) {
+        const q = opts.limit === undefined ? '' : `?limit=${encodeURIComponent(String(opts.limit))}`;
+        const res = await this.send(`/v1/due${q}`, undefined, this.plainHeaders(), 'GET');
+        return (await res.json()).due ?? [];
+    }
+    /** Create or replace a recurring schedule (`cron`, five UTC fields) or a one-shot timer (`at`, ISO 8601 with an offset) on an agent. Needs the hosted API to have schedules switched on. */
+    async putSchedule(agent, name, body, opts = {}) {
+        const res = await this.send(this.schedulePath(agent, name, opts.memory), JSON.stringify(body), { ...this.plainHeaders(), 'Content-Type': 'application/json' }, 'PUT');
+        return (await res.json()).schedule;
+    }
+    /** The schedules and timers of one agent. */
+    async schedules(agent, opts = {}) {
+        const res = await this.send(this.schedulePath(agent, undefined, opts.memory), undefined, this.plainHeaders(), 'GET');
+        return (await res.json()).schedules ?? [];
+    }
+    /** Delete a schedule or timer. Throws a 404 ArgenticError if it does not exist. */
+    async deleteSchedule(agent, name, opts = {}) {
+        await this.send(this.schedulePath(agent, name, opts.memory), undefined, this.plainHeaders(), 'DELETE');
+    }
+    /**
+     * Declare an agent's tools once (at most 32). A wake that sends no `tools` uses them; a wake that does send `tools` uses
+     * those instead. Replaces what was stored; an empty list clears it. Returns the stored tools.
+     */
+    async putTools(agent, tools) {
+        const res = await this.send(`/v1/agents/${encodeURIComponent(agent)}/tools`, JSON.stringify({ tools }), { ...this.plainHeaders(), 'Content-Type': 'application/json' }, 'PUT');
+        return (await res.json()).tools ?? [];
+    }
+    /** The tools stored for an agent with putTools(), or an empty list. */
+    async tools(agent) {
+        const res = await this.send(`/v1/agents/${encodeURIComponent(agent)}/tools`, undefined, this.plainHeaders(), 'GET');
+        return (await res.json()).tools ?? [];
+    }
+    /** Where Argentic posts a signed `agent.due` notice (https, port 443, a public host), or null to stop the notices and keep polling due(). Returns the stored address. */
+    async setWakeUrl(url) {
+        const res = await this.send('/v1/settings/wake_url', JSON.stringify({ url }), { ...this.plainHeaders(), 'Content-Type': 'application/json' }, 'PUT');
+        return (await res.json()).wake_url;
+    }
+    /** The wake URL and the signing secret (`whsec_...`) to give handleDue as `secret`. */
+    async notices() {
+        const res = await this.send('/v1/settings/notices', undefined, this.plainHeaders(), 'GET');
+        return (await res.json());
+    }
+    plainHeaders() {
+        return { Authorization: `Bearer ${this.apiKey}` };
+    }
+    schedulePath(agent, name, memory) {
+        const base = `/v1/agents/${encodeURIComponent(agent)}/schedules${name === undefined ? '' : `/${encodeURIComponent(name)}`}`;
+        return memory === undefined ? base : `${base}?memory=${encodeURIComponent(memory)}`;
+    }
+    async send(path, body, headers, method = 'POST') {
+        let failures = 0;
+        let queued = 0;
+        for (;;) {
+            let res;
+            let netError;
+            try {
+                res = await this.doFetch(this.baseUrl + path, {
+                    method,
+                    headers,
+                    ...(body === undefined ? {} : { body }),
+                    ...(this.timeoutMs > 0 ? { signal: AbortSignal.timeout(this.timeoutMs) } : {}),
+                });
+            }
+            catch (e) {
+                netError = e;
+            }
+            if (res && res.ok)
+                return res;
+            // 409 on a wake means queued behind another call; on a schedule write it means a limit, which is the caller's to read.
+            if (res && res.status === 409 && method === 'POST') {
+                const info = (await res.json().catch(() => ({})));
+                if (++queued > this.maxQueuedWaits)
+                    throw new ArgenticError('still queued after waiting', 409, info);
+                await this.sleep(Math.min(Math.max(info.retry_after ?? 1, 0), 5) * 1000);
+                continue;
+            }
+            if (res && res.status < 500) {
+                const info = await res.json().catch(() => undefined);
+                const { error: code, detail } = (info ?? {});
+                const more = detail === undefined ? '' : `: ${typeof detail === 'string' ? detail : JSON.stringify(detail)}`;
+                throw new ArgenticError(`${res.status} ${code ?? res.statusText}${more}`, res.status, info);
+            }
+            // 5xx or network error: same request, same key.
+            if (failures >= this.backoffMs.length) {
+                const what = res ? `HTTP ${res.status}` : String(netError?.message ?? netError);
+                throw new ArgenticError(`gave up after ${failures + 1} tries: ${what}`, res?.status);
+            }
+            await this.sleep(this.backoffMs[failures++]);
+        }
+    }
+}
+/** The notice cannot be trusted or read. Nothing was woken. `code` says why. */
+export class WebhookVerificationError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'WebhookVerificationError';
+    }
+}
+/** `v1,<base64 HMAC-SHA256>` over "id.timestamp.body", keyed by the base64-decoded part of the secret after `whsec_`. Standard Webhooks. */
+export function signNotice(secret, id, timestamp, body) {
+    return `v1,${createHmac('sha256', secretKey(secret)).update(`${id}.${timestamp}.${body}`).digest('base64')}`;
+}
+function secretKey(secret) {
+    const b64 = (secret ?? '').replace(/^whsec_/, '');
+    const key = /^[A-Za-z0-9+/]+={0,2}$/.test(b64) && b64.length % 4 === 0 ? Buffer.from(b64, 'base64') : undefined;
+    if (!key?.length)
+        throw new WebhookVerificationError('the webhook secret is missing or not a whsec_ base64 string (set ARGENTIC_WEBHOOK_SECRET)', 'bad_secret');
+    return key;
+}
+async function readDue(req) {
+    if (typeof Request !== 'undefined' && req instanceof Request)
+        return { body: await req.text(), get: (n) => req.headers.get(n) ?? undefined };
+    const { body, headers } = req;
+    if (headers instanceof Headers)
+        return { body, get: (n) => headers.get(n) ?? undefined };
+    const lower = new Map(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+    return { body, get: (n) => lower.get(n) };
+}
+/**
+ * Check the signature and the time, then parse the notice. No network. The signature is checked against the body exactly as it arrived,
+ * so pass the raw text, not re-serialized JSON. Use it to queue the notice and wake later; the returned `id` is the key to wake with.
+ */
+export async function verifyDue(req, opts = {}) {
+    const key = secretKey(opts.secret ?? process.env.ARGENTIC_WEBHOOK_SECRET);
+    const { body, get } = await readDue(req);
+    const id = get('webhook-id');
+    const stamp = get('webhook-timestamp');
+    const sigs = get('webhook-signature');
+    if (!id || !stamp || !sigs)
+        throw new WebhookVerificationError('missing webhook-id, webhook-timestamp or webhook-signature header', 'missing_header');
+    if (!/^\d{1,12}$/.test(stamp))
+        throw new WebhookVerificationError('webhook-timestamp is not a number of seconds', 'bad_timestamp');
+    const nowS = (opts.now ?? Date.now)() / 1000;
+    if (Math.abs(nowS - Number(stamp)) > (opts.toleranceSeconds ?? 300))
+        throw new WebhookVerificationError('webhook-timestamp is outside the allowed window', 'stale');
+    const expected = createHmac('sha256', key).update(`${id}.${stamp}.${body}`).digest();
+    let ok = false;
+    for (const entry of sigs.split(/\s+/)) {
+        const [version, sig] = entry.split(',');
+        if (version !== 'v1' || !sig)
+            continue;
+        const given = Buffer.from(sig, 'base64');
+        if (given.length === expected.length && timingSafeEqual(given, expected))
+            ok = true;
+    }
+    if (!ok)
+        throw new WebhookVerificationError('no webhook-signature matches', 'bad_signature');
+    let notice;
+    try {
+        notice = JSON.parse(body);
+    }
+    catch {
+        throw new WebhookVerificationError('the notice body is not JSON', 'bad_body');
+    }
+    if (notice?.type !== 'agent.due' || typeof notice.agent !== 'string' || !notice.agent)
+        throw new WebhookVerificationError('not an agent.due notice', 'bad_body');
+    return { notice, id };
+}
+/**
+ * Verify a due notice, then wake the agent for what fell due, on your own model key (the notice carries none).
+ * The wake's idempotency key comes from the notice's webhook-id, so a notice delivered again replays the first wake's answer.
+ * Throws WebhookVerificationError before any call is made if the notice is not valid.
+ */
+export async function handleDue(req, opts = {}) {
+    const { notice, id } = await verifyDue(req, opts);
+    const body = { fire_due: true, model: opts.model ?? freeModel };
+    if (notice.memory != null)
+        body.memory = notice.memory;
+    const wake = await (opts.client ?? new Argentic()).wake(notice.agent, body, safeKey(id));
+    return { notice, wake };
+}
+/** handleDue as a route handler's answer: 200 woken, 401 not verified, 400 unreadable body, 500 secret not set up, 502 the wake failed (so the notice is sent again). */
+export async function handleDueResponse(req, opts = {}) {
+    try {
+        const { notice, wake } = await handleDue(req, opts);
+        return Response.json({ agent: notice.agent, wake_id: wake.wake_id, status: wake.status });
+    }
+    catch (e) {
+        if (e instanceof WebhookVerificationError) {
+            const status = e.code === 'bad_body' ? 400 : e.code === 'bad_secret' ? 500 : 401;
+            return Response.json({ error: e.code }, { status });
+        }
+        return Response.json({ error: 'wake_failed' }, { status: 502 });
+    }
+}
+export class Ledger {
+    path;
+    entries = {};
+    wakes = {};
+    /**
+     * A missing file starts an empty ledger. A file that cannot be read or parsed is set aside as `<path>.corrupt` and `onCorrupt`
+     * is told, because an empty ledger means finished actions may run again. `onCorrupt` defaults to console.warn.
+     */
+    constructor(path, onCorrupt = (m) => console.warn(m)) {
+        this.path = path;
+        let text;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return;
+            onCorrupt(`argentic: cannot read the ledger ${path} (${e.message}); starting empty, so finished actions may run again`);
+            return;
+        }
+        try {
+            const saved = JSON.parse(text);
+            if (saved === null || typeof saved !== 'object' || Array.isArray(saved))
+                throw new Error('not a JSON object');
+            this.entries = saved.entries ?? {};
+            this.wakes = saved.wakes ?? {};
+        }
+        catch (e) {
+            this.entries = {};
+            this.wakes = {};
+            let kept = '';
+            try {
+                renameSync(path, `${path}.corrupt`);
+                kept = `, the old file is kept as ${path}.corrupt`;
+            }
+            catch { }
+            onCorrupt(`argentic: the ledger ${path} is not valid (${e.message}); starting empty, so finished actions may run again${kept}`);
+        }
+    }
+    get(key) {
+        return this.entries[key];
+    }
+    set(key, entry) {
+        this.entries[key] = entry;
+        this.save();
+    }
+    /** The stopped wake answered for this idempotency key, if one was kept. */
+    getWake(key) {
+        return this.wakes[key];
+    }
+    setWake(key, wake) {
+        this.wakes[key] = wake;
+        this.save();
+    }
+    /** Write temp file, then rename, so a crash never leaves half a ledger. */
+    save() {
+        mkdirSync(dirname(this.path) || '.', { recursive: true });
+        const tmp = `${this.path}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(Object.keys(this.wakes).length ? { entries: this.entries, wakes: this.wakes } : { entries: this.entries }, null, 2));
+        renameSync(tmp, this.path);
+    }
+}
+// ---------------------------------------------------------------------------
+// runDurable
+/**
+ * Throw this from a tool when the outcome is not known yet and the same call is safe to try again:
+ * a network drop, a timeout, a provider that is down. runDurable does not write it to the ledger,
+ * so it stops the run. Run it again and the action is asked for again with the same key.
+ */
+export class RetryLater extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'RetryLater';
+    }
+}
+const safeKey = (s) => s.replace(/[^A-Za-z0-9\-_.:]/g, '-').slice(0, 128);
+/**
+ * A wake stopped by its turn or time limit leaves the agent mid-task. Its actions have not been answered, so the next
+ * wake sends their results and the agent carries on from there with them, instead of the same key resuming it blind.
+ */
+const carriesOn = (s) => s === 'turn_cap' || s === 'time_cap';
+export async function runDurable(opts) {
+    const { client, agent, tools } = opts;
+    const log = opts.log ?? ((line) => console.log(line));
+    const maxSteps = opts.maxSteps ?? 8;
+    const model = opts.model ?? freeModel;
+    const ledger = new Ledger(opts.ledgerPath);
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const decls = tools.map(({ name, description, parameters, once_per }) => {
+        const schema = toArgenticSchema(parameters);
+        if (once_per !== undefined)
+            checkOncePer(name, once_per, schema);
+        return { name, description: description || name, parameters: schema, ...(once_per !== undefined && { once_per }) };
+    });
+    const wakes = [];
+    let message = opts.task;
+    let reply = '';
+    let spentUsd = 0;
+    let status = 'max_steps';
+    let steps = 0;
+    let executed = 0;
+    const structured = opts.structuredResults ?? true;
+    let pending = [];
+    for (let step = 0; step < maxSteps; step++) {
+        const key = safeKey(`${opts.runId}.${step}`);
+        const body = { message, model, tools: decls };
+        if (structured && step > 0 && pending.length)
+            body.results = pending;
+        opts.onWakeStart?.({ step });
+        if (opts.system)
+            body.system = opts.system;
+        if (opts.limits)
+            body.limits = opts.limits;
+        // A stopped wake kept in the ledger is not asked again: its actions get their results under the next key.
+        const kept = ledger.getWake(key);
+        const res = kept ? { ...kept, idempotentReplay: true } : await client.wake(agent, body, key);
+        if (!kept && carriesOn(res.status) && res.actions?.length) {
+            const { idempotentReplay: _, ...answer } = res;
+            ledger.setWake(key, answer);
+        }
+        steps = step + 1;
+        wakes.push(res.wake_id);
+        reply = res.reply ?? '';
+        spentUsd += res.spent_usd ?? 0;
+        status = res.status;
+        log(`step ${step}: wake ${res.wake_id} ${res.status}${kept ? ' (stopped answer kept in the ledger)' : res.idempotentReplay ? ' (stored answer replayed)' : ''}`);
+        opts.onWake?.({ step, wakeId: res.wake_id, status: res.status, replayed: !!res.idempotentReplay });
+        const actions = res.actions ?? [];
+        const results = [];
+        for (const action of actions) {
+            const ledgerKey = `${agent}:${action.seq}`;
+            const done = ledger.get(ledgerKey);
+            if (done) {
+                log(`skip seq ${action.seq} ${action.tool}: already done before`);
+                opts.onSkip?.({ tool: action.tool, seq: action.seq });
+                results.push({ tool: action.tool, seq: action.seq, result: done.result });
+                continue;
+            }
+            const tool = byName.get(action.tool);
+            let result;
+            if (!tool) {
+                result = { error: 'unknown tool' };
+            }
+            else {
+                try {
+                    result = await tool.execute(action.args ?? {}, { seq: action.seq, idempotencyKey: ledgerKey });
+                }
+                catch (e) {
+                    if (e instanceof RetryLater)
+                        throw e;
+                    result = { error: e instanceof Error ? e.message : String(e) };
+                }
+            }
+            ledger.set(ledgerKey, { tool: action.tool, args: action.args ?? {}, result: result ?? null, at: new Date().toISOString() });
+            executed++;
+            log(`ran seq ${action.seq} ${action.tool}`);
+            results.push({ tool: action.tool, seq: action.seq, result: ledger.get(ledgerKey).result });
+            opts.onAction?.({ tool: action.tool, seq: action.seq, executed });
+            if (opts.crashAfterActions && executed >= opts.crashAfterActions) {
+                log(`simulating a crash after ${executed} action(s)`);
+                process.kill(process.pid, 'SIGKILL');
+            }
+        }
+        if (actions.length === 0 || !(res.status === 'done' || carriesOn(res.status)))
+            break;
+        message = 'Results of the tools you asked for:\n' + JSON.stringify(results);
+        pending = results.map(({ seq, result }) => ({ seq, result }));
+    }
+    return { reply, wakes, steps, status, spentUsd };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};