@jinn-network/client 0.1.7-canary.d4e4e183 → 0.1.7-canary.f3c8e0db

package/dist/preflight/rpc-network.js

@@ -1,5 +1,6 @@
-import { createPublicClient, http } from 'viem';
+import { createPublicClient, http, HttpRequestError } from 'viem';
 import { base, baseSepolia } from 'viem/chains';
+import { describeFallbackChain, maskRpcHost } from '../rpc/transport.js';
 export function expectedChainIdForNetwork(network) {
     return network === 'testnet' ? 84532 : 8453;
 }
@@ -118,4 +119,69 @@ export function rpcNetworkFailureHint(result) {
     }
     return 'Set rpcUrl to a Base mainnet endpoint such as https://mainnet.base.org, or set BASE_RPC_URL.';
 }
+function classifyProbeError(host, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof HttpRequestError && typeof err.status === 'number') {
+        return { ok: false, host, code: err.status, message };
+    }
+    // viem wraps HTTP errors inside other shapes; walk the cause chain.
+    let cur = err?.cause;
+    while (cur) {
+        if (cur instanceof HttpRequestError && typeof cur.status === 'number') {
+            return { ok: false, host, code: cur.status, message };
+        }
+        cur = cur.cause;
+    }
+    return { ok: false, host, reason: 'unreachable', message };
+}
+/**
+ * Probe each URL in a fallback chain with a per-slot `eth_blockNumber` call.
+ * Records ok/latency or a structured failure (HTTP status / unreachable).
+ *
+ * The probe is **log-only** — it never throws on per-slot failures. Startup
+ * gating remains the job of {@link checkRpcNetwork}, which fails loud on
+ * chain-id mismatch.
+ *
+ * Per AC9 (issue #592): emits one log line per slot
+ *   `[rpc] <layer> <host> ok latency=Nms`
+ *   `[rpc] <layer> <host> warn <http-status>`     (e.g. 429, 503)
+ *   `[rpc] <layer> <host> warn unreachable: <message>`
+ */
+export async function probeFallbackChain(urls, network, layer, options = {}) {
+    const log = options.log ?? ((m) => process.stderr.write(`${m}\n`));
+    // Chain is informational only — eth_blockNumber doesn't depend on chain
+    // identity. Both L1 and L2 layers reuse the same Base/Base-Sepolia pair
+    // since this is just used to satisfy viem's typing.
+    const chain = network === 'testnet' ? baseSepolia : base;
+    const results = [];
+    for (const url of urls) {
+        const host = maskRpcHost(url);
+        const client = createPublicClient({ chain, transport: http(url, { retryCount: 0 }) });
+        const t0 = performance.now();
+        try {
+            await client.getBlockNumber();
+            const latencyMs = Math.max(0, Math.round(performance.now() - t0));
+            log(`[rpc] ${layer} ${host} ok latency=${latencyMs}ms`);
+            results.push({ ok: true, host, latencyMs });
+        }
+        catch (err) {
+            const failure = classifyProbeError(host, err);
+            if (failure.code !== undefined) {
+                log(`[rpc] ${layer} ${host} warn ${failure.code}`);
+            }
+            else {
+                log(`[rpc] ${layer} ${host} warn unreachable: ${failure.message.split('\n')[0]}`);
+            }
+            results.push(failure);
+        }
+    }
+    return results;
+}
+/**
+ * Boot-log summary line for a fallback chain, formatted per AC7:
+ *   `[rpc] L2 transport: fallback chain (N providers) — primary=<host>`
+ */
+export function summarizeFallbackChain(layer, urls) {
+    return `[rpc] ${layer} transport: ${describeFallbackChain(urls)}`;
+}
 //# sourceMappingURL=rpc-network.js.map

package/dist/preflight/rpc-network.js.map

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

package/dist/rpc/transport.d.ts

@@ -0,0 +1,109 @@
+/**
+ * RPC transport helper — builds a viem `fallback()` transport from a single
+ * URL, an array of URLs, or a comma-separated string. The substrate for issue
+ * #592 (multi-RPC fallback chain across daemon / relayer / indexer / CI).
+ *
+ * Design:
+ * - `parseRpcUrls` normalises `string | readonly string[]` to a deduplicated
+ *   non-empty array, splits comma-strings, trims, drops empties, and caps the
+ *   chain at {@link MAX_RPC_CHAIN_LENGTH} providers (extras are dropped with a
+ *   warning). Throws when no URLs remain.
+ * - `buildFallbackTransport` wraps `http(url)` per slot inside viem's
+ *   `fallback([...], { rank: false, retryCount: 0 })`. `rank: false` is
+ *   explicit — the issue's "Tenderly stays in slot 3" constraint requires
+ *   order preservation (no latency-based reshuffling). `retryCount: 0` keeps
+ *   the helper from doubling retries on top of the existing
+ *   `withRecoverableRetry` wrapper used by callers like the mech adapter.
+ * - On exhausted fall-through the helper rejects with `AllRpcsFailedError`,
+ *   which carries a structured `providers: readonly string[]` list of masked
+ *   hosts so callers and tests can assert on it.
+ * - `describeFallbackChain` formats the canonical AC7 boot-log summary line:
+ *   `fallback chain (N providers) — primary=<host>`.
+ *
+ * Do not conflate with `discovery.fallbackToOnchain` — that's a separate layer
+ * at the read-API level (Ponder → eth_getLogs floor). This helper sits beneath
+ * both layers at the JSON-RPC transport level.
+ */
+import { type FallbackTransport, type Transport } from 'viem';
+/**
+ * Hard cap on the number of providers in a single fallback chain. Four covers
+ * the "operator paid primary + public publicnode + public sepolia.base.org +
+ * Tenderly slot-3" shape from the issue; beyond that the boot probe takes too
+ * long and slot 5+ is almost always copy-paste noise.
+ */
+export declare const MAX_RPC_CHAIN_LENGTH = 4;
+export interface ParseRpcUrlsOptions {
+    /** Logger used to emit the "capped" warning. Defaults to `console.error`. */
+    log?: (message: string) => void;
+}
+/**
+ * Normalise `string | readonly string[]` into a non-empty, deduplicated,
+ * capped list of RPC URLs. Comma-separated strings are split (operator
+ * convention, see `peers` in `config.ts`). Duplicates are removed before the
+ * cap is applied so the effective chain length matches operator intent (an
+ * operator who prepends their paid primary to the existing fallback list
+ * shouldn't burn a slot on the duplicate).
+ *
+ * @throws if the input yields zero non-empty URLs.
+ */
+export declare function parseRpcUrls(input: string | readonly string[], options?: ParseRpcUrlsOptions): string[];
+/**
+ * Error thrown when every provider in a fallback chain has failed. Carries
+ * the masked host list so callers can surface a useful operator-facing message
+ * without leaking secret query strings (api-key paths).
+ */
+export declare class AllRpcsFailedError extends Error {
+    readonly providers: readonly string[];
+    readonly cause?: unknown;
+    constructor(providers: readonly string[], cause?: unknown);
+}
+/**
+ * Detect errors that viem's `fallback()` short-circuits on (via its
+ * `shouldThrow(err)` fast-exit) — `ExecutionRevertedError`,
+ * `TransactionRejectedRpcError`, `UserRejectedRequestError`,
+ * `WalletConnectSessionSettlementError`, and CAIP user-rejected (code
+ * `5000`). These are EVM- or wallet-level signals, NOT transport-level
+ * failures, so they must propagate unchanged. Wrapping them as
+ * `AllRpcsFailedError` would give the operator-app a false-positive
+ * "all RPCs failed" message when the actual problem is e.g. a contract
+ * revert on a view function.
+ *
+ * Mirrors viem's own predicate at
+ * `node_modules/viem/clients/transports/fallback.ts` (`shouldThrow`),
+ * dispatching by **numeric JSON-RPC code** (the path that catches real
+ * `RpcRequestError` instances coming out of the HTTP transport) plus the
+ * `ExecutionRevertedError.nodeMessage` regex (the path that catches reverts
+ * surfaced as plain `Error` with no numeric code). The cause-chain walk by
+ * class `name` remains as a third path for wallet-provider stacks that
+ * deliver proper class instances (and for already-normalised errors after
+ * viem's `buildRequest` re-wrap pass).
+ */
+export declare function isViemShouldThrowError(err: unknown): boolean;
+/**
+ * Mask an RPC URL down to its hostname for display / error reporting. Drops
+ * the path so api-key segments in the URL don't leak into logs.
+ */
+export declare function maskRpcHost(url: string): string;
+export interface BuildFallbackTransportOptions {
+    /**
+     * Set to `true` to let viem rank providers by latency. Default `false` —
+     * order matters for operator-configured paid primaries and the
+     * "Tenderly stays in slot 3" constraint from the issue.
+     */
+    rank?: boolean;
+}
+/**
+ * Build a viem fallback transport over the given URLs. Returns a callable
+ * transport suitable for `createPublicClient({ transport })`.
+ *
+ * Errors that exhaust the chain are wrapped in `AllRpcsFailedError`.
+ */
+export declare function buildFallbackTransport(urls: readonly string[], options?: BuildFallbackTransportOptions): FallbackTransport;
+export declare namespace buildFallbackTransport {
+    var buildFromTransports: (transports: readonly Transport[], urls: readonly string[], options?: BuildFallbackTransportOptions) => FallbackTransport;
+}
+/**
+ * Boot-log summary line for a fallback chain. Matches the canonical AC7
+ * format: `fallback chain (N providers) — primary=<host>`.
+ */
+export declare function describeFallbackChain(urls: readonly string[]): string;

package/dist/rpc/transport.js

@@ -0,0 +1,220 @@
+/**
+ * RPC transport helper — builds a viem `fallback()` transport from a single
+ * URL, an array of URLs, or a comma-separated string. The substrate for issue
+ * #592 (multi-RPC fallback chain across daemon / relayer / indexer / CI).
+ *
+ * Design:
+ * - `parseRpcUrls` normalises `string | readonly string[]` to a deduplicated
+ *   non-empty array, splits comma-strings, trims, drops empties, and caps the
+ *   chain at {@link MAX_RPC_CHAIN_LENGTH} providers (extras are dropped with a
+ *   warning). Throws when no URLs remain.
+ * - `buildFallbackTransport` wraps `http(url)` per slot inside viem's
+ *   `fallback([...], { rank: false, retryCount: 0 })`. `rank: false` is
+ *   explicit — the issue's "Tenderly stays in slot 3" constraint requires
+ *   order preservation (no latency-based reshuffling). `retryCount: 0` keeps
+ *   the helper from doubling retries on top of the existing
+ *   `withRecoverableRetry` wrapper used by callers like the mech adapter.
+ * - On exhausted fall-through the helper rejects with `AllRpcsFailedError`,
+ *   which carries a structured `providers: readonly string[]` list of masked
+ *   hosts so callers and tests can assert on it.
+ * - `describeFallbackChain` formats the canonical AC7 boot-log summary line:
+ *   `fallback chain (N providers) — primary=<host>`.
+ *
+ * Do not conflate with `discovery.fallbackToOnchain` — that's a separate layer
+ * at the read-API level (Ponder → eth_getLogs floor). This helper sits beneath
+ * both layers at the JSON-RPC transport level.
+ */
+import { ExecutionRevertedError, fallback, http, TransactionRejectedRpcError, UserRejectedRequestError, } from 'viem';
+/**
+ * Hard cap on the number of providers in a single fallback chain. Four covers
+ * the "operator paid primary + public publicnode + public sepolia.base.org +
+ * Tenderly slot-3" shape from the issue; beyond that the boot probe takes too
+ * long and slot 5+ is almost always copy-paste noise.
+ */
+export const MAX_RPC_CHAIN_LENGTH = 4;
+/**
+ * Normalise `string | readonly string[]` into a non-empty, deduplicated,
+ * capped list of RPC URLs. Comma-separated strings are split (operator
+ * convention, see `peers` in `config.ts`). Duplicates are removed before the
+ * cap is applied so the effective chain length matches operator intent (an
+ * operator who prepends their paid primary to the existing fallback list
+ * shouldn't burn a slot on the duplicate).
+ *
+ * @throws if the input yields zero non-empty URLs.
+ */
+export function parseRpcUrls(input, options = {}) {
+    const log = options.log ?? ((m) => process.stderr.write(`${m}\n`));
+    const raw = typeof input === 'string' ? input.split(',') : [...input];
+    const cleaned = raw.map((u) => u.trim()).filter((u) => u.length > 0);
+    if (cleaned.length === 0) {
+        throw new Error('parseRpcUrls: at least one RPC URL is required');
+    }
+    // Dedup before applying the cap so repeated URLs (easy to introduce when an
+    // operator prepends a paid primary that already exists in the fallback list)
+    // don't burn slots of the 4-slot chain. `Set` preserves first-seen insertion
+    // order, which matches the "primary stays in slot 0" constraint.
+    const deduped = [...new Set(cleaned)];
+    if (deduped.length > MAX_RPC_CHAIN_LENGTH) {
+        log(`[rpc] capped fallback chain to ${MAX_RPC_CHAIN_LENGTH} providers ` +
+            `(dropped ${deduped.length - MAX_RPC_CHAIN_LENGTH} extra slots)`);
+        return deduped.slice(0, MAX_RPC_CHAIN_LENGTH);
+    }
+    return deduped;
+}
+/**
+ * Error thrown when every provider in a fallback chain has failed. Carries
+ * the masked host list so callers can surface a useful operator-facing message
+ * without leaking secret query strings (api-key paths).
+ */
+export class AllRpcsFailedError extends Error {
+    providers;
+    cause;
+    constructor(providers, cause) {
+        super(`All RPC providers in the fallback chain failed (providers=${providers.join(', ')})`);
+        this.name = 'AllRpcsFailedError';
+        this.providers = providers;
+        this.cause = cause;
+    }
+}
+/**
+ * Detect errors that viem's `fallback()` short-circuits on (via its
+ * `shouldThrow(err)` fast-exit) — `ExecutionRevertedError`,
+ * `TransactionRejectedRpcError`, `UserRejectedRequestError`,
+ * `WalletConnectSessionSettlementError`, and CAIP user-rejected (code
+ * `5000`). These are EVM- or wallet-level signals, NOT transport-level
+ * failures, so they must propagate unchanged. Wrapping them as
+ * `AllRpcsFailedError` would give the operator-app a false-positive
+ * "all RPCs failed" message when the actual problem is e.g. a contract
+ * revert on a view function.
+ *
+ * Mirrors viem's own predicate at
+ * `node_modules/viem/clients/transports/fallback.ts` (`shouldThrow`),
+ * dispatching by **numeric JSON-RPC code** (the path that catches real
+ * `RpcRequestError` instances coming out of the HTTP transport) plus the
+ * `ExecutionRevertedError.nodeMessage` regex (the path that catches reverts
+ * surfaced as plain `Error` with no numeric code). The cause-chain walk by
+ * class `name` remains as a third path for wallet-provider stacks that
+ * deliver proper class instances (and for already-normalised errors after
+ * viem's `buildRequest` re-wrap pass).
+ */
+export function isViemShouldThrowError(err) {
+    // 1. Code-based dispatch — matches what viem's own `shouldThrow` does,
+    //    so a raw `RpcRequestError { code: 3 | -32003 | 4001 | 7000 | 5000 }`
+    //    from the HTTP transport is caught here regardless of class name.
+    //    Codes are pulled from the viem error classes (no magic numbers) where
+    //    available; 7000 and 5000 are inline because
+    //    `WalletConnectSessionSettlementError` is not re-exported from the
+    //    top-level `viem` package and 5000 is the CAIP user-rejected code
+    //    viem hard-codes alongside it.
+    if (err instanceof Error && 'code' in err && typeof err.code === 'number') {
+        const code = err.code;
+        if (code === ExecutionRevertedError.code || // 3 — contract revert
+            code === TransactionRejectedRpcError.code || // -32003 — tx rejected
+            code === UserRejectedRequestError.code || // 4001 — user-rejected
+            code === 7000 || // WalletConnectSessionSettlementError
+            code === 5000 // CAIP user-rejected
+        )
+            return true;
+        // 2. nodeMessage regex — catches reverts that arrive as a plain `Error`
+        //    (no numeric code, no recognised class name). Viem's own
+        //    `shouldThrow` runs this check too.
+        if (ExecutionRevertedError.nodeMessage.test(err.message))
+            return true;
+    }
+    // 3. Cause-chain walk — viem wraps low-level RPC errors in higher-level
+    //    error classes (e.g. `ContractFunctionExecutionError` →
+    //    `RpcRequestError` → `ExecutionRevertedError`), and wallet providers
+    //    can deliver proper class instances directly. Walk with cycle
+    //    detection so a self-referential `.cause` cannot infinite-loop.
+    const seen = new Set();
+    let cursor = err;
+    while (cursor instanceof Error && !seen.has(cursor)) {
+        seen.add(cursor);
+        if (cursor.name === 'ExecutionRevertedError')
+            return true;
+        if (cursor.name === 'TransactionRejectedRpcError')
+            return true;
+        if (cursor.name === 'UserRejectedRequestError')
+            return true;
+        if (cursor.name === 'WalletConnectSessionSettlementError')
+            return true;
+        cursor = cursor.cause;
+    }
+    return false;
+}
+/**
+ * Mask an RPC URL down to its hostname for display / error reporting. Drops
+ * the path so api-key segments in the URL don't leak into logs.
+ */
+export function maskRpcHost(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.hostname || '(unknown host)';
+    }
+    catch {
+        return '(invalid rpc url)';
+    }
+}
+/**
+ * Build a viem fallback transport over the given URLs. Returns a callable
+ * transport suitable for `createPublicClient({ transport })`.
+ *
+ * Errors that exhaust the chain are wrapped in `AllRpcsFailedError`.
+ */
+export function buildFallbackTransport(urls, options = {}) {
+    const transports = urls.map((url) => http(url));
+    return buildFallbackTransport.buildFromTransports(transports, urls, options);
+}
+/**
+ * Internal helper exposed for tests: build a fallback transport from
+ * pre-constructed viem transports (e.g. `custom()` mocks) so tests can drive
+ * each slot deterministically without an actual HTTP fetch.
+ */
+buildFallbackTransport.buildFromTransports = function buildFromTransports(transports, urls, options = {}) {
+    const maskedProviders = urls.map(maskRpcHost);
+    const inner = fallback(transports, {
+        rank: options.rank ?? false,
+        retryCount: 0,
+    });
+    // Wrap the transport so that the final exhausted-chain rejection surfaces
+    // as our structured `AllRpcsFailedError` (carrying the masked host list).
+    // We do the wrap at the transport-factory level rather than swapping the
+    // returned function's `request` so the FallbackTransport's typed shape
+    // (`onResponse`, `transports`, etc.) is preserved.
+    const wrapped = ((config) => {
+        const t = inner(config);
+        const originalRequest = t.request.bind(t);
+        t.request = (async (args) => {
+            try {
+                return await originalRequest(args);
+            }
+            catch (err) {
+                // viem's fallback() short-circuits on shouldThrow-class errors
+                // (contract revert, user-rejected, CAIP 5000) — those are
+                // EVM/wallet-level, not transport-level failures. Propagate them
+                // unchanged so callers (and the operator-app's `rpc_all_failed`
+                // state message) don't misread a single-slot revert as an
+                // exhausted-chain outage.
+                if (isViemShouldThrowError(err))
+                    throw err;
+                // Otherwise: viem doesn't expose a distinct "all transports failed"
+                // error class — when fallback exhausts the chain it throws the last
+                // underlying error. Wrap so the caller gets a stable structural
+                // error carrying the masked provider list.
+                throw new AllRpcsFailedError(maskedProviders, err);
+            }
+        });
+        return t;
+    });
+    return wrapped;
+};
+/**
+ * Boot-log summary line for a fallback chain. Matches the canonical AC7
+ * format: `fallback chain (N providers) — primary=<host>`.
+ */
+export function describeFallbackChain(urls) {
+    if (urls.length === 0)
+        return 'fallback chain (0 providers)';
+    return `fallback chain (${urls.length} providers) — primary=${maskRpcHost(urls[0])}`;
+}
+//# sourceMappingURL=transport.js.map

package/dist/rpc/transport.js.map

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

package/dist/spend/credential.d.ts

@@ -0,0 +1,8 @@
+/** A credential identity. Format: `{provider}:{authMethod}`, e.g. `anthropic:api-key`. Never empty. */
+export type CredentialId = string;
+/**
+ * Resolve which authentication credential a harness will bill against, from
+ * the presence of provider env vars. Returns null when the harness makes no
+ * paid LLM call (e.g. prediction harnesses) or no credential is recognisable.
+ */
+export declare function resolveCredentialId(harness: string | undefined, env: NodeJS.ProcessEnv): CredentialId | null;

package/dist/spend/credential.js

@@ -0,0 +1,30 @@
+import { CLAUDE_CODE_HARNESS, CODEX_HARNESS, HERMES_AGENT_HARNESS, canonicalHarnessName, } from '../harnesses/names.js';
+/**
+ * Resolve which authentication credential a harness will bill against, from
+ * the presence of provider env vars. Returns null when the harness makes no
+ * paid LLM call (e.g. prediction harnesses) or no credential is recognisable.
+ */
+export function resolveCredentialId(harness, env) {
+    if (!harness)
+        return null;
+    switch (canonicalHarnessName(harness)) {
+        case CLAUDE_CODE_HARNESS:
+            // empty string treated as absent
+            if (env['CLAUDE_CODE_OAUTH_TOKEN'])
+                return 'anthropic:subscription';
+            if (env['ANTHROPIC_API_KEY'])
+                return 'anthropic:api-key';
+            return null;
+        case CODEX_HARNESS:
+            if (env['OPENAI_API_KEY'])
+                return 'openai:api-key';
+            return 'openai:subscription';
+        case HERMES_AGENT_HARNESS: {
+            const provider = (env['JINN_HERMES_PROVIDER'] ?? 'hermes').trim().toLowerCase();
+            return `${provider}:api-key`;
+        }
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=credential.js.map

package/dist/spend/credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.js","sourceRoot":"","sources":["../../src/spend/credential.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAK/B;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA2B,EAC3B,GAAsB;IAEtB,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,QAAQ,oBAAoB,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,KAAK,mBAAmB;YACtB,iCAAiC;YACjC,IAAI,GAAG,CAAC,yBAAyB,CAAC;gBAAE,OAAO,wBAAwB,CAAC;YACpE,IAAI,GAAG,CAAC,mBAAmB,CAAC;gBAAE,OAAO,mBAAmB,CAAC;YACzD,OAAO,IAAI,CAAC;QACd,KAAK,aAAa;YAChB,IAAI,GAAG,CAAC,gBAAgB,CAAC;gBAAE,OAAO,gBAAgB,CAAC;YACnD,OAAO,qBAAqB,CAAC;QAC/B,KAAK,oBAAoB,CAAC,CAAC,CAAC;YAC1B,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,sBAAsB,CAAC,IAAI,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAChF,OAAO,GAAG,QAAQ,UAAU,CAAC;QAC/B,CAAC;QACD;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/spend/daemon-config.d.ts

@@ -0,0 +1,13 @@
+import type { JinnConfig } from '../config.js';
+import { type CredentialId } from './credential.js';
+export interface SpendCapDaemonConfig {
+    /** credentialId -> USD/day cap. */
+    caps: Record<CredentialId, number>;
+    /** manifest CID -> the credential its harness bills against. */
+    manifestCredentials: Record<string, CredentialId>;
+}
+/**
+ * Assemble the daemon's spend-cap config from operator config + env. Returns
+ * undefined when no credential ends up with a cap (the gate then stays off).
+ */
+export declare function buildSpendCapConfig(config: Pick<JinnConfig, 'joinedSolverNets' | 'spendCaps'>, env: NodeJS.ProcessEnv): SpendCapDaemonConfig | undefined;

package/dist/spend/daemon-config.js

@@ -0,0 +1,24 @@
+import { resolveCredentialId } from './credential.js';
+/**
+ * Assemble the daemon's spend-cap config from operator config + env. Returns
+ * undefined when no credential ends up with a cap (the gate then stays off).
+ */
+export function buildSpendCapConfig(config, env) {
+    const blanketRaw = env['JINN_SPEND_CAP_USD'];
+    const blanketNum = blanketRaw != null && blanketRaw.trim() !== '' ? Number(blanketRaw) : NaN;
+    const blanket = Number.isFinite(blanketNum) && blanketNum > 0 ? blanketNum : undefined;
+    const manifestCredentials = {};
+    for (const [manifestCid, entry] of Object.entries(config.joinedSolverNets ?? {})) {
+        const credentialId = resolveCredentialId(entry.harness, env);
+        if (credentialId)
+            manifestCredentials[manifestCid] = credentialId;
+    }
+    const caps = {};
+    for (const credentialId of new Set(Object.values(manifestCredentials))) {
+        const cap = config.spendCaps?.[credentialId] ?? blanket;
+        if (cap != null)
+            caps[credentialId] = cap;
+    }
+    return Object.keys(caps).length > 0 ? { caps, manifestCredentials } : undefined;
+}
+//# sourceMappingURL=daemon-config.js.map

package/dist/spend/daemon-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-config.js","sourceRoot":"","sources":["../../src/spend/daemon-config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAqB,MAAM,iBAAiB,CAAC;AASzE;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAA0D,EAC1D,GAAsB;IAEtB,MAAM,UAAU,GAAG,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,UAAU,IAAI,IAAI,IAAI,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC7F,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IAEvF,MAAM,mBAAmB,GAAiC,EAAE,CAAC;IAC7D,KAAK,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,gBAAgB,IAAI,EAAE,CAAC,EAAE,CAAC;QACjF,MAAM,YAAY,GAAG,mBAAmB,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC7D,IAAI,YAAY;YAAE,mBAAmB,CAAC,WAAW,CAAC,GAAG,YAAY,CAAC;IACpE,CAAC;IAED,MAAM,IAAI,GAAiC,EAAE,CAAC;IAC9C,KAAK,MAAM,YAAY,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC;QACvE,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC;QACxD,IAAI,GAAG,IAAI,IAAI;YAAE,IAAI,CAAC,YAAY,CAAC,GAAG,GAAG,CAAC;IAC5C,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAClF,CAAC"}

package/dist/spend/pricing.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Price a token count in USD for the given model. Returns null when the model
+ * is unknown to the catalog (caller falls back to a heuristic).
+ *
+ * Uses the tokenlens bundled, offline model catalog (models.dev snapshot).
+ * The `tokenlens` re-export of `getTokenCosts` accepts an object with
+ * `{ modelId, usage }` and injects the default catalog automatically.
+ *
+ * Note: tokenlens's bundled catalog may lag current model IDs (e.g.
+ * `claude-haiku-4-5-20251001` is absent in v1.3.1 and returns null);
+ * callers must handle null gracefully.
+ */
+export declare function priceTokens(modelId: string, tokens: {
+    inputTokens: number;
+    outputTokens: number;
+}): number | null;

package/dist/spend/pricing.js

@@ -0,0 +1,26 @@
+import { getTokenCosts } from 'tokenlens';
+/**
+ * Price a token count in USD for the given model. Returns null when the model
+ * is unknown to the catalog (caller falls back to a heuristic).
+ *
+ * Uses the tokenlens bundled, offline model catalog (models.dev snapshot).
+ * The `tokenlens` re-export of `getTokenCosts` accepts an object with
+ * `{ modelId, usage }` and injects the default catalog automatically.
+ *
+ * Note: tokenlens's bundled catalog may lag current model IDs (e.g.
+ * `claude-haiku-4-5-20251001` is absent in v1.3.1 and returns null);
+ * callers must handle null gracefully.
+ */
+export function priceTokens(modelId, tokens) {
+    try {
+        const costs = getTokenCosts({
+            modelId,
+            usage: { prompt_tokens: tokens.inputTokens, completion_tokens: tokens.outputTokens },
+        });
+        return typeof costs?.totalUSD === 'number' ? costs.totalUSD : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=pricing.js.map

package/dist/spend/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../src/spend/pricing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,MAAqD;IAErD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,aAAa,CAAC;YAC1B,OAAO;YACP,KAAK,EAAE,EAAE,aAAa,EAAE,MAAM,CAAC,WAAW,EAAE,iBAAiB,EAAE,MAAM,CAAC,YAAY,EAAE;SACrF,CAAC,CAAC;QACH,OAAO,OAAO,KAAK,EAAE,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/spend/record.d.ts

@@ -0,0 +1,13 @@
+import type { Store } from '../store/store.js';
+/**
+ * Record the cost of one finished harness run as a `task_cost` activity row.
+ * Called once per harness run (at the POST_SNAPSHOT transition). Best-effort:
+ * never throws — a parse failure must not break task execution.
+ */
+export declare function recordTaskCost(store: Store, args: {
+    requestId: string;
+    harness: string;
+    model: string | undefined;
+    workingDir: string;
+    solverType: string | null;
+}, env?: NodeJS.ProcessEnv): void;

package/dist/spend/record.js

@@ -0,0 +1,30 @@
+import { resolveCredentialId } from './credential.js';
+import { harvestHarnessUsage } from './usage.js';
+/**
+ * Record the cost of one finished harness run as a `task_cost` activity row.
+ * Called once per harness run (at the POST_SNAPSHOT transition). Best-effort:
+ * never throws — a parse failure must not break task execution.
+ */
+export function recordTaskCost(store, args, env = process.env) {
+    try {
+        const credentialId = resolveCredentialId(args.harness, env);
+        if (!credentialId)
+            return;
+        const usage = harvestHarnessUsage(args.harness, args.workingDir, args.model);
+        store.recordActivityEvent({
+            ts: new Date().toISOString(),
+            kind: 'task_cost',
+            requestId: args.requestId,
+            solverType: args.solverType,
+            credentialId,
+            costUsdMicros: Math.round(usage.costUsd * 1_000_000),
+            model: usage.model,
+            detail: usage.estimated ? 'estimated' : 'observed',
+        });
+    }
+    catch (err) {
+        console.warn(`[spend] failed to record task cost for ${args.requestId}: ` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=record.js.map

package/dist/spend/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/spend/record.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAY,EACZ,IAMC,EACD,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC5D,IAAI,CAAC,YAAY;YAAE,OAAO;QAC1B,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7E,KAAK,CAAC,mBAAmB,CAAC;YACxB,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,YAAY;YACZ,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;YACpD,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU;SACnD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CACV,0CAA0C,IAAI,CAAC,SAAS,IAAI;YAC1D,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACxD,CAAC;IACJ,CAAC;AACH,CAAC"}