@argentic-ai/client 0.0.0-stage → 0.1.13

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Argentic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# Argentic for TypeScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Argentic runs the agent loop. Your Vercel AI SDK or Mastra tools and system prompt carry over; the framework's own loop (`generateText`, `Agent`, Mastra `Agent.generate`) is not used.
+
+Each turn, Argentic rebuilds the prompt from a journal of the run instead of replaying an ever-growing transcript: state blocks plus a recent tail of about 40K tokens. The journal keeps the full record, so you can see every step the agent took and check it against what the model saw.
+
+Each tool call the agent makes comes back to your code to carry out. If the process dies mid-run, run it again: it resumes without repeating a finished action.
+
+## Try it
+
+```
+npx @argentic-ai/client demo
+```
+
+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).
+
+## Install
+
+```
+npm i @argentic-ai/client
+```
+
+- `@argentic-ai/client`: the client and `runDurable`, 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.
+
+To vendor it instead: clone this repo and copy `argentic.ts`, `ai-sdk.ts` and `mastra.ts` into your project (Node 22+, no package needed beyond what you already use).
+
+## Use
+
+```ts
+import { tool } from 'ai'
+import { z } from 'zod'
+import { Argentic, runDurable } from '@argentic-ai/client'
+import { fromAiSdkTools } from '@argentic-ai/client/ai-sdk'
+
+const tools = { refund_order: tool({
+  description: 'Refund an order.',
+  inputSchema: z.object({ order_id: z.string(), amount_usd: z.number() }),
+  execute: async (args, { toolCallId }) => refund(args, toolCallId),
+}) }
+
+// apiKey defaults to ARGENTIC_API_KEY and modelKey to MODEL_KEY
+const client = new Argentic()
+const out = await runDurable({
+  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),
+})
+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.
+
+## 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.
+
+## Tools, context and deferred loading (0.1.10)
+
+Declare an agent's tools once with `client.putTools(agent, tools)` and leave `tools` out of later wakes; `client.tools(agent)` reads them back. A wake can also carry `context` (facts for that call only, such as the signed-in user's plan; it is not written to the journal) and `tool_choice` (`'auto'`, `'required'` or `{ type: 'tool', name }`). On a tool, `defer_loading: true` keeps its schema out of the prompt until the agent looks it up, which pays off from about ten tools.
+
+```ts
+await client.putTools('support-bot', [{ name: 'book_slot', description: 'Book a slot.', parameters: { type: 'object', properties: { day: { type: 'string' } }, required: ['day'] } }])
+const out = await client.wake('support-bot', { message: 'Book Tuesday.', model: freeModel, context: 'Plan: pro' }, 'book-1')
+```
+
+## 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.
+
+## Waking on a schedule (handleDue)
+
+Create a recurring schedule or a one-shot timer, and read what is due:
+
+```ts
+const client = new Argentic()
+await client.putSchedule('support-bot', 'morning-check', { cron: '0 9 * * *', message: 'Review overnight tickets.' }) // five UTC fields
+await client.putSchedule('support-bot', 'follow-up', { at: '2026-11-20T09:00:00Z', message: 'Chase the open refund.' }) // one-shot
+await client.schedules('support-bot')   // name, cron or at, next_at, last_fired_at, fires
+await client.due()                      // what is due now; wake each agent with fire_due, or let the notice below do it
+await client.deleteSchedule('support-bot', 'follow-up')
+```
+
+
+Beta, off by default on the hosted API, and open to single beta users only for now. When an agent falls due (a plan's `wake_at`, a schedule, a timer or a hook event), Argentic POSTs a signed notice to the `wake_url` you registered. The notice names the agent and why it is due and carries no agent content and no model key. `handleDue` checks the signature and the time, then wakes the agent with `fire_due` on your own model key.
+
+Register the address and read the secret with the client: `await client.setWakeUrl('https://app.example.com/argentic/due')`, then `(await client.notices()).signing_secret` (`whsec_...`). Store it like a password, for example as `ARGENTIC_WEBHOOK_SECRET`. The model key stays on your server: set `MODEL_KEY` there, as for any other wake.
+
+```ts
+import { Hono } from 'hono'
+import { handleDueResponse } from '@argentic-ai/client'
+
+const app = new Hono()
+// Reads ARGENTIC_API_KEY, MODEL_KEY and ARGENTIC_WEBHOOK_SECRET from the environment.
+app.post('/argentic/due', (c) => handleDueResponse(c.req.raw))
+```
+
+`handleDueResponse` answers 200 when the agent was woken, 401 if the signature or time is wrong, 400 if the body is not an `agent.due` notice, 500 if the secret is missing or malformed, and 502 if the wake itself failed (the notice is then sent again). It takes a Fetch `Request` or `{ body, headers }` with the raw body text, and works the same in a Next.js route handler. `handleDue(request, { secret, client, model, toleranceSeconds })` returns `{ notice, wake }` and throws `WebhookVerificationError` (with a `code`) before any call is made. `verifyDue(request)` only verifies and parses, so you can queue the notice and wake later. The wake uses the notice's `webhook-id` as its idempotency key, so a notice delivered twice replays the first wake instead of waking twice. Timestamps more than 300 seconds off are refused.
+
+## What to know
+
+Delivery is at-least-once. An action that was running when the process died, before its result reached the local ledger, runs again on resume. Make your handlers safe to repeat: the AI SDK `toolCallId` your `execute` receives is a stable key (`agent:seq`) to dedupe on.
+
+Mastra tools get the same key as `context.agent.toolCallId`.
+
+Full walkthroughs: [`examples/ai-sdk`](../../examples/ai-sdk), [`examples/mastra`](../../examples/mastra).

package/dist/ai-sdk.d.ts

@@ -0,0 +1,9 @@
+import { type ToolSet } from 'ai';
+import { type DurableTool } 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[]>;

package/dist/ai-sdk.js

@@ -0,0 +1,32 @@
+// Vercel AI SDK (v5/v6) on-ramp: your tool() objects become Argentic tools.
+// Only the tools carry over. Argentic runs the loop, not generateText or Agent.
+import { asSchema } from 'ai';
+import { withOncePer } from "./argentic.js";
+const isAsyncIterable = (v) => typeof v === 'object' && v !== null && Symbol.asyncIterator in v;
+/**
+ * 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 async function fromAiSdkTools(tools, opts = {}) {
+    return withOncePer(await Promise.all(Object.entries(tools).map(async ([name, t]) => {
+        const parameters = (await asSchema(t.inputSchema).jsonSchema);
+        return {
+            name,
+            description: t.description ?? '',
+            parameters,
+            execute: async (args, ctx) => {
+                if (!t.execute)
+                    return { error: `tool ${name} has no execute function` };
+                let out = await t.execute(args, { toolCallId: ctx.idempotencyKey, messages: [] });
+                // A streaming tool yields many values; the last one is its result.
+                if (isAsyncIterable(out)) {
+                    let last;
+                    for await (const part of out)
+                        last = part;
+                    out = last;
+                }
+                return out;
+            },
+        };
+    })), opts.oncePer);
+}

package/dist/argentic.d.ts

@@ -0,0 +1,376 @@
+export declare 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 declare const defaultTimeoutMs = 300000;
+export interface ModelSpec {
+    provider: string;
+    id: string;
+    prices: {
+        in: number;
+        out: number;
+    };
+}
+/** The free default model. */
+export declare const freeModel: ModelSpec;
+/** What Argentic is told about a tool. It is declared, never executed by Argentic. */
+export interface ToolDecl {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    /**
+     * A business-operation key such as `refund:{order_id}`. Each `{name}` is filled in from the call's arguments, and Argentic
+     * refuses a second call that produces the same key, whatever else it writes. Every `{name}` must be a required string,
+     * number, integer or boolean parameter of this tool. Left out, nothing about the tool request changes.
+     */
+    once_per?: string;
+    /**
+     * Leave this tool out of the prompt. The agent finds it by describing what it needs (`find_tools`) and calls it through
+     * `use_tool`; the call still comes back in `actions` as this tool. Worth it from about ten tools or ten thousand tokens of
+     * schemas. Not allowed on a tool that waits for a person or is named in `tool_choice`.
+     */
+    defer_loading?: true;
+}
+/**
+ * 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 declare function toArgenticSchema(schema: Record<string, any>): Record<string, unknown>;
+/**
+ * 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 declare function checkOncePer(tool: string, template: unknown, parameters: Record<string, unknown>): void;
+/** 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 declare function withOncePer<T extends ToolDecl>(tools: T[], oncePer?: Record<string, string>): T[];
+export interface WakeBody {
+    /** Required unless `fire_due` is set; the API refuses both together. */
+    message?: string;
+    /** Wake for the plans, schedules and timers that have fallen due instead of with a message. */
+    fire_due?: boolean;
+    /** Which memory of the agent to wake. Left out, the agent's default. */
+    memory?: string;
+    model: ModelSpec;
+    system?: string;
+    /** Facts for this call only (opening hours, the signed-in user's plan), up to 16,000 characters. Not written to the journal or memory; send it again on the next call if the agent still needs it. */
+    context?: string;
+    tools?: ToolDecl[];
+    /** Whether this call must end with a call to one of your tools. `auto` (default), `required`, or `{ type: 'tool', name }`. */
+    tool_choice?: 'auto' | 'required' | {
+        type: 'tool';
+        name: string;
+    };
+    limits?: {
+        max_usd?: number;
+        max_turns?: number;
+    };
+    /**
+     * What your app's tools returned for the `actions` of the previous wake, as `{ seq, result }`: `seq` is the action's
+     * `seq` and `result` is exactly what the tool returned. The API journals each as the real result of that call. Send it
+     * together with a `message` (the text the model reads), never with `fire_due`; at most 100 entries. A server that does
+     * not know the field yet refuses it, and `wake()` then sends the same wake again without it and stops sending it on
+     * this client.
+     */
+    results?: {
+        seq: number;
+        result: unknown;
+    }[];
+}
+export interface Action {
+    id: string;
+    tool: string;
+    args: Record<string, unknown>;
+    seq: number;
+}
+export type WakeStatus = 'done' | 'spend_cap' | 'budget_cap' | 'turn_cap' | 'time_cap' | 'error' | 'approval_required';
+export interface WakeResult {
+    status: WakeStatus;
+    reply: string;
+    spent_usd: number;
+    turns: number;
+    wake_id: string;
+    actions?: Action[];
+    resumed?: boolean;
+    error?: string;
+    /** True when this key was already answered and the stored answer came back. */
+    idempotentReplay: boolean;
+}
+export interface ReplayTurn {
+    turn_seq: number;
+    wake_id: string | null;
+    match: boolean | null;
+    reason?: string;
+}
+export interface ReplayResult {
+    turns: ReplayTurn[];
+    matched: number;
+    mismatched: number;
+    unverifiable: number;
+    [key: string]: unknown;
+}
+export declare class ArgenticError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, body?: unknown | undefined);
+}
+/** A next step for an error a first run tends to hit, or undefined. Examples print it instead of a stack trace. */
+export declare function hintFor(e: unknown): string | undefined;
+/** The body of a schedule write: exactly one of `cron` or `at`. */
+export interface ScheduleBody {
+    /** Five numeric UTC fields (numbers, `*`, ranges, lists, steps). Occurrences closer than the host's grid (60 minutes in the beta) are refused. */
+    cron?: string;
+    /** A one-shot timer: ISO 8601 with an offset, in the future by at least the grid, at most 366 days ahead. */
+    at?: string;
+    /** What the agent is told when it fires, up to 4,000 characters. */
+    message: string;
+    enabled?: boolean;
+}
+export interface Schedule {
+    name: string;
+    /** Present on a recurring schedule. */
+    cron?: string;
+    /** Present on a one-shot timer, with `timer: true`. */
+    at?: string;
+    timer?: true;
+    message: string;
+    enabled: boolean;
+    next_at: string;
+    last_fired_at: string | null;
+    fires: number;
+}
+/** One entry of due(): a plan (`plan_id`, `wake_at`), a schedule or timer (`schedule`, `scheduled_at`) or an agent waiting on an event (`reasons`, `since`). */
+export interface DueItem {
+    agent: string;
+    memory?: string;
+    plan_id?: number;
+    text?: string;
+    wake_at?: string;
+    schedule?: string;
+    scheduled_at?: string;
+    timer?: true;
+    reasons?: string[];
+    since?: string;
+    /** The notice to your wake_url ran out of attempts. */
+    notice_failing?: true;
+}
+export interface NoticeSettings {
+    wake_url: string | null;
+    /** Give this to handleDue / verifyDue as `secret`. */
+    signing_secret: string;
+}
+export interface ClientOptions {
+    /** Defaults to the ARGENTIC_API_KEY environment variable. */
+    apiKey?: string;
+    /** Sent as X-Model-Key on wake. Defaults to the MODEL_KEY environment variable. */
+    modelKey?: string;
+    baseUrl?: string;
+    /** How long one request may take before that try counts as a network failure, in milliseconds. Default 300000; 0 means no limit. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+    /** Waits between retries of a 5xx or network failure. */
+    backoffMs?: number[];
+    /** Upper bound on 409 queued retries before giving up. */
+    maxQueuedWaits?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class Argentic {
+    private readonly apiKey;
+    private readonly modelKey?;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly doFetch;
+    private readonly backoffMs;
+    private readonly maxQueuedWaits;
+    private readonly sleep;
+    /** Set once a server has refused `results` as an unknown field; later wakes of this client leave it out. */
+    private resultsRefused;
+    constructor(opts?: ClientOptions);
+    /**
+     * 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.
+     */
+    wake(agent: string, body: WakeBody, idempotencyKey: string): Promise<WakeResult>;
+    /** Re-render a wake's prompts from the journal and compare them to what the model was shown. Spends nothing. */
+    replay(agent: string, wakeId: string): Promise<ReplayResult>;
+    /** 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. */
+    due(opts?: {
+        limit?: number;
+    }): Promise<DueItem[]>;
+    /** 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. */
+    putSchedule(agent: string, name: string, body: ScheduleBody, opts?: {
+        memory?: string;
+    }): Promise<Schedule>;
+    /** The schedules and timers of one agent. */
+    schedules(agent: string, opts?: {
+        memory?: string;
+    }): Promise<Schedule[]>;
+    /** Delete a schedule or timer. Throws a 404 ArgenticError if it does not exist. */
+    deleteSchedule(agent: string, name: string, opts?: {
+        memory?: string;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    putTools(agent: string, tools: ToolDecl[]): Promise<ToolDecl[]>;
+    /** The tools stored for an agent with putTools(), or an empty list. */
+    tools(agent: string): Promise<ToolDecl[]>;
+    /** 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. */
+    setWakeUrl(url: string | null): Promise<string | null>;
+    /** The wake URL and the signing secret (`whsec_...`) to give handleDue as `secret`. */
+    notices(): Promise<NoticeSettings>;
+    private plainHeaders;
+    private schedulePath;
+    private send;
+}
+/** What the notice says. It names the agent and why it is due, never its content. */
+export interface DueNotice {
+    type: 'agent.due';
+    agent: string;
+    memory: string | null;
+    reasons: string[];
+    /** ISO time the agent became due. */
+    since: string;
+}
+export type WebhookErrorCode = 'bad_secret' | 'missing_header' | 'bad_timestamp' | 'stale' | 'bad_signature' | 'bad_body';
+/** The notice cannot be trusted or read. Nothing was woken. `code` says why. */
+export declare class WebhookVerificationError extends Error {
+    readonly code: WebhookErrorCode;
+    constructor(message: string, code: WebhookErrorCode);
+}
+/** A Fetch API Request, or the raw body text with its headers. */
+export type DueRequest = Request | {
+    body: string;
+    headers: Record<string, string> | Headers;
+};
+export interface VerifyOptions {
+    /** The `whsec_...` secret shown when the wake_url was registered. Defaults to the ARGENTIC_WEBHOOK_SECRET environment variable. */
+    secret?: string;
+    /** How far the notice's timestamp may be from now, either way, in seconds. Default 300. */
+    toleranceSeconds?: number;
+    /** The current time in milliseconds. For tests. */
+    now?: () => number;
+}
+export interface DueOptions extends VerifyOptions {
+    /** The client that wakes the agent. Defaults to a new Argentic(), which reads ARGENTIC_API_KEY and MODEL_KEY. */
+    client?: Argentic;
+    model?: ModelSpec;
+}
+/** `v1,<base64 HMAC-SHA256>` over "id.timestamp.body", keyed by the base64-decoded part of the secret after `whsec_`. Standard Webhooks. */
+export declare function signNotice(secret: string, id: string, timestamp: number | string, body: string): string;
+/**
+ * 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 declare function verifyDue(req: DueRequest, opts?: VerifyOptions): Promise<{
+    notice: DueNotice;
+    id: string;
+}>;
+/**
+ * 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 declare function handleDue(req: DueRequest, opts?: DueOptions): Promise<{
+    notice: DueNotice;
+    wake: WakeResult;
+}>;
+/** 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 declare function handleDueResponse(req: DueRequest, opts?: DueOptions): Promise<Response>;
+export interface LedgerEntry {
+    tool: string;
+    args: Record<string, unknown>;
+    result: unknown;
+    at: string;
+}
+/** A wake that stopped at its turn or time limit with actions to run, kept so a restart sends their results instead of asking the wake again. */
+export type StoppedWake = Omit<WakeResult, 'idempotentReplay'>;
+export declare class Ledger {
+    readonly path: string;
+    private entries;
+    private 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: string, onCorrupt?: (message: string) => void);
+    get(key: string): LedgerEntry | undefined;
+    set(key: string, entry: LedgerEntry): void;
+    /** The stopped wake answered for this idempotency key, if one was kept. */
+    getWake(key: string): StoppedWake | undefined;
+    setWake(key: string, wake: StoppedWake): void;
+    /** Write temp file, then rename, so a crash never leaves half a ledger. */
+    private save;
+}
+/**
+ * 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 declare class RetryLater extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export interface ToolContext {
+    seq: number;
+    /** `${agent}:${seq}`. Use it to make the side effect safe to repeat. */
+    idempotencyKey: string;
+}
+export interface DurableTool extends ToolDecl {
+    execute: (args: any, ctx: ToolContext) => unknown | Promise<unknown>;
+}
+export interface ActionInfo {
+    tool: string;
+    seq: number;
+    /** Number of actions newly executed in this process so far. */
+    executed: number;
+}
+export interface RunOptions {
+    client: Argentic;
+    agent: string;
+    /** Chosen by you and kept the same across restarts. */
+    runId: string;
+    task: string;
+    system?: string;
+    tools: DurableTool[];
+    ledgerPath: string;
+    model?: ModelSpec;
+    maxSteps?: number;
+    limits?: WakeBody['limits'];
+    /** Called just before each wake is sent, so a caller can say it is waiting on the model (the first answer can take several seconds). */
+    onWakeStart?: (info: {
+        step: number;
+    }) => void;
+    /** Called after each newly executed action is written to the ledger. */
+    onAction?: (info: ActionInfo) => void;
+    /** Called for an action the ledger says already finished, so it is not run again. */
+    onSkip?: (info: {
+        tool: string;
+        seq: number;
+    }) => void;
+    /** Called after each wake answers. `replayed` means the API sent back its stored answer for this key, or the ledger kept a stopped one. */
+    onWake?: (info: {
+        step: number;
+        wakeId: string;
+        status: WakeStatus;
+        replayed: boolean;
+    }) => void;
+    /** Kill this process hard after the Nth newly executed action (to try a crash). */
+    crashAfterActions?: number;
+    /**
+     * Send each follow-up wake's tool results as the structured `results` field as well as in the message text, so the API
+     * journals the real result of every call. Default true. Set false to send the text only.
+     */
+    structuredResults?: boolean;
+    log?: (line: string) => void;
+}
+export interface RunResult {
+    reply: string;
+    wakes: string[];
+    steps: number;
+    status: WakeStatus | 'max_steps';
+    spentUsd: number;
+}
+export declare function runDurable(opts: RunOptions): Promise<RunResult>;