solverr-agent 0.0.0-stage → 0.1.1

package/dist/limits.js

@@ -0,0 +1,31 @@
+import { PaymentError } from "./errors.js";
+/** Validates limits and normalizes host patterns to lowercase. */
+export function normalizeLimits(limits) {
+    for (const [name, value] of [["perPaymentUsd", limits.perPaymentUsd], ["dailyUsd", limits.dailyUsd]]) {
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+            throw new Error(`limits.${name} must be a number of USD, 0 or more.`);
+    }
+    if (!Array.isArray(limits.allow) || limits.allow.some((host) => typeof host !== "string" || !host.trim())) {
+        throw new Error("limits.allow must be a list of host names.");
+    }
+    return { perPaymentUsd: limits.perPaymentUsd, dailyUsd: limits.dailyUsd, allow: limits.allow.map((host) => host.trim().toLowerCase()) };
+}
+export function isHostAllowed(hostname, allow) {
+    const host = hostname.toLowerCase();
+    return allow.some((pattern) => (pattern.startsWith("*.") ? host.endsWith(pattern.slice(1)) : host === pattern));
+}
+export function assertHostAllowed(limits, hostname) {
+    if (!isHostAllowed(hostname, limits.allow)) {
+        throw new PaymentError("host_not_allowed", `Payments to ${hostname} are not allowed. Add it to the allow list to pay this site.`);
+    }
+}
+/** Throws a `PaymentError` when paying `amountUsd` to `hostname` would break a limit. */
+export function enforceLimits(limits, payment) {
+    assertHostAllowed(limits, payment.hostname);
+    if (payment.amountUsd > limits.perPaymentUsd) {
+        throw new PaymentError("per_payment_limit", `This payment costs about $${payment.amountUsd.toFixed(2)}, above the per-payment limit of $${limits.perPaymentUsd.toFixed(2)}.`);
+    }
+    if (payment.spentLast24hUsd + payment.amountUsd > limits.dailyUsd) {
+        throw new PaymentError("daily_limit", `This payment of about $${payment.amountUsd.toFixed(2)} would bring the last 24 hours to $${(payment.spentLast24hUsd + payment.amountUsd).toFixed(2)}, above the daily limit of $${limits.dailyUsd.toFixed(2)}.`);
+    }
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1,13 @@
+import { type StdioServerHandle } from "@modelcontextprotocol/server/stdio";
+import type { AgentWallet } from "./agent-wallet.js";
+import { type SpendingLimits } from "./limits.js";
+export interface McpServerOptions {
+    name: string;
+    version: string;
+    /** `set_limits` can lower limits and narrow the allow list, but never go above these. */
+    ceiling: SpendingLimits;
+}
+/** Checks `requested` against the ceiling configured at startup and returns the merged limits. */
+export declare function limitsWithinCeiling(current: SpendingLimits, requested: Partial<SpendingLimits>, ceiling: SpendingLimits): SpendingLimits;
+/** Serves the agent wallet as an MCP server over stdin and stdout. */
+export declare function serveAgentMcp(agent: AgentWallet, options: McpServerOptions): StdioServerHandle;

package/dist/mcp-server.js

@@ -0,0 +1,153 @@
+import { PAYMENT_RESPONSE_HEADER, decodePaymentResponseHeader, readHeader } from "solverr-x402";
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod/v4";
+import { PaymentError, errorSummary } from "./errors.js";
+import { isHostAllowed } from "./limits.js";
+import { assertFetchAllowed, pinnedDispatcher } from "./url-guard.js";
+/** Longest response body returned to the model, in characters. */
+const MAX_BODY_CHARS = 20_000;
+const TEXT_CONTENT_TYPE = /^(text\/|application\/(json|xml|[\w.+-]+\+(json|xml))|application\/x-www-form-urlencoded)/i;
+const json = (value, isError = false) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }], ...(isError ? { isError: true } : {}) });
+function failure(error) {
+    if (error instanceof PaymentError) {
+        const invoice = error.invoiceId ? { invoice_id: error.invoiceId } : {};
+        return json({ error: { code: error.code, message: error.message, funds_sent: error.fundsSent, ...invoice } }, true);
+    }
+    return json({ error: { code: "request_failed", message: errorSummary(error), funds_sent: false } }, true);
+}
+/** Reads a text body up to the size limit; a body that fails to arrive is described instead, so the status and receipt still reach the model. */
+async function readBody(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    try {
+        if (contentType && !TEXT_CONTENT_TYPE.test(contentType)) {
+            await response.body?.cancel();
+            return { body: `[${contentType} body not shown]`, truncated: false };
+        }
+        if (!response.body)
+            return { body: "", truncated: false };
+        /** Read in chunks and stopped past the limit, so a huge or endless body is never held in memory. */
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let text = "";
+        for (;;) {
+            const { done, value } = await reader.read();
+            text += done ? decoder.decode() : decoder.decode(value, { stream: true });
+            if (text.length > MAX_BODY_CHARS) {
+                await reader.cancel();
+                return { body: text.slice(0, MAX_BODY_CHARS), truncated: true };
+            }
+            if (done)
+                return { body: text, truncated: false };
+        }
+    }
+    catch (error) {
+        return { body: `[body could not be read: ${errorSummary(error, 120)}]`, truncated: false };
+    }
+}
+/** Whether every host matched by `pattern` is also matched by the `ceiling` allow list. */
+function isCoveredBy(pattern, ceiling) {
+    const normalized = pattern.trim().toLowerCase();
+    if (ceiling.includes(normalized))
+        return true;
+    const wildcards = ceiling.filter((entry) => entry.startsWith("*."));
+    return isHostAllowed(normalized.replace(/^\*\./, ""), wildcards);
+}
+/** Checks `requested` against the ceiling configured at startup and returns the merged limits. */
+export function limitsWithinCeiling(current, requested, ceiling) {
+    const next = { ...current, ...requested };
+    if (next.perPaymentUsd > ceiling.perPaymentUsd)
+        throw new Error(`per_payment_usd cannot be above $${ceiling.perPaymentUsd}, the limit set when the server started.`);
+    if (next.dailyUsd > ceiling.dailyUsd)
+        throw new Error(`daily_usd cannot be above $${ceiling.dailyUsd}, the limit set when the server started.`);
+    if (!next.allow.every((pattern) => isCoveredBy(pattern, ceiling.allow))) {
+        throw new Error(`allow can only contain hosts from the startup allow list: ${ceiling.allow.join(", ")}.`);
+    }
+    return next;
+}
+function buildServer(agent, options) {
+    const server = new McpServer({ name: options.name, version: options.version });
+    server.registerTool("pay_url", {
+        title: "Fetch a URL, paying if needed",
+        description: "Fetches a URL on a host in the allow list. If the site answers 402 Payment Required with a Solverr invoice, pays it from the agent wallet within the spending limits, then fetches again. Returns the HTTP status, the payment receipt and the response body; a redirect is returned with its location instead of being followed. If the result has payment_unused true, invoice_id is paid but the site answered with an error and did not use the payment: calling pay_url again with the same method and URL sends that payment again instead of paying a new invoice. If an error says funds_sent is true, money left the wallet for invoice_id: follow the error message before calling pay_url for the same request again.",
+        inputSchema: z.object({
+            url: z.url({ protocol: /^https?$/ }).describe("The http or https URL to fetch."),
+            method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET"),
+            headers: z.record(z.string(), z.string()).optional().describe("Extra request headers."),
+            body: z.string().optional().describe("Request body for POST, PUT or PATCH."),
+        }),
+    }, async ({ url, method, headers, body }) => {
+        try {
+            const target = new URL(url);
+            const dispatcher = pinnedDispatcher(await assertFetchAllowed(target, agent.limits().allow));
+            let response;
+            let text;
+            let truncated;
+            try {
+                /** Redirects are returned, not followed, and connections go only to the checked addresses, so every URL the model reaches passes the checks above. */
+                response = await agent.fetch(target, { method, headers, body, redirect: "manual", dispatcher });
+                ({ body: text, truncated } = await readBody(response));
+            }
+            finally {
+                await dispatcher?.close();
+            }
+            const location = response.headers.get("location");
+            const unusedInvoice = response.status >= 400 ? agent.unusedInvoice(target, method) : undefined;
+            return json({
+                status: response.status,
+                ...(location ? { location } : {}),
+                content_type: response.headers.get("content-type") || null,
+                payment: readHeader(response.headers.get(PAYMENT_RESPONSE_HEADER), decodePaymentResponseHeader) ?? null,
+                ...(unusedInvoice ? { invoice_id: unusedInvoice, payment_unused: true } : {}),
+                body: text,
+                body_truncated: truncated,
+            });
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.registerTool("get_balances", { title: "Wallet balances", description: "Shows the agent wallet's balances of the coins it can pay with, on NEAR and Base." }, async () => {
+        try {
+            return json(await agent.balances());
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.registerTool("get_spending", { title: "Spending and limits", description: "Shows the spending limits, the amount spent in the last 24 hours, and recent payments." }, async () => {
+        try {
+            return json(await agent.spending());
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.registerTool("set_limits", {
+        title: "Change spending limits",
+        description: "Lowers the per-payment or daily USD limit, or narrows the list of hosts the agent may pay. Limits cannot be raised above the values the server was started with.",
+        inputSchema: z.object({
+            per_payment_usd: z.number().min(0).optional(),
+            daily_usd: z.number().min(0).optional(),
+            allow: z.array(z.string().min(1)).optional().describe("Hosts the agent may request and pay, such as api.example.com or *.example.com."),
+        }),
+    }, async ({ per_payment_usd, daily_usd, allow }) => {
+        try {
+            const current = agent.limits();
+            const requested = {
+                ...(per_payment_usd !== undefined ? { perPaymentUsd: per_payment_usd } : {}),
+                ...(daily_usd !== undefined ? { dailyUsd: daily_usd } : {}),
+                ...(allow !== undefined ? { allow } : {}),
+            };
+            return json({ limits: agent.setLimits(limitsWithinCeiling(current, requested, options.ceiling)) });
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    return server;
+}
+/** Serves the agent wallet as an MCP server over stdin and stdout. */
+export function serveAgentMcp(agent, options) {
+    return serveStdio(() => buildServer(agent, options), { onerror: (error) => process.stderr.write(`[solverr-agent] ${errorSummary(error)}\n`) });
+}

package/dist/payer.d.ts

@@ -0,0 +1,28 @@
+import type { WalletAsset } from "./assets.js";
+import type { ChainWallet } from "./chains/chain-wallet.js";
+import type { SolverrChallenge } from "./challenge.js";
+import type { GatewayClient } from "./gateway.js";
+import { type SpendingLimits } from "./limits.js";
+import type { SpendLog } from "./spend-log.js";
+interface PayerOptions {
+    wallets: readonly ChainWallet[];
+    assets: readonly WalletAsset[];
+    spendLog: SpendLog;
+    gateway: GatewayClient;
+    limits: () => SpendingLimits;
+    paymentTimeoutMs: number;
+}
+/** Pays `solverr` invoices one at a time: limits, coin choice, quote checks, transfer, and confirmation. */
+export declare class Payer {
+    private readonly options;
+    private queue;
+    constructor(options: PayerOptions);
+    /** Pays the invoice in `challenge`, one payment at a time so limit checks never race.
+        An aborted `signal` stops the payment at any step before the transfer; once the transfer starts it is not stopped. */
+    pay(resourceUrl: URL, challenge: SolverrChallenge, signal?: AbortSignal): Promise<void>;
+    private payInvoice;
+    /** Mirrors `changes` on `entry` before saving, so the error path knows funds left even when the write fails. */
+    private record;
+    private transferAndConfirm;
+}
+export {};

package/dist/payer.js

@@ -0,0 +1,157 @@
+import { SolverrApiError } from "solverr-x402";
+import { formatUnits } from "viem";
+import { rankPaymentOptions } from "./coin-selection.js";
+import { MAX_QUOTE_ATTEMPTS, MAX_QUOTE_OVER_ESTIMATE, MIN_QUOTE_VALIDITY_MS, STATUS_POLL_INTERVAL_MS } from "./config.js";
+import { PaymentError, errorSummary } from "./errors.js";
+import { assertHostAllowed, enforceLimits } from "./limits.js";
+import { sleep } from "./timeout.js";
+/** Invoice states the agent's own quote ending sets, after which waiting cannot lead to `paid`. `expired` is not one:
+    a deposit sent near the deadline still moves the invoice to `detected` and then `paid`. */
+const FAILED_INVOICE_STATES = new Set(["underpaid", "refunded", "failed"]);
+/** Allowance for rounding in the USD comparison of a quote against its estimate. */
+const QUOTE_TOLERANCE_USD = 0.01;
+/** Pays `solverr` invoices one at a time: limits, coin choice, quote checks, transfer, and confirmation. */
+export class Payer {
+    options;
+    queue = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+    }
+    /** Pays the invoice in `challenge`, one payment at a time so limit checks never race.
+        An aborted `signal` stops the payment at any step before the transfer; once the transfer starts it is not stopped. */
+    pay(resourceUrl, challenge, signal) {
+        const run = () => this.payInvoice(resourceUrl, challenge, signal);
+        const result = this.queue.then(run, run);
+        this.queue = result.catch(() => undefined);
+        return result;
+    }
+    async payInvoice(resourceUrl, challenge, signal) {
+        const { extra } = challenge;
+        const { spendLog, gateway } = this.options;
+        const hostname = resourceUrl.hostname;
+        signal?.throwIfAborted();
+        assertHostAllowed(this.options.limits(), hostname);
+        if (extra.mode !== "live") {
+            throw new PaymentError("test_invoice", "This is a test invoice. Test invoices come from the Solverr demo store and cannot be paid on-chain.");
+        }
+        if (Date.parse(extra.expires_at) - Date.now() < MIN_QUOTE_VALIDITY_MS)
+            throw new PaymentError("invoice_expired", "The invoice expires too soon to pay safely.");
+        const tokens = await gateway.listTokens(challenge.tokensUrl);
+        const settlementToken = tokens.find((token) => token.asset_id === extra.settlement.asset_id);
+        if (!settlementToken?.price_usd)
+            throw new PaymentError("invalid_challenge", "The invoice's settlement coin has no price from the gateway.");
+        const settlementUsd = Number(extra.settlement.amount) * settlementToken.price_usd;
+        const amountUsd = extra.currency === "USD" ? Math.max(settlementUsd, Number(extra.price)) : settlementUsd;
+        if (!Number.isFinite(amountUsd) || amountUsd <= 0)
+            throw new PaymentError("invalid_challenge", "The invoice amount is not valid.");
+        const entry = await spendLog.reserve({ url: resourceUrl.toString(), host: hostname, invoice_id: extra.invoice_id, amount_usd: amountUsd, status: "reserved" }, (spentLast24hUsd) => enforceLimits(this.options.limits(), { hostname, amountUsd, spentLast24hUsd }));
+        try {
+            const { options, skipped } = await rankPaymentOptions({ wallets: this.options.wallets, assets: this.options.assets, tokens, settlement: extra.settlement, amountUsd });
+            if (options.length === 0) {
+                throw new PaymentError("no_funds", `No coin in this wallet covers about $${amountUsd.toFixed(2)}.${skipped.length ? ` Checked: ${skipped.join("; ")}.` : ""}`);
+            }
+            const refusals = [];
+            for (const option of options.slice(0, MAX_QUOTE_ATTEMPTS)) {
+                signal?.throwIfAborted();
+                let quote;
+                try {
+                    quote = await gateway.requestQuote(extra.quote_url, option.asset.asset_id, option.wallet.address);
+                }
+                catch (error) {
+                    if (error instanceof SolverrApiError && error.status === 422) {
+                        refusals.push(`${option.asset.symbol} on ${option.asset.blockchain}: ${error.message}`);
+                        continue;
+                    }
+                    throw error;
+                }
+                const { amount, quotedUsd } = verifyQuote(quote, option, amountUsd);
+                await this.record(entry, { amount_usd: quotedUsd, asset_id: option.asset.asset_id, blockchain: option.asset.blockchain, amount_base: amount.toString() }, (spentLast24hUsd) => enforceLimits(this.options.limits(), { hostname, amountUsd: quotedUsd, spentLast24hUsd }));
+                signal?.throwIfAborted();
+                return await this.transferAndConfirm(entry, option, quote, amount, challenge);
+            }
+            throw new PaymentError("quote_unavailable", `No quote was available. ${refusals.join(" ")}`.trim());
+        }
+        catch (error) {
+            const fundsSent = entry.status !== "reserved" || (error instanceof PaymentError && error.fundsSent);
+            if (entry.status === "reserved") {
+                /** A failed write leaves the entry reserved, which still counts toward the daily limit. */
+                await this.record(entry, { status: fundsSent ? "failed" : "aborted", error: errorSummary(error) }).catch(() => undefined);
+            }
+            throw fundsSent ? sentPaymentError(error, extra.invoice_id) : error;
+        }
+    }
+    /** Mirrors `changes` on `entry` before saving, so the error path knows funds left even when the write fails. */
+    async record(entry, changes, check) {
+        Object.assign(entry, changes);
+        await this.options.spendLog.update(entry.id, changes, check);
+    }
+    async transferAndConfirm(entry, option, quote, amount, challenge) {
+        const { gateway } = this.options;
+        const { extra } = challenge;
+        const transfer = await option.wallet.transfer(option.asset, quote.deposit_address, amount);
+        /** From here on the entry counts toward the daily limit whatever its saved status, so a failed write does not stop the payment. */
+        await this.record(entry, { status: "sent", tx_hash: transfer.hash }).catch(() => undefined);
+        try {
+            await gateway.reportDeposit(extra.deposit_url, transfer.hash, quote.id);
+        }
+        catch {
+            /** Reporting only speeds up detection; the gateway also watches the deposit address. */
+        }
+        const deadline = Date.now() + this.options.paymentTimeoutMs;
+        let lastStatus = "unknown";
+        while (Date.now() < deadline) {
+            try {
+                lastStatus = (await gateway.getStatus(extra.status_url)).status;
+            }
+            catch (error) {
+                if (!(error instanceof SolverrApiError))
+                    throw error;
+            }
+            if (lastStatus === "paid") {
+                await this.record(entry, { status: "paid" }).catch(() => undefined);
+                return;
+            }
+            if (FAILED_INVOICE_STATES.has(lastStatus)) {
+                await this.record(entry, { status: "failed", error: `Invoice ${lastStatus}` }).catch(() => undefined);
+                throw new PaymentError("payment_failed", `Sent ${transfer.hash}, but the invoice is ${lastStatus}. Any refund goes to ${option.wallet.address}.`, true, extra.invoice_id);
+            }
+            await sleep(STATUS_POLL_INTERVAL_MS);
+        }
+        throw new PaymentError("payment_timeout", `Sent ${transfer.hash}, but invoice ${extra.invoice_id} was still "${lastStatus}" after ${Math.round(this.options.paymentTimeoutMs / 1000)} s. Check ${extra.status_url} before paying again.`, true, extra.invoice_id);
+    }
+}
+/** The error for a payment whose funds may have left the wallet, carrying the invoice ID so the caller never pays it twice. */
+function sentPaymentError(error, invoiceId) {
+    if (error instanceof PaymentError && error.fundsSent)
+        return new PaymentError(error.code, error.message, true, invoiceId);
+    return new PaymentError("payment_unconfirmed", `Funds were sent for invoice ${invoiceId}, but the payment could not be confirmed: ${errorSummary(error)}`, true, invoiceId);
+}
+/** Checks a quote against the chosen coin, the wallet and the estimate before any funds move; returns the exact amount and its USD value. */
+function verifyQuote(quote, option, estimateUsd) {
+    const mismatch = (reason) => new PaymentError("quote_mismatch", `The quote was refused: ${reason}.`);
+    if (quote.deposit_address?.startsWith("TEST-")) {
+        throw new PaymentError("test_invoice", "This invoice uses a test deposit address. Test invoices cannot be paid on-chain.");
+    }
+    if (quote.coin?.asset_id !== option.asset.asset_id)
+        throw mismatch("it is for a different coin");
+    if (quote.refund_address?.toLowerCase() !== option.wallet.address.toLowerCase())
+        throw mismatch("its refund address is not this wallet");
+    if (!option.wallet.isValidRecipient(quote.deposit_address))
+        throw mismatch(`the deposit address is not a valid ${option.asset.blockchain} address`);
+    if (quote.deposit_memo)
+        throw mismatch("it needs a memo, which this wallet cannot attach");
+    if (!/^\d{1,78}$/.test(quote.amount_in_base ?? ""))
+        throw mismatch("its amount is malformed");
+    const amount = BigInt(quote.amount_in_base);
+    if (amount <= 0n)
+        throw mismatch("its amount is zero");
+    if (amount > option.balance)
+        throw new PaymentError("no_funds", `The quote needs ${quote.amount_in} ${option.asset.symbol}, more than this wallet holds.`);
+    if (Date.parse(quote.deadline) - Date.now() < MIN_QUOTE_VALIDITY_MS)
+        throw mismatch("it expires too soon");
+    const quotedUsd = Number(formatUnits(amount, option.asset.decimals)) * option.priceUsd;
+    if (quotedUsd > estimateUsd * (1 + MAX_QUOTE_OVER_ESTIMATE) + QUOTE_TOLERANCE_USD) {
+        throw mismatch(`it costs about $${quotedUsd.toFixed(4)}, far above the expected $${estimateUsd.toFixed(4)}`);
+    }
+    return { amount, quotedUsd };
+}

package/dist/spend-log.d.ts

@@ -0,0 +1,38 @@
+/** `reserved`: limits checked, nothing sent. `sent`: transfer broadcast. `paid`: invoice paid.
+    `failed`: funds were sent but the invoice was not paid. `aborted`: stopped before any transfer. */
+export type SpendStatus = "reserved" | "sent" | "paid" | "failed" | "aborted";
+export interface SpendEntry {
+    id: string;
+    created_at: string;
+    url: string;
+    host: string;
+    invoice_id: string;
+    amount_usd: number;
+    status: SpendStatus;
+    asset_id?: string;
+    blockchain?: string;
+    amount_base?: string;
+    tx_hash?: string;
+    error?: string;
+}
+export type SpendChanges = Partial<Omit<SpendEntry, "id" | "created_at">>;
+/** Throws to refuse a write; receives the USD counted over the last 24 hours, excluding the entry being written. */
+export type SpendCheck = (spentLast24hUsd: number) => void;
+/** Local JSON record of payments that enforces the rolling 24-hour limit across restarts and processes.
+    Every write re-reads the file under an exclusive lock file, so agents sharing one log never overwrite each other. */
+export declare class SpendLog {
+    readonly path: string;
+    constructor(path?: string);
+    /** Reads the file; a missing file is an empty log, a corrupt one is an error so limits are never reset silently. */
+    entries(): Promise<SpendEntry[]>;
+    /** USD counted toward the daily limit over the last 24 hours. */
+    spentLast24hUsd(): Promise<number>;
+    /** Runs `check` against the current total and adds the entry in one locked step, so two processes cannot both pass the limit. */
+    reserve(entry: Omit<SpendEntry, "id" | "created_at">, check: SpendCheck): Promise<SpendEntry>;
+    /** Applies `changes` to entry `id`, after `check` passes against the total of all other entries. */
+    update(id: string, changes: SpendChanges, check?: SpendCheck): Promise<SpendEntry>;
+    /** Holds `${path}.lock` (created with `wx`, holding a random token) while `run` reads and writes the log. */
+    private withLock;
+    /** Writes to a temporary file and renames it, so a crash never leaves a half-written log. */
+    private save;
+}

package/dist/spend-log.js

@@ -0,0 +1,162 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DAY_MS, SPEND_LOG_LOCK_RETRY_MS, SPEND_LOG_LOCK_TIMEOUT_MS, SPEND_LOG_RETENTION_MS, SPEND_LOG_STALE_LOCK_MS } from "./config.js";
+import { sleep } from "./timeout.js";
+const DEFAULT_SPEND_LOG_PATH = join(homedir(), ".solverr", "agent-spend-log.json");
+/** Every status except `aborted` counts toward the daily limit, since funds may have left the wallet. */
+const counts = (entry) => entry.status !== "aborted";
+function spentLast24h(entries, exceptId) {
+    const since = Date.now() - DAY_MS;
+    return entries
+        .filter((entry) => entry.id !== exceptId && counts(entry) && Date.parse(entry.created_at) >= since)
+        .reduce((sum, entry) => sum + entry.amount_usd, 0);
+}
+/** On Windows a lock file that is being deleted refuses to open with EPERM, which means the same as EEXIST here. */
+const isLockBusy = (error) => {
+    const code = error.code;
+    return code === "EEXIST" || (code === "EPERM" && process.platform === "win32");
+};
+/** Reads the lock file's token and whether it is older than the stale limit; `undefined` when there is no lock. */
+async function readLock(lockPath) {
+    try {
+        const [{ mtimeMs }, token] = await Promise.all([stat(lockPath), readFile(lockPath, "utf8")]);
+        return { token, stale: Date.now() - mtimeMs >= SPEND_LOG_STALE_LOCK_MS };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        if (isLockBusy(error))
+            return { token: "", stale: false };
+        throw error;
+    }
+}
+/** Removes a stale lock file and returns whether it may now be free. Only the waiter that creates this token's takeover file
+    removes it, after reading the lock again, so a fresh lock another waiter took meanwhile is never deleted. */
+async function removeStaleLock(lockPath) {
+    const lock = await readLock(lockPath);
+    if (!lock)
+        return true;
+    if (!lock.stale)
+        return false;
+    const claimPath = `${lockPath}.${/^[\w-]{1,64}$/.test(lock.token) ? lock.token : "unknown"}.takeover`;
+    let claim;
+    try {
+        claim = await open(claimPath, "wx", 0o600);
+    }
+    catch (error) {
+        if (isLockBusy(error))
+            return false;
+        throw error;
+    }
+    try {
+        const current = await readLock(lockPath);
+        if (current?.stale && current.token === lock.token)
+            await rm(lockPath, { force: true });
+    }
+    finally {
+        await claim.close();
+        await rm(claimPath, { force: true });
+    }
+    return true;
+}
+/** Local JSON record of payments that enforces the rolling 24-hour limit across restarts and processes.
+    Every write re-reads the file under an exclusive lock file, so agents sharing one log never overwrite each other. */
+export class SpendLog {
+    path;
+    constructor(path = DEFAULT_SPEND_LOG_PATH) {
+        this.path = path;
+    }
+    /** Reads the file; a missing file is an empty log, a corrupt one is an error so limits are never reset silently. */
+    async entries() {
+        let text;
+        try {
+            text = await readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            return [];
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = null;
+        }
+        if (parsed?.version !== 1 || !Array.isArray(parsed.entries))
+            throw new Error(`Spend log ${this.path} is not a valid spend log file.`);
+        return parsed.entries;
+    }
+    /** USD counted toward the daily limit over the last 24 hours. */
+    async spentLast24hUsd() {
+        return spentLast24h(await this.entries());
+    }
+    /** Runs `check` against the current total and adds the entry in one locked step, so two processes cannot both pass the limit. */
+    async reserve(entry, check) {
+        return this.withLock(async () => {
+            const entries = await this.entries();
+            check(spentLast24h(entries));
+            const created = { id: randomUUID(), created_at: new Date().toISOString(), ...entry };
+            entries.push(created);
+            await this.save(entries);
+            return created;
+        });
+    }
+    /** Applies `changes` to entry `id`, after `check` passes against the total of all other entries. */
+    async update(id, changes, check) {
+        return this.withLock(async () => {
+            const entries = await this.entries();
+            const entry = entries.find((item) => item.id === id);
+            if (!entry)
+                throw new Error(`Spend log entry ${id} not found.`);
+            check?.(spentLast24h(entries, id));
+            Object.assign(entry, changes);
+            await this.save(entries);
+            return entry;
+        });
+    }
+    /** Holds `${path}.lock` (created with `wx`, holding a random token) while `run` reads and writes the log. */
+    async withLock(run) {
+        const lockPath = `${this.path}.lock`;
+        await mkdir(dirname(this.path), { recursive: true });
+        const deadline = Date.now() + SPEND_LOG_LOCK_TIMEOUT_MS;
+        const token = randomUUID();
+        let lock;
+        while (!lock) {
+            try {
+                lock = await open(lockPath, "wx", 0o600);
+            }
+            catch (error) {
+                if (!isLockBusy(error))
+                    throw error;
+                if (await removeStaleLock(lockPath))
+                    continue;
+                if (Date.now() >= deadline) {
+                    throw new Error(`Spend log ${this.path} stayed locked for ${SPEND_LOG_LOCK_TIMEOUT_MS / 1000} s. If no other agent is running, delete ${lockPath}.`);
+                }
+                await sleep(SPEND_LOG_LOCK_RETRY_MS);
+            }
+        }
+        try {
+            await lock.writeFile(token, "utf8");
+            return await run();
+        }
+        finally {
+            await lock.close();
+            /** A lock taken over after going stale belongs to its new holder and is left in place. */
+            if ((await readLock(lockPath))?.token === token)
+                await rm(lockPath, { force: true });
+        }
+    }
+    /** Writes to a temporary file and renames it, so a crash never leaves a half-written log. */
+    async save(entries) {
+        const cutoff = Date.now() - SPEND_LOG_RETENTION_MS;
+        const file = { version: 1, entries: entries.filter((entry) => Date.parse(entry.created_at) >= cutoff) };
+        const temporary = `${this.path}.${process.pid}.tmp`;
+        await writeFile(temporary, `${JSON.stringify(file, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        await rename(temporary, this.path);
+    }
+}

package/dist/timeout.d.ts

@@ -0,0 +1,7 @@
+/** Error raised when an operation exceeds its time budget. */
+export declare class TimeoutError extends Error {
+    constructor(label: string, ms: number);
+}
+/** Rejects with `TimeoutError` when `promise` does not settle within `ms`; the underlying work is not cancelled. */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
+export declare const sleep: (ms: number) => Promise<unknown>;

package/dist/timeout.js

@@ -0,0 +1,16 @@
+/** Error raised when an operation exceeds its time budget. */
+export class TimeoutError extends Error {
+    constructor(label, ms) {
+        super(`${label} did not finish within ${Math.round(ms / 1000)} s.`);
+        this.name = "TimeoutError";
+    }
+}
+/** Rejects with `TimeoutError` when `promise` does not settle within `ms`; the underlying work is not cancelled. */
+export function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new TimeoutError(label, ms)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/url-guard.d.ts

@@ -0,0 +1,7 @@
+import { Agent } from "undici";
+/** Refuses a host off the allow list or resolving to any private address, unless the URL names that IP or `localhost` and it is allowed exactly.
+    Returns the checked public addresses for `pinnedDispatcher`; empty for an IP or `localhost` allowed exactly, which needs no pinning. */
+export declare function assertFetchAllowed(url: URL, allow: readonly string[]): Promise<string[]>;
+/** Dispatcher that connects only to `addresses`, so a DNS answer changed after `assertFetchAllowed` cannot reach a private network.
+    Undefined when there is nothing to pin; close it once the response body is read. */
+export declare function pinnedDispatcher(addresses: readonly string[]): Agent | undefined;