@nookplot/runtime 0.5.142 → 0.5.143

package/dist/usdcBudget.js

@@ -0,0 +1,155 @@
+/**
+ * UsdcBudget — a hard-stop, rolling-window USDC spend cap for the per-call x402
+ * `pay_api` action.
+ *
+ * A first-class sibling to the goal loop's `budgetNook`, with two deliberate
+ * differences: it is **money-denominated** (USDC base units) and it **enforces**
+ * (`budgetNook` is soft/warn-only — `goalLoop.ts:190`). One tracker per agent
+ * process, hung off `runtime.usdcBudget`, so every `pay_api` dispatch site
+ * (reactive + goal-loop, TS + the Python mirror) shares the SAME ledger and the
+ * cap holds no matter which path spends.
+ *
+ * Enforcement model (zero overshoot):
+ *   1. Before paying, a dispatch site asks `maxForNextCall()` for the largest
+ *      amount this call may spend (min of the per-call ceiling and remaining
+ *      daily headroom). It passes that as `payAndCall`'s `maxAmountBaseUnits`,
+ *      which aborts BEFORE signing if the 402 quote exceeds it.
+ *   2. After a successful pay, the site `record()`s the exact amount.
+ *   3. The goal loop reads `isExhausted()` and terminates with `blocked_budget`
+ *      once the daily cap is fully consumed (the consumer that finally makes the
+ *      `blocked_budget` outcome live — see `goal/types.ts`).
+ *
+ * Amounts are USDC base units (6 decimals): 1 USDC = 1_000_000n.
+ * A `dailyCapBaseUnits` of 0n means "unlimited" (cap disabled); likewise 0n for
+ * the per-call ceiling means "no per-call ceiling".
+ *
+ * @module usdcBudget
+ */
+/** USDC has 6 decimals on Base. */
+export const USDC_DECIMALS = 6;
+const USDC_ONE = 1000000n;
+/** Default daily cap when nothing is configured: $10/day. Conservative
+ *  safety net for a runaway buyer — operators raise it via `X402_DAILY_USDC_CAP`
+ *  (or `dailyCapBaseUnits: 0n` to disable). pay_api is the only consumer, so a
+ *  non-zero default never affects non-buying agents. */
+export const DEFAULT_DAILY_USDC_CAP_BASE_UNITS = 10n * USDC_ONE;
+const WINDOW_MS = 24 * 60 * 60 * 1000;
+/** Parse a USDC display amount ("10", "0.5") into base units. Returns 0n
+ *  (unlimited) for empty / non-positive / unparseable input. */
+export function parseUsdcToBaseUnits(display) {
+    if (!display)
+        return 0n;
+    const trimmed = display.trim();
+    if (!/^\d+(\.\d+)?$/.test(trimmed))
+        return 0n;
+    const [whole, frac = ""] = trimmed.split(".");
+    const fracPadded = (frac + "000000").slice(0, USDC_DECIMALS);
+    return BigInt(whole) * USDC_ONE + BigInt(fracPadded || "0");
+}
+/** Format base units as a `$x.xx` USDC string for log/agent messages. */
+export function formatUsdc(baseUnits) {
+    const whole = baseUnits / USDC_ONE;
+    const frac = (baseUnits % USDC_ONE).toString().padStart(USDC_DECIMALS, "0").replace(/0+$/, "");
+    return frac ? `$${whole}.${frac}` : `$${whole}`;
+}
+export class UsdcBudget {
+    /** Daily cap in USDC base units. 0n = unlimited. */
+    dailyCapBaseUnits;
+    /** Per-call ceiling in USDC base units. 0n = none. */
+    perCallCapBaseUnits;
+    windowMs;
+    now;
+    spentBaseUnits = 0n;
+    windowStartMs;
+    constructor(opts = {}) {
+        this.dailyCapBaseUnits = opts.dailyCapBaseUnits ?? DEFAULT_DAILY_USDC_CAP_BASE_UNITS;
+        this.perCallCapBaseUnits = opts.perCallCapBaseUnits ?? 0n;
+        this.windowMs = opts.windowMs ?? WINDOW_MS;
+        this.now = opts.now ?? (() => Date.now());
+        this.windowStartMs = this.now();
+    }
+    /** Roll the spend window when the current 24h period has elapsed. */
+    roll() {
+        const t = this.now();
+        if (t - this.windowStartMs >= this.windowMs) {
+            this.spentBaseUnits = 0n;
+            this.windowStartMs = t;
+        }
+    }
+    /** Pre-pay check for a known quote. Honors both the per-call ceiling and the
+     *  remaining daily headroom. */
+    check(amountBaseUnits) {
+        this.roll();
+        if (this.perCallCapBaseUnits > 0n && amountBaseUnits > this.perCallCapBaseUnits) {
+            return {
+                allowed: false,
+                reason: `per-call ${formatUsdc(amountBaseUnits)} exceeds the ceiling ${formatUsdc(this.perCallCapBaseUnits)}`,
+                remainingBaseUnits: this.remaining(),
+            };
+        }
+        if (this.dailyCapBaseUnits > 0n && this.spentBaseUnits + amountBaseUnits > this.dailyCapBaseUnits) {
+            return {
+                allowed: false,
+                reason: `daily USDC cap ${formatUsdc(this.dailyCapBaseUnits)} would be exceeded (already spent ${formatUsdc(this.spentBaseUnits)})`,
+                remainingBaseUnits: this.remaining(),
+            };
+        }
+        return { allowed: true, remainingBaseUnits: this.remaining() };
+    }
+    /** The largest amount a single call may spend right now (min of per-call
+     *  ceiling and remaining daily headroom). `undefined` = unlimited. `0n` =
+     *  budget already exhausted (caller should not pay at all). */
+    maxForNextCall() {
+        this.roll();
+        const limits = [];
+        if (this.perCallCapBaseUnits > 0n)
+            limits.push(this.perCallCapBaseUnits);
+        if (this.dailyCapBaseUnits > 0n)
+            limits.push(this.dailyCapBaseUnits - this.spentBaseUnits);
+        if (limits.length === 0)
+            return undefined; // fully unlimited
+        const m = limits.reduce((a, b) => (b < a ? b : a));
+        return m > 0n ? m : 0n;
+    }
+    /** Record a completed spend (call AFTER a successful payment). */
+    record(amountBaseUnits) {
+        this.roll();
+        if (amountBaseUnits > 0n)
+            this.spentBaseUnits += amountBaseUnits;
+    }
+    /** Remaining daily headroom in base units; -1n when unlimited. */
+    remaining() {
+        if (this.dailyCapBaseUnits === 0n)
+            return -1n;
+        this.roll();
+        const r = this.dailyCapBaseUnits - this.spentBaseUnits;
+        return r > 0n ? r : 0n;
+    }
+    /** True when a daily cap is set and fully consumed — the goal loop's
+     *  `blocked_budget` trigger. Always false when unlimited. */
+    isExhausted() {
+        if (this.dailyCapBaseUnits === 0n)
+            return false;
+        this.roll();
+        return this.spentBaseUnits >= this.dailyCapBaseUnits;
+    }
+    /** Spent-so-far in the current window (base units). */
+    get spent() {
+        this.roll();
+        return this.spentBaseUnits;
+    }
+}
+/** Build a UsdcBudget from explicit options falling back to env
+ *  (`X402_DAILY_USDC_CAP`, `X402_PER_CALL_USDC_CAP`, both USDC display units)
+ *  and finally the conservative default daily cap. */
+export function createUsdcBudget(opts = {}) {
+    const env = typeof process !== "undefined" ? process.env : undefined;
+    const dailyCapBaseUnits = opts.dailyCapBaseUnits ??
+        (env?.X402_DAILY_USDC_CAP !== undefined
+            ? parseUsdcToBaseUnits(env.X402_DAILY_USDC_CAP)
+            : DEFAULT_DAILY_USDC_CAP_BASE_UNITS);
+    const perCallCapBaseUnits = opts.perCallCapBaseUnits ??
+        (env?.X402_PER_CALL_USDC_CAP !== undefined ? parseUsdcToBaseUnits(env.X402_PER_CALL_USDC_CAP) : 0n);
+    return new UsdcBudget({ ...opts, dailyCapBaseUnits, perCallCapBaseUnits });
+}
+//# sourceMappingURL=usdcBudget.js.map

package/dist/usdcBudget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usdcBudget.js","sourceRoot":"","sources":["../src/usdcBudget.ts"],"names":[],"mappings":"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"}

package/dist/x402.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Optional convenience wrapper for paying marketplace API listings per-call via
+ * x402 (ROADMAP_x402-marketplace-fees.md v2). This is NOT required — any standard
+ * x402 client (Base MCP, x402-axios, x402-py) can pay a Nookplot listing because
+ * the gateway speaks the standard `"exact"` scheme. This wrapper just removes the
+ * boilerplate for agents already holding an ethers signer.
+ *
+ * Unlike the agreement-based {@link ApiMarketplaceManager.proxyRequest}, the x402
+ * path is **accountless**: there is no gateway API key and no on-chain agreement.
+ * The buyer's per-call EIP-3009 USDC authorization IS the payment + the auth.
+ *
+ * Flow:
+ *   1. Probe `GET/POST /v1/api-x402/:listingId/*` with no payment → HTTP 402 +
+ *      the `accepts[]` challenge (splitter `payTo`, USDC `asset`, price).
+ *   2. Sign an EIP-3009 `ReceiveWithAuthorization` over the advertised amount.
+ *   3. Re-send the request with the encoded payment header → upstream response.
+ *
+ * v2.0 accepts USDC only, so the token's EIP-712 domain is the USDC default
+ * ("USD Coin" / "2"). NOOK (a different domain) is deferred to v2.1.
+ *
+ * @module x402
+ */
+import { ethers } from "ethers";
+export interface X402PayAndCallInput {
+    /** On-chain listing id. */
+    listingId: number | string;
+    /** Upstream path after the listing id (e.g. "chat/completions"). */
+    path: string;
+    /** HTTP method. Default "GET". */
+    method?: string;
+    /** JSON request body (serialized for non-GET/HEAD). */
+    body?: unknown;
+    /** Extra request headers passed through to the upstream. */
+    headers?: Record<string, string>;
+    /** Hard per-call ceiling in USDC base units. When set, `payAndCall` throws
+     *  BEFORE signing if the 402-quoted `maxAmountRequired` exceeds it. The
+     *  `pay_api` dispatch sites pass `runtime.usdcBudget.maxForNextCall()` here so
+     *  the spend cap is enforced at the point of payment. */
+    maxAmountBaseUnits?: bigint;
+}
+export interface X402PayAndCallResult {
+    status: number;
+    headers: Record<string, string>;
+    /** Parsed JSON when possible, else raw text. */
+    body: unknown;
+    /** True when a payment was signed + submitted; false when the gateway
+     *  short-circuited before payment (e.g. listing unavailable). */
+    paid: boolean;
+    /** USDC base units actually authorized when `paid` is true (the 402
+     *  `maxAmountRequired`). Lets the caller record the spend against a budget. */
+    amountPaidBaseUnits?: string;
+}
+export interface X402ManagerOptions {
+    /** Override the EIP-712 chain id (else derived from the 402 `network`). */
+    chainId?: number;
+}
+export declare class X402Manager {
+    private readonly gatewayUrl;
+    private readonly chainIdOverride?;
+    constructor(gatewayUrl: string, opts?: X402ManagerOptions);
+    /**
+     * Pay for and make a single metered call to a marketplace API listing.
+     *
+     * @param input  The listing + upstream request.
+     * @param signer An ethers signer holding the buyer's USDC (e.g. `new ethers.Wallet(pk)`).
+     */
+    payAndCall(input: X402PayAndCallInput, signer: ethers.Signer): Promise<X402PayAndCallResult>;
+}
+//# sourceMappingURL=x402.d.ts.map

package/dist/x402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAgBhC,MAAM,WAAW,mBAAmB;IAClC,2BAA2B;IAC3B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;6DAGyD;IACzD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,gDAAgD;IAChD,IAAI,EAAE,OAAO,CAAC;IACd;qEACiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd;mFAC+E;IAC/E,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAYD,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAS;gBAE9B,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB;IAK7D;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAiEnG"}

package/dist/x402.js

@@ -0,0 +1,139 @@
+/**
+ * Optional convenience wrapper for paying marketplace API listings per-call via
+ * x402 (ROADMAP_x402-marketplace-fees.md v2). This is NOT required — any standard
+ * x402 client (Base MCP, x402-axios, x402-py) can pay a Nookplot listing because
+ * the gateway speaks the standard `"exact"` scheme. This wrapper just removes the
+ * boilerplate for agents already holding an ethers signer.
+ *
+ * Unlike the agreement-based {@link ApiMarketplaceManager.proxyRequest}, the x402
+ * path is **accountless**: there is no gateway API key and no on-chain agreement.
+ * The buyer's per-call EIP-3009 USDC authorization IS the payment + the auth.
+ *
+ * Flow:
+ *   1. Probe `GET/POST /v1/api-x402/:listingId/*` with no payment → HTTP 402 +
+ *      the `accepts[]` challenge (splitter `payTo`, USDC `asset`, price).
+ *   2. Sign an EIP-3009 `ReceiveWithAuthorization` over the advertised amount.
+ *   3. Re-send the request with the encoded payment header → upstream response.
+ *
+ * v2.0 accepts USDC only, so the token's EIP-712 domain is the USDC default
+ * ("USD Coin" / "2"). NOOK (a different domain) is deferred to v2.1.
+ *
+ * @module x402
+ */
+import { ethers } from "ethers";
+/** EIP-3009 ReceiveWithAuthorization typed-data fields (USDC FiatTokenV2). */
+const RECEIVE_WITH_AUTHORIZATION_TYPES = {
+    ReceiveWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+    ],
+};
+const DEFAULT_TIMEOUT_SECONDS = 600;
+export class X402Manager {
+    gatewayUrl;
+    chainIdOverride;
+    constructor(gatewayUrl, opts = {}) {
+        this.gatewayUrl = gatewayUrl.replace(/\/+$/, "");
+        this.chainIdOverride = opts.chainId;
+    }
+    /**
+     * Pay for and make a single metered call to a marketplace API listing.
+     *
+     * @param input  The listing + upstream request.
+     * @param signer An ethers signer holding the buyer's USDC (e.g. `new ethers.Wallet(pk)`).
+     */
+    async payAndCall(input, signer) {
+        const method = (input.method ?? "GET").toUpperCase();
+        const path = String(input.path).replace(/^\/+/, "");
+        const url = `${this.gatewayUrl}/v1/api-x402/${input.listingId}/${path}`;
+        const bodyStr = input.body !== undefined ? JSON.stringify(input.body) : "";
+        const makeInit = (extraHeaders) => {
+            const headers = {
+                "Content-Type": "application/json",
+                ...input.headers,
+                ...extraHeaders,
+            };
+            const init = { method, headers };
+            if (bodyStr && !["GET", "HEAD"].includes(method))
+                init.body = bodyStr;
+            return init;
+        };
+        // 1. Probe — the gateway answers 402 with the payment challenge.
+        const probe = await fetch(url, makeInit());
+        if (probe.status !== 402) {
+            return toResult(probe, false);
+        }
+        const challenge = (await probe.json());
+        const accept = challenge.accepts?.[0];
+        if (!accept || accept.scheme !== "exact") {
+            throw new Error("x402: gateway did not offer a supported 'exact' payment option");
+        }
+        // Hard spend guard — refuse BEFORE signing if the quoted price exceeds the
+        // caller's per-call ceiling (the budgetUsdc cap). No funds move.
+        if (input.maxAmountBaseUnits !== undefined) {
+            const quote = BigInt(accept.maxAmountRequired);
+            if (quote > input.maxAmountBaseUnits) {
+                throw new Error(`x402 spend blocked: quoted ${quote} base units exceeds the allowed ${input.maxAmountBaseUnits} for this call (USDC spend cap)`);
+            }
+        }
+        // 2. Sign the EIP-3009 authorization over the advertised amount.
+        const from = await signer.getAddress();
+        const chainId = this.chainIdOverride ?? parseChainId(accept.network);
+        const nowSec = Math.floor(Date.now() / 1000);
+        const authorization = {
+            from,
+            to: accept.payTo,
+            value: accept.maxAmountRequired,
+            validAfter: 0,
+            validBefore: nowSec + (accept.maxTimeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS),
+            nonce: ethers.hexlify(ethers.randomBytes(32)),
+        };
+        const domain = {
+            name: accept.extra?.eip712?.name ?? "USD Coin",
+            version: accept.extra?.eip712?.version ?? "2",
+            chainId,
+            verifyingContract: accept.asset,
+        };
+        const signature = await signer.signTypedData(domain, RECEIVE_WITH_AUTHORIZATION_TYPES, authorization);
+        // 3. Re-send with the encoded payment header.
+        const header = encodePaymentHeader({ payload: { authorization, signature } });
+        const paid = await fetch(url, makeInit({ "PAYMENT-SIGNATURE": header }));
+        return toResult(paid, true, accept.maxAmountRequired);
+    }
+}
+function parseChainId(network) {
+    const m = /^eip155:(\d+)$/.exec(network);
+    if (m)
+        return Number(m[1]);
+    if (network === "base")
+        return 8453;
+    if (network === "base-sepolia")
+        return 84532;
+    throw new Error(`x402: unsupported network "${network}"`);
+}
+function encodePaymentHeader(payload) {
+    const json = JSON.stringify(payload);
+    return typeof Buffer !== "undefined"
+        ? Buffer.from(json, "utf8").toString("base64")
+        : btoa(json);
+}
+async function toResult(res, paid, amountPaidBaseUnits) {
+    const text = await res.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = text;
+    }
+    const headers = {};
+    res.headers.forEach((val, key) => {
+        headers[key] = val;
+    });
+    return { status: res.status, headers, body, paid, ...(paid ? { amountPaidBaseUnits } : {}) };
+}
+//# sourceMappingURL=x402.js.map

package/dist/x402.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.js","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nookplot/runtime",
-  "version": "0.5.142",
-  "description": "Agent Runtime SDK — persistent connection, events, memory bridge, and economy for AI agents on Nookplot",
+  "version": "0.5.143",
+  "description": "Agent Runtime SDK — persistent connection, events, memory bridge, and economy for AI agents on Nookplot",
   "author": "nookplot",
   "type": "module",
   "main": "dist/index.js",

package/dist/__tests__/economy.frontierInference.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=economy.frontierInference.test.d.ts.map

package/dist/__tests__/economy.frontierInference.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"economy.frontierInference.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/economy.frontierInference.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/economy.frontierInference.test.js

@@ -1,61 +0,0 @@
-/**
- * EconomyManager.frontierInference() — the one-shot frontier (Surplus) call that
- * backs the `use_frontier_model` autonomous action (spends an owner-reserved
- * pass). Contract:
- *   1. ALWAYS routes to Surplus regardless of the configured default source.
- *   2. Returns `costUsdcMicros` = the spend-tracker delta for this call (so the
- *      caller can finalize the reserved pass with the real settled spend).
- *   3. Throws a keyless SurplusError (no network) when there's no private key.
- *
- * `surplusInference` is mocked here so the test doesn't require the optional
- * x402/viem peers (the real-client path is covered by economy.surplusBranch).
- */
-import { describe, it, expect, vi, beforeEach } from "vitest";
-vi.mock("../inference/surplusInference.js", async (importOriginal) => {
-    const actual = await importOriginal();
-    return {
-        ...actual,
-        // Simulate an x402 spend of $0.042 by bumping the shared tracker, and echo
-        // the requested model so we can assert the override took effect.
-        surplusInference: vi.fn(async (params) => {
-            if (params.tracker)
-                params.tracker.spentBaseUnits += 42000n;
-            return {
-                content: "frontier says hi",
-                model: params.options?.model ?? "unknown",
-                provider: "surplus",
-                usage: { promptTokens: 1, completionTokens: 1, totalTokens: 2, creditsCost: 0 },
-            };
-        }),
-    };
-});
-const { ConnectionManager } = await import("../connection.js");
-const { EconomyManager } = await import("../economy.js");
-const surplusMod = await import("../inference/surplusInference.js");
-const TEST_PK = "0x" + "ab".repeat(32);
-const TEST_BASE = "https://gateway.example.com";
-const MSGS = [{ role: "user", content: "Prove the theorem." }];
-beforeEach(() => vi.clearAllMocks());
-describe("EconomyManager.frontierInference()", () => {
-    it("routes to Surplus even when the default source is platform, and returns the cost delta", async () => {
-        const economy = new EconomyManager(new ConnectionManager({
-            gatewayUrl: TEST_BASE,
-            apiKey: "nk_test",
-            privateKey: TEST_PK,
-            inferenceSource: "platform", // default — frontierInference overrides to Surplus
-            surplus: { model: "llama-3.3-70b" },
-        }));
-        const result = await economy.frontierInference(MSGS, { model: "claude-opus-4.8" });
-        expect(surplusMod.surplusInference).toHaveBeenCalledTimes(1);
-        expect(result.provider).toBe("surplus");
-        expect(result.content).toBe("frontier says hi");
-        expect(result.model).toBe("claude-opus-4.8"); // the per-call override won
-        expect(result.costUsdcMicros).toBe(42_000); // tracker delta, 6-dec base units
-    });
-    it("throws keyless (no surplus call) when there is no private key", async () => {
-        const economy = new EconomyManager(new ConnectionManager({ gatewayUrl: TEST_BASE, apiKey: "nk_test" }));
-        await expect(economy.frontierInference(MSGS, { model: "claude-opus-4.8" })).rejects.toMatchObject({ code: "keyless" });
-        expect(surplusMod.surplusInference).not.toHaveBeenCalled();
-    });
-});
-//# sourceMappingURL=economy.frontierInference.test.js.map

package/dist/__tests__/economy.frontierInference.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"economy.frontierInference.test.js","sourceRoot":"","sources":["../../src/__tests__/economy.frontierInference.test.ts"],"names":[],"mappings":"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"}

package/dist/frontierPass.d.ts

@@ -1,30 +0,0 @@
-/**
- * Shared `use_frontier_model` executor — used by BOTH the runtime's autonomous
- * loop (autonomous.ts) and the CLI dispatcher (agentLoop.ts), which have
- * parallel action-dispatch paths. Keeping the logic here prevents the two from
- * drifting on a money path.
- *
- * Flow (client-executed, non-custodial — the gateway can't run this):
- *   1. consume — claim ONE owner-reserved pass (gateway enforces reserved count
- *      + rolling daily cap; a 409/429 surfaces as a thrown request error).
- *   2. run — one-shot Surplus completion paid by the agent's OWN client-signed
- *      x402 key (economy.frontierInference).
- *   3. finalize — record the real settled spend; OR revert the pass to
- *      'reserved' on failure so it isn't wasted.
- *
- * @module frontierPass
- */
-import type { ConnectionManager } from "./connection.js";
-import type { EconomyManager } from "./economy.js";
-export interface FrontierPassResult {
-    ok?: boolean;
-    model?: string;
-    answer?: string;
-    spent_usdc?: string;
-    error?: string;
-    message?: string;
-    /** Loose result object the agent reads as a tool result. */
-    [key: string]: unknown;
-}
-export declare function runFrontierPass(connection: ConnectionManager, economy: EconomyManager, args: Record<string, unknown>, agentAddress?: string): Promise<FrontierPassResult>;
-//# sourceMappingURL=frontierPass.d.ts.map

package/dist/frontierPass.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"frontierPass.d.ts","sourceRoot":"","sources":["../src/frontierPass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,iBAAiB,EAC7B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAyC7B"}

package/dist/frontierPass.js

@@ -1,42 +0,0 @@
-export async function runFrontierPass(connection, economy, args, agentAddress) {
-    const model = String(args.model ?? "").trim();
-    const task = String(args.task ?? "").trim();
-    const reason = typeof args.reason === "string" ? args.reason.slice(0, 280) : undefined;
-    if (!model)
-        return { error: "bad_model", message: "Pass a `model` (a Surplus model id)." };
-    if (!task)
-        return { error: "bad_task", message: "Pass the `task` — the full self-contained prompt for the frontier model." };
-    if (!agentAddress)
-        return { error: "frontier_unavailable", message: "Agent address unknown — cannot consume a pass." };
-    // 1. Claim a reserved pass.
-    let claim;
-    try {
-        claim = await connection.request("POST", `/v1/agents/${agentAddress}/inference-passes/consume`, { model, reason });
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-            error: "no_reserved_pass",
-            message: `Couldn't claim a ${model} pass: ${msg}. Ask your owner to reserve passes in the agent's vault.`,
-        };
-    }
-    // 2. Run the one-shot frontier completion (client-signed x402, own USDC).
-    try {
-        const out = await economy.frontierInference([{ role: "user", content: task }], { model });
-        const costUsdcMicros = Number.isFinite(out.costUsdcMicros) ? out.costUsdcMicros : 0;
-        // 3. Record the settled spend (best-effort — the inference already happened).
-        await connection
-            .request("POST", `/v1/agents/${agentAddress}/inference-passes/${claim.passId}/finalize`, { costUsdcMicros })
-            .catch(() => { });
-        return { ok: true, model, answer: out.content ?? "", spent_usdc: (costUsdcMicros / 1e6).toFixed(6) };
-    }
-    catch (err) {
-        // x402 declined / timed out / provider error → return the pass to 'reserved'.
-        await connection
-            .request("POST", `/v1/agents/${agentAddress}/inference-passes/${claim.passId}/revert`, {})
-            .catch(() => { });
-        const msg = err instanceof Error ? err.message : String(err);
-        return { error: "frontier_call_failed", message: `Frontier call failed (your pass was NOT spent): ${msg}` };
-    }
-}
-//# sourceMappingURL=frontierPass.js.map

package/dist/frontierPass.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"frontierPass.js","sourceRoot":"","sources":["../src/frontierPass.ts"],"names":[],"mappings":"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"}