@argentic-ai/client 0.1.14 → 0.2.0

package/README.md

@@ -8,11 +8,9 @@ Each tool call the agent makes comes back to your code to carry out. If the proc
 
 ## Try it
 
-```
-npx @argentic-ai/client demo
-```
+Install it below and run the example under Use. To compare Argentic with a plain loop on a scripted scenario, run `npx @argentic-ai/check` (see the [repo README](../../README.md#try-it)).
 
-Set `ARGENTIC_API_KEY` and `MODEL_KEY` first. Press Ctrl-C while it works, run it again, and it skips what already finished. Details in the [repo README](../../README.md#run-the-demo-2-minutes).
+Client 0.2.0 removed `npx @argentic-ai/client demo` and the `argentic` command with it, and renamed `runDurable` to `run` and `DurableTool` to `Tool`. The old names still work as deprecated aliases (Python: `run_durable` is now `run`, with the old name kept and a `DeprecationWarning`). Nothing else in the library changed.
 
 ## Install
 
@@ -20,7 +18,7 @@ Set `ARGENTIC_API_KEY` and `MODEL_KEY` first. Press Ctrl-C while it works, run i
 npm i @argentic-ai/client
 ```
 
-- `@argentic-ai/client`: the client and `runDurable`, no dependencies, Node 22+.
+- `@argentic-ai/client`: the client and `run`, no dependencies, Node 22+.
 - `@argentic-ai/client/ai-sdk`: `fromAiSdkTools`, needs `ai` v5, v6 or v7.
 - `@argentic-ai/client/tools`: `toolPack`, retry-safe tools for Stripe, Resend, SMTP, Slack, GitHub and a generic HTTP POST. See [TOOLS.md](TOOLS.md).
 - `@argentic-ai/client/mastra`: `fromMastraTools`, takes the `createTool()` tools you would pass to an Agent (the key is the tool name). Needs `@mastra/core` 1.x for the tools; the adapter itself imports nothing.
@@ -32,7 +30,7 @@ To vendor it instead: clone this repo and copy `argentic.ts`, `ai-sdk.ts` and `m
 ```ts
 import { tool } from 'ai'
 import { z } from 'zod'
-import { Argentic, runDurable } from '@argentic-ai/client'
+import { Argentic, run } from '@argentic-ai/client'
 import { fromAiSdkTools } from '@argentic-ai/client/ai-sdk'
 
 const tools = { refund_order: tool({
@@ -43,7 +41,7 @@ const tools = { refund_order: tool({
 
 // apiKey defaults to ARGENTIC_API_KEY and modelKey to MODEL_KEY
 const client = new Argentic()
-const out = await runDurable({
+const out = await run({
   client, agent: 'my-agent', runId: 'order-1182', ledgerPath: '.argentic-ledger.json',
   task: 'Refund order 1182.', system: 'Call one tool per turn.',
   tools: await fromAiSdkTools(tools),
@@ -51,11 +49,11 @@ const out = await runDurable({
 console.log(out.reply)
 ```
 
-Keep `agent` and `runId` the same across restarts. A request that takes longer than `timeoutMs` (default 300000, 0 for no limit) counts as a network failure and is retried with the same key. If the ledger file is not valid JSON, `runDurable` warns on stderr, sets the file aside as `<path>.corrupt` and starts empty, so finished actions may run again. `client.replay(agent, wakeId)` re-renders a wake's prompts from the journal and compares them to what the model saw; it calls no model and spends nothing.
+Keep `agent` and `runId` the same across restarts. A request that takes longer than `timeoutMs` (default 300000, 0 for no limit) counts as a network failure and is retried with the same key. If the ledger file is not valid JSON, `run` warns on stderr, sets the file aside as `<path>.corrupt` and starts empty, so finished actions may run again. `client.replay(agent, wakeId)` re-renders a wake's prompts from the journal and compares them to what the model saw; it calls no model and spends nothing.
 
 ## Once per operation (`once_per`, 0.1.7)
 
-A tool can declare `once_per`, a key such as `refund:{order_id}` filled in from the call's arguments. Argentic then refuses a second call with the same key, in this wake or any later one. Set it on a `DurableTool` directly, or pass `{ oncePer: { refund_order: 'refund:{order_id}' } }` as the second argument to `fromAiSdkTools` or `fromMastraTools`. The template is checked before the request is sent. See [TOOLS.md](TOOLS.md#declaring-a-tool-once_per). 0.1.6 and earlier dropped the field.
+A tool can declare `once_per`, a key such as `refund:{order_id}` filled in from the call's arguments. Argentic then refuses a second call with the same key, in this wake or any later one. Set it on a `Tool` directly, or pass `{ oncePer: { refund_order: 'refund:{order_id}' } }` as the second argument to `fromAiSdkTools` or `fromMastraTools`. The template is checked before the request is sent. See [TOOLS.md](TOOLS.md#declaring-a-tool-once_per). 0.1.6 and earlier dropped the field.
 
 ## Tools, context and deferred loading (0.1.10)
 
@@ -68,7 +66,7 @@ const out = await client.wake('support-bot', { message: 'Book Tuesday.', model:
 
 ## Structured tool results (0.1.11)
 
-`runDurable` answers the tools an agent asked for with a text message the model reads, and now also sends the same results as the `results` field of the wake: `[{ seq, result }]`, where `seq` is the action's `seq` and `result` is exactly what the tool returned (or the `{ error }` object when it threw). The API journals each as the real result of that call. The first wake of a run has none, and a result the ledger already held is sent again like the others. Pass `structuredResults: false` to send the text only. If the API you talk to does not know the field yet, it answers 400 and names `results`; the client sends that wake again once without it, under the same key, and leaves it out from then on. Calling `client.wake()` yourself, add `results` to the body next to the `message`, never with `fire_due`, at most 100 entries.
+`run` answers the tools an agent asked for with a text message the model reads, and now also sends the same results as the `results` field of the wake: `[{ seq, result }]`, where `seq` is the action's `seq` and `result` is exactly what the tool returned (or the `{ error }` object when it threw). The API journals each as the real result of that call. The first wake of a run has none, and a result the ledger already held is sent again like the others. Pass `structuredResults: false` to send the text only. If the API you talk to does not know the field yet, it answers 400 and names `results`; the client sends that wake again once without it, under the same key, and leaves it out from then on. Calling `client.wake()` yourself, add `results` to the body next to the `message`, never with `fire_due`, at most 100 entries.
 
 ## Waking on a schedule (handleDue)
 

package/dist/ai-sdk.d.ts

@@ -1,9 +1,9 @@
 import { type ToolSet } from 'ai';
-import { type DurableTool } from './argentic.ts';
+import { type Tool } from './argentic.ts';
 /**
  * The tool name is the ToolSet key. Async because a JSON schema may be a promise.
  * `oncePer` maps a tool name to its `once_per` template, such as `{ refund_order: 'refund:{order_id}' }`.
  */
 export declare function fromAiSdkTools(tools: ToolSet, opts?: {
     oncePer?: Record<string, string>;
-}): Promise<DurableTool[]>;
+}): Promise<Tool[]>;

package/dist/argentic.d.ts

@@ -306,7 +306,7 @@ export declare class Ledger {
 }
 /**
  * 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,
+ * a network drop, a timeout, a provider that is down. run 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 declare class RetryLater extends Error {
@@ -318,9 +318,11 @@ export interface ToolContext {
     /** `${agent}:${seq}`. Use it to make the side effect safe to repeat. */
     idempotencyKey: string;
 }
-export interface DurableTool extends ToolDecl {
+export interface Tool extends ToolDecl {
     execute: (args: any, ctx: ToolContext) => unknown | Promise<unknown>;
 }
+/** @deprecated Renamed to `Tool` in 0.2.0. Same type; this name stays so existing code keeps compiling. */
+export type DurableTool = Tool;
 export interface ActionInfo {
     tool: string;
     seq: number;
@@ -334,7 +336,7 @@ export interface RunOptions {
     runId: string;
     task: string;
     system?: string;
-    tools: DurableTool[];
+    tools: Tool[];
     ledgerPath: string;
     model?: ModelSpec;
     maxSteps?: number;
@@ -373,4 +375,6 @@ export interface RunResult {
     status: WakeStatus | 'max_steps';
     spentUsd: number;
 }
-export declare function runDurable(opts: RunOptions): Promise<RunResult>;
+export declare function run(opts: RunOptions): Promise<RunResult>;
+/** @deprecated Renamed to `run` in 0.2.0. Same function; this name stays so existing code keeps working. */
+export declare const runDurable: typeof run;

package/dist/argentic.js

@@ -1,4 +1,4 @@
-// Argentic core: a small client and a durable tool loop. No dependencies, Node 22+.
+// Argentic core: a small client and a 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';
@@ -453,10 +453,10 @@ export class Ledger {
     }
 }
 // ---------------------------------------------------------------------------
-// runDurable
+// run
 /**
  * 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,
+ * a network drop, a timeout, a provider that is down. run 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 {
@@ -473,7 +473,7 @@ const safeKey = (s) => s.replace(/[^A-Za-z0-9\-_.:]/g, '-').slice(0, 128);
  * 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) {
+export async function run(opts) {
     const { client, agent, tools } = opts;
     const log = opts.log ?? ((line) => console.log(line));
     const maxSteps = opts.maxSteps ?? 8;
@@ -562,3 +562,5 @@ export async function runDurable(opts) {
     }
     return { reply, wakes, steps, status, spentUsd };
 }
+/** @deprecated Renamed to `run` in 0.2.0. Same function; this name stays so existing code keeps working. */
+export const runDurable = run;

package/dist/mastra.d.ts

@@ -1,4 +1,4 @@
-import { type DurableTool } from './argentic.ts';
+import { type Tool } from './argentic.ts';
 interface MastraToolLike {
     description?: string;
     inputSchema?: unknown;
@@ -10,5 +10,5 @@ interface MastraToolLike {
  */
 export declare function fromMastraTools(tools: Record<string, MastraToolLike>, opts?: {
     oncePer?: Record<string, string>;
-}): DurableTool[];
+}): Tool[];
 export {};

package/dist/tools.d.ts

@@ -1,4 +1,4 @@
-import { type DurableTool } from './argentic.ts';
+import { type Tool } from './argentic.ts';
 /** What to do with a Slack, GitHub or SMTP action that may or may not have landed and cannot be checked. */
 export type Ambiguous = 'hold' | 'retry';
 export interface StripeOptions {
@@ -68,8 +68,8 @@ export interface ToolPackOptions {
 /** A key a provider accepts (Stripe allows 255 characters, Resend 256). */
 export declare function providerKey(key: string): string;
 /**
- * Tools for runDurable. Pass only the services you use; each tool is built from your options and your
+ * Tools for run. Pass only the services you use; each tool is built from your options and your
  * secrets, never from anything the model sends. With Resend and SMTP both set, Resend is `send_email`
  * and SMTP is `send_email_smtp`.
  */
-export declare function toolPack(opts: ToolPackOptions): DurableTool[];
+export declare function toolPack(opts: ToolPackOptions): Tool[];

package/dist/tools.js

@@ -547,7 +547,7 @@ function httpTools(rt, o) {
 }
 // ---------------------------------------------------------------------------
 /**
- * Tools for runDurable. Pass only the services you use; each tool is built from your options and your
+ * Tools for run. Pass only the services you use; each tool is built from your options and your
  * secrets, never from anything the model sends. With Resend and SMTP both set, Resend is `send_email`
  * and SMTP is `send_email_smtp`.
  */

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@argentic-ai/client",
-  "version": "0.1.14",
+  "version": "0.2.0",
   "description": "Argentic client for TypeScript. The engine runs your agent for hours, rebuilding each prompt from a journal (state blocks plus a recent tail of about 40K tokens) instead of an ever-growing transcript. Adapters for the Vercel AI SDK and Mastra.",
   "license": "MIT",
   "type": "module",
   "engines": { "node": ">=22" },
   "files": ["dist", "README.md", "LICENSE"],
   "main": "./dist/argentic.js",
-  "bin": { "argentic": "./dist/cli.js" },
   "types": "./dist/argentic.d.ts",
   "exports": {
     ".": { "types": "./dist/argentic.d.ts", "default": "./dist/argentic.js" },

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -1,197 +0,0 @@
-#!/usr/bin/env node
-// `npx @argentic-ai/client demo`: kill an agent mid-run, run it again, and watch it skip what already finished.
-// Uses only the published client. State lives in ./.argentic-demo/ so a rerun from the same folder picks up the same run.
-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { Argentic, freeModel, hintFor, runDurable } from "./argentic.js";
-const color = process.stdout.isTTY && !process.env.NO_COLOR;
-const paint = (code) => (s) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
-const dim = paint('2');
-const bold = paint('1');
-const green = paint('32');
-const yellow = paint('33');
-const out = (s = '') => process.stdout.write(s + '\n');
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const system = 'Tool calls are requests: their outcomes arrive in the next message. ' +
-    'Call one tool per turn. When everything is done, reply with a one-line summary and no tool call.';
-const task = 'Order 1182 (ticket T-77, customer dana@example.com) arrived broken. Refund the $42 order, ' +
-    'email the customer that the refund is on its way, then close the ticket. Do one step at a time.';
-const usage = `Usage: npx @argentic-ai/client demo [--fresh] [--kill-after N]
-
-  --fresh         start a new run (forget the one in ./.argentic-demo/)
-  --kill-after N  kill the process yourself after N actions, instead of pressing Ctrl-C
-
-Needs ARGENTIC_API_KEY (from https://getargentic.com/platform) and MODEL_KEY
-(your model provider's key; the default model is a free NVIDIA one, key from https://build.nvidia.com).`;
-/** The side effects land in outbox.jsonl, keyed by the action's stable key, so a repeat is visible and harmless. */
-function makeTools(outbox, workMs) {
-    const sent = (key) => existsSync(outbox) && readFileSync(outbox, 'utf8').split('\n').some((l) => l && JSON.parse(l).key === key);
-    const act = async (key, seq, tool, what, data, result) => {
-        process.stdout.write(`  ${bold('▸')} #${seq} ${tool.padEnd(14)} ${what} ${dim('…')}`);
-        await sleep(workMs);
-        if (sent(key)) {
-            out(` ${yellow('already in the outbox under this key, not sent again')}`);
-        }
-        else {
-            appendFileSync(outbox, JSON.stringify({ key, tool, ...data, at: new Date().toISOString() }) + '\n');
-            out(` ${green('done')}`);
-        }
-        return result;
-    };
-    const str = { type: 'string' };
-    return [
-        {
-            name: 'refund_order',
-            description: 'Refund an order.',
-            parameters: { type: 'object', properties: { order_id: str, amount_usd: { type: 'number' } }, required: ['order_id', 'amount_usd'] },
-            execute: (a, { idempotencyKey, seq }) => act(idempotencyKey, seq, 'refund_order', `$${a.amount_usd} on order ${a.order_id}`, a, { refunded: true, order_id: a.order_id, amount_usd: a.amount_usd }),
-        },
-        {
-            name: 'send_email',
-            description: 'Send an email to a customer.',
-            parameters: { type: 'object', properties: { to: str, subject: str, body: str }, required: ['to', 'subject', 'body'] },
-            execute: (a, { idempotencyKey, seq }) => act(idempotencyKey, seq, 'send_email', `to ${a.to}`, a, { sent: true, to: a.to }),
-        },
-        {
-            name: 'close_ticket',
-            description: 'Close a support ticket with a note.',
-            parameters: { type: 'object', properties: { ticket_id: str, note: str }, required: ['ticket_id', 'note'] },
-            execute: (a, { idempotencyKey, seq }) => act(idempotencyKey, seq, 'close_ticket', `ticket ${a.ticket_id}`, a, { closed: true, ticket_id: a.ticket_id }),
-        },
-    ];
-}
-function modelFromEnv() {
-    const e = process.env;
-    if (!e.ARGENTIC_MODEL_ID)
-        return freeModel;
-    return {
-        provider: e.ARGENTIC_MODEL_PROVIDER ?? freeModel.provider,
-        id: e.ARGENTIC_MODEL_ID,
-        prices: { in: Number(e.ARGENTIC_PRICE_IN ?? 0), out: Number(e.ARGENTIC_PRICE_OUT ?? 0) },
-    };
-}
-async function demo(argv) {
-    const apiKey = process.env.ARGENTIC_API_KEY;
-    const modelKey = process.env.MODEL_KEY;
-    if (!apiKey || !modelKey) {
-        console.error(`Set ARGENTIC_API_KEY and MODEL_KEY first.\n\n${usage}`);
-        process.exit(1);
-    }
-    const at = argv.indexOf('--kill-after');
-    const killAfter = at >= 0 ? Number(argv[at + 1]) || undefined : undefined;
-    const dir = '.argentic-demo';
-    const statePath = join(dir, 'run.json');
-    const ledgerPath = join(dir, 'ledger.json');
-    const outbox = join(dir, 'outbox.jsonl');
-    if (argv.includes('--fresh'))
-        rmSync(dir, { recursive: true, force: true });
-    mkdirSync(dir, { recursive: true });
-    const resuming = existsSync(statePath);
-    if (!resuming) {
-        const id = Math.random().toString(36).slice(2, 8);
-        writeFileSync(statePath, JSON.stringify({ agent: `kill-demo-${id}`, runId: `run-${id}` }));
-    }
-    const { agent, runId } = JSON.parse(readFileSync(statePath, 'utf8'));
-    const finishedBefore = existsSync(ledgerPath) ? Object.keys(JSON.parse(readFileSync(ledgerPath, 'utf8')).entries ?? {}).length : 0;
-    out(bold('Argentic: kill it mid-run'));
-    out(dim(`agent ${agent}, run ${runId}, state in ./${dir}/`));
-    out();
-    if (!resuming) {
-        out('A support agent works one ticket in three actions: refund the order, email the customer, close the ticket.');
-        out(`Press ${bold('Ctrl-C')} while it works, then run the same command again.`);
-    }
-    else {
-        out(`Picking up ${runId}: ${finishedBefore} action${finishedBefore === 1 ? '' : 's'} finished before it stopped.`);
-        out('Same run, same keys. Finished actions are skipped, the rest carry on.');
-    }
-    out();
-    process.on('SIGINT', () => {
-        out('\n');
-        out(yellow('Killed mid-run.') + ' Run the same command again and it picks up where it stopped.');
-        process.exit(130);
-    });
-    const client = new Argentic({ apiKey, modelKey });
-    let ran = 0;
-    let hinted = resuming || killAfter !== undefined;
-    const res = await runDurable({
-        client,
-        agent,
-        runId,
-        task,
-        system,
-        tools: makeTools(outbox, Number(process.env.ARGENTIC_DEMO_WORK_MS ?? 1500)),
-        ledgerPath,
-        model: modelFromEnv(),
-        maxSteps: 10,
-        crashAfterActions: killAfter,
-        log: () => { },
-        onWakeStart: ({ step }) => {
-            if (step === 0 && !resuming)
-                out(dim('  The first answer can take 15 seconds and nothing runs before it, so wait for the first action before pressing Ctrl-C.'));
-            process.stdout.write(dim(`  model turn ${step + 1}: asking the model… `));
-        },
-        onWake: ({ replayed }) => {
-            if (replayed)
-                out(dim('answer already in the journal, sent back without calling the model again'));
-            else
-                out(dim('answered'));
-        },
-        onSkip: ({ tool, seq }) => out(`  ${dim('↷')} #${seq} ${tool.padEnd(14)} ${dim('finished on an earlier run, skipped')}`),
-        onAction: ({ executed }) => {
-            ran = executed;
-            if (killAfter && executed >= killAfter)
-                out(yellow(`\nKilling the process now (--kill-after ${killAfter}). Run the same command without it.`));
-            else if (!hinted) {
-                hinted = true;
-                out(yellow('  Now is a good time to press Ctrl-C.'));
-            }
-        },
-    });
-    out();
-    out(`${bold('Reply:')} ${res.reply || dim('(none)')}`);
-    out(dim(`status ${res.status}, ${res.steps} model turns, ${ran} action${ran === 1 ? '' : 's'} run in this process, spent $${res.spentUsd.toFixed(4)}`));
-    const counts = { refund_order: 0, send_email: 0, close_ticket: 0 };
-    if (existsSync(outbox))
-        for (const l of readFileSync(outbox, 'utf8').split('\n'))
-            if (l)
-                counts[JSON.parse(l).tool] = (counts[JSON.parse(l).tool] ?? 0) + 1;
-    out();
-    out(bold('What happened, from the outbox') + dim(` (./${outbox})`));
-    for (const [tool, n] of Object.entries(counts))
-        out(`  ${tool.padEnd(14)} ${n === 1 ? green('1 time') : yellow(`${n} times`)}`);
-    out();
-    out(bold('Proof of what ran') + dim(' (re-renders each prompt from the journal and compares it with what the model was sent; free)'));
-    let clean = true;
-    for (const wake of res.wakes) {
-        const r = await client.replay(agent, wake);
-        const ok = r.mismatched === 0 && r.unverifiable === 0;
-        clean &&= ok;
-        out(`  ${wake}  ${ok ? green('all match') : yellow(`${r.mismatched} differ, ${r.unverifiable} not checkable`)}`);
-    }
-    if (res.status !== 'done')
-        out(yellow(`\nThe run stopped with status ${res.status}. Run the same command again to carry on.`));
-    const dash = (process.env.ARGENTIC_DASHBOARD_URL ?? 'https://getargentic.com').replace(/\/+$/, '');
-    out();
-    out(`See it in the dashboard: ${dash}/platform/ ${dim('->')} Runs ${dim('->')} ${agent}`);
-    out(dim('Open the oldest run (the one you killed) and press Check under Proof of what ran.'));
-    if (resuming && res.status === 'done') {
-        out();
-        out(`${bold('Worth showing someone?')} On that run page, press Share proof for a read-only link.`);
-        out(dim('It shows what ran and each action’s key. Messages and tool data stay private, and you can stop sharing any time.'));
-    }
-    out(dim('Start over with --fresh.'));
-    if (!clean)
-        process.exitCode = 1;
-}
-const [cmd, ...rest] = process.argv.slice(2);
-if (cmd !== 'demo') {
-    out(usage);
-    process.exit(cmd === undefined || cmd === '--help' || cmd === '-h' ? 0 : 1);
-}
-await demo(rest).catch((e) => {
-    const hint = hintFor(e);
-    if (!hint)
-        throw e;
-    console.error(`\n${e instanceof Error ? e.message : String(e)}\n${hint}`);
-    process.exit(1);
-});