@goassay-ai/sdk 0.0.0-bootstrap.0 → 0.1.0

package/dist/http.d.ts

@@ -0,0 +1,52 @@
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** Where the SDK writes what it does. Silent by default. Fields never carry keys or signatures. */
+export interface Logger {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+}
+export declare const silentLogger: Logger;
+/** JSON-RPC "rate limited" (spec section 2.1). */
+export declare const RPC_RATE_LIMITED = -32029;
+/** A server asking for a longer wait than this is not retried; the caller gets the error. */
+export declare const MAX_RETRY_AFTER_MS = 60000;
+/** A copy of `fields` with anything that looks secret removed. Applied to every log line. */
+export declare function redact(fields: Record<string, unknown>): Record<string, unknown>;
+export interface HttpOptions {
+    fetch: FetchLike;
+    apiKey: string;
+    /** The only origins the API key is sent to: the MCP and the API origin. */
+    origins: readonly string[];
+    timeoutMs: number;
+    maxRetries: number;
+    logger: Logger;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    userAgent: string;
+}
+export interface HttpRequest {
+    url: string;
+    method: "GET" | "POST";
+    headers?: Record<string, string>;
+    body?: string;
+    /** Retry connection failures and retryable statuses (safe: reads, and idempotent MCP calls). */
+    retry: boolean;
+}
+export interface HttpResponse {
+    status: number;
+    headers: Headers;
+    text: string;
+}
+/** `Retry-After` (seconds or an HTTP date) in milliseconds, or undefined. */
+export declare function retryAfterMs(value: string | null, nowMs: number): number | undefined;
+/**
+ * One origin-pinned HTTP client for the MCP and API hosts: the bearer goes only to the configured
+ * origins, redirects are an error, every attempt has a timeout, and retries back off and honour
+ * `Retry-After`. Every answer's `Date` header updates the clock offset (spec section 7).
+ */
+export declare class Http {
+    #private;
+    /** Server clock minus local clock, seconds, from the last answer. */
+    dateOffset: number;
+    constructor(options: HttpOptions);
+    request(req: HttpRequest): Promise<HttpResponse>;
+}

package/dist/http.js

@@ -0,0 +1,139 @@
+import { dateHeaderOffset } from "./core/clock.js";
+import { NetworkError, TimeoutError } from "./errors.js";
+import { redactMcpUrl } from "./mcp-url.js";
+export const silentLogger = { debug() { }, warn() { } };
+/** Statuses retried with backoff (with `Retry-After` honoured). */
+const RETRY_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+/** JSON-RPC "rate limited" (spec section 2.1). */
+export const RPC_RATE_LIMITED = -32029;
+const BASE_DELAY_MS = 500;
+const MAX_BACKOFF_MS = 8_000;
+/** A server asking for a longer wait than this is not retried; the caller gets the error. */
+export const MAX_RETRY_AFTER_MS = 60_000;
+const SECRET_KEY = /authorization|api[-_]?key|signature|secret|private|token|voucher/i;
+const LONG_HEX = /0x[0-9a-fA-F]{100,}/g;
+/** A copy of `fields` with anything that looks secret removed. Applied to every log line. */
+export function redact(fields) {
+    const out = {};
+    for (const [k, v] of Object.entries(fields)) {
+        if (SECRET_KEY.test(k))
+            out[k] = "[redacted]";
+        else if (typeof v === "string")
+            out[k] = v.replace(LONG_HEX, "[redacted]");
+        else
+            out[k] = v;
+    }
+    return out;
+}
+/** `Retry-After` (seconds or an HTTP date) in milliseconds, or undefined. */
+export function retryAfterMs(value, nowMs) {
+    if (value === null || value.trim() === "")
+        return undefined;
+    if (/^\d+$/.test(value.trim()))
+        return Number(value.trim()) * 1000;
+    const at = Date.parse(value);
+    return Number.isFinite(at) ? Math.max(0, at - nowMs) : undefined;
+}
+/** `data.retryAfterMs` of a JSON-RPC -32029 answer, or `undefined` when the body is not one. */
+function rpcRateLimit(text) {
+    if (!text.includes(String(RPC_RATE_LIMITED)))
+        return undefined;
+    try {
+        const msg = JSON.parse(text);
+        if (msg?.error?.code !== RPC_RATE_LIMITED)
+            return undefined;
+        const ms = msg.error.data?.retryAfterMs;
+        return { retryAfterMs: typeof ms === "number" && Number.isFinite(ms) && ms >= 0 ? ms : undefined };
+    }
+    catch {
+        return undefined;
+    }
+}
+class RedirectRefused extends Error {
+}
+/** `fetch` with `redirect: "error"` rejects a redirect with a TypeError whose cause says so. */
+function isRedirectError(err) {
+    const cause = err instanceof Error ? err.cause : undefined;
+    return typeof cause?.message === "string" && /redirect/i.test(cause.message);
+}
+/**
+ * One origin-pinned HTTP client for the MCP and API hosts: the bearer goes only to the configured
+ * origins, redirects are an error, every attempt has a timeout, and retries back off and honour
+ * `Retry-After`. Every answer's `Date` header updates the clock offset (spec section 7).
+ */
+export class Http {
+    #o;
+    /** Server clock minus local clock, seconds, from the last answer. */
+    dateOffset = 0;
+    constructor(options) {
+        this.#o = options;
+    }
+    async request(req) {
+        const url = new URL(req.url);
+        if (!this.#o.origins.includes(url.origin))
+            throw new NetworkError("refusing a request to an origin the client was not configured for");
+        const attempts = req.retry ? this.#o.maxRetries + 1 : 1;
+        for (let attempt = 0;; attempt++) {
+            const last = attempt + 1 >= attempts;
+            const started = this.#o.now();
+            let res;
+            let text;
+            const signal = AbortSignal.timeout(this.#o.timeoutMs);
+            try {
+                res = await this.#o.fetch(req.url, {
+                    method: req.method,
+                    headers: {
+                        accept: "application/json",
+                        "user-agent": this.#o.userAgent,
+                        ...req.headers,
+                        authorization: `Bearer ${this.#o.apiKey}`,
+                    },
+                    ...(req.body !== undefined ? { body: req.body } : {}),
+                    redirect: "error",
+                    signal,
+                });
+                // Also refuse a redirect an injected fetch followed: the bearer must not leave the origin.
+                if (res.redirected ||
+                    (res.url !== "" && new URL(res.url).origin !== url.origin) ||
+                    (res.status >= 300 && res.status < 400)) {
+                    await res.body?.cancel().catch(() => undefined);
+                    throw new RedirectRefused();
+                }
+                text = await res.text();
+            }
+            catch (err) {
+                if (err instanceof RedirectRefused || isRedirectError(err))
+                    throw new NetworkError("refusing to follow a redirect", err, "REDIRECT_REFUSED");
+                const timedOut = signal.aborted;
+                this.#log(req, attempt, { error: timedOut ? "timeout" : "network" }, started);
+                if (!last) {
+                    await this.#o.sleep(this.#backoff(attempt));
+                    continue;
+                }
+                throw timedOut ? new TimeoutError(undefined, err) : new NetworkError("could not reach Assay", err);
+            }
+            this.dateOffset = dateHeaderOffset(res.headers.get("date"), this.#o.now() / 1000);
+            this.#log(req, attempt, { status: res.status }, started);
+            if (!last) {
+                const rpc = rpcRateLimit(text);
+                if (RETRY_STATUSES.has(res.status) || rpc !== undefined) {
+                    const wait = retryAfterMs(res.headers.get("retry-after"), this.#o.now()) ?? rpc?.retryAfterMs;
+                    if (wait === undefined || wait <= MAX_RETRY_AFTER_MS) {
+                        await this.#o.sleep(wait ?? this.#backoff(attempt));
+                        continue;
+                    }
+                }
+            }
+            return { status: res.status, headers: res.headers, text };
+        }
+    }
+    #backoff(attempt) {
+        const base = Math.min(MAX_BACKOFF_MS, BASE_DELAY_MS * 2 ** attempt);
+        return Math.round(base * (0.75 + Math.random() * 0.25));
+    }
+    #log(req, attempt, extra, started) {
+        // A link-only token (`/u/{token}`) is a secret: logged as `/u/…`.
+        const path = redactMcpUrl(new URL(req.url).pathname.split("/").slice(0, 4).join("/"));
+        this.#o.logger.debug("assay request", redact({ method: req.method, path, attempt, ms: this.#o.now() - started, ...extra }));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { Assay, DEFAULT_API_URL, DEFAULT_MCP_URL, DEFAULT_WEB_URL, type AssayOptions } from "./client.js";
+export { BUILT_IN_NETWORKS } from "./networks.js";
+export { AssayError, AuthError, ConfigError, DelegateAlreadyBoundError, DelegateBindConflictError, HumanSessionRequiredError, McpUrlNotFoundError, NetworkError, PaymentError, PaymentNetworkUnknownError, PaymentRefusedError, PaymentRequiredError, PaymentSchemeUnsupportedError, RateLimitError, ScopeMissingError, ServerError, TimeoutError, } from "./errors.js";
+export { evmSigner, type EvmSigner, type Signer, type TypedData, type ViemLikeAccount } from "./signer.js";
+export type { Logger } from "./http.js";
+export type { OnPayment } from "./resources/context.js";
+export type { PaymentDetails } from "./schemes/types.js";
+export type { Eip155Network, Limits } from "./schemes/eip155/index.js";
+export type { CallOptions, CallReceipt, ListOptions, ListResult, SearchOptions, SearchResult, ToolInfo, ToolResult, ToolSummary, } from "./resources/tools.js";
+export type { Receipt } from "./resources/receipts.js";
+export type { BindResult, PaidCallsState, PaidCallsStatus, WaitOptions } from "./resources/paid-calls.js";
+export type { Money } from "./core/voucher.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Assay, DEFAULT_API_URL, DEFAULT_MCP_URL, DEFAULT_WEB_URL } from "./client.js";
+export { BUILT_IN_NETWORKS } from "./networks.js";
+export { AssayError, AuthError, ConfigError, DelegateAlreadyBoundError, DelegateBindConflictError, HumanSessionRequiredError, McpUrlNotFoundError, NetworkError, PaymentError, PaymentNetworkUnknownError, PaymentRefusedError, PaymentRequiredError, PaymentSchemeUnsupportedError, RateLimitError, ScopeMissingError, ServerError, TimeoutError, } from "./errors.js";
+export { evmSigner } from "./signer.js";

package/dist/mcp-url.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The MCP URL shapes the Assay MCP host serves (spec section 2.3), checked when a client is built
+ * so a typo is a `ConfigError` at once, not a 404 on the first call. Only the shape is checked:
+ * whether the tool set exists, or is shared with this key, is the server's answer.
+ *
+ * To support a new shape, add one line to `PATH_SHAPES` or `FILTERS`.
+ */
+/** The MCP origin a bare path (`"/my/research"`) resolves against. */
+export declare const DEFAULT_MCP_ORIGIN = "https://mcp.goassay.ai";
+/**
+ * `value` (a full MCP URL, or a path such as `"/my/research"` resolved against `origin`) as the
+ * URL to send to. Throws `ConfigError` for a path the MCP host does not serve. The URL is sent as
+ * given: the server reads it into its canonical form.
+ */
+export declare function resolveMcpUrl(name: string, value: string, origin: string): string;
+/** `url` with a link-only token shown as `/u/…`: for `toString`, `toJSON`, `inspect` and logs. */
+export declare function redactMcpUrl(url: string): string;

package/dist/mcp-url.js

@@ -0,0 +1,98 @@
+import { ConfigError } from "./errors.js";
+/**
+ * The MCP URL shapes the Assay MCP host serves (spec section 2.3), checked when a client is built
+ * so a typo is a `ConfigError` at once, not a 404 on the first call. Only the shape is checked:
+ * whether the tool set exists, or is shared with this key, is the server's answer.
+ *
+ * To support a new shape, add one line to `PATH_SHAPES` or `FILTERS`.
+ */
+/** The MCP origin a bare path (`"/my/research"`) resolves against. */
+export const DEFAULT_MCP_ORIGIN = "https://mcp.goassay.ai";
+const SLUG = "[a-z0-9-]{2,64}";
+const HANDLE = "[a-z][a-z0-9-]{2,23}";
+const CATEGORY = "[a-z][a-z0-9-]{1,63}";
+/** A link-only token: a secret, never printed (see {@link redactMcpUrl}). */
+const TOKEN = "[a-z0-9_-]{22,64}";
+const VERSION = "(?:@[1-9][0-9]{0,5})?";
+/** Paths, matched lowercased with `%40` read as `@` and one trailing slash removed. */
+const PATH_SHAPES = [
+    /^\/$/, // Everything
+    new RegExp(`^/my/${SLUG}${VERSION}$`), // my tool set: Draft, or version n
+    new RegExp(`^/@${HANDLE}/${SLUG}${VERSION}$`), // a public tool set
+    new RegExp(`^/u/${TOKEN}${VERSION}$`), // a link-only tool set
+    new RegExp(`^/c/${CATEGORY}$`), // a topic
+    new RegExp(`^/@${HANDLE}$`), // one maker's tools
+];
+const TOOL_SELECTOR = /^[a-z][a-z0-9_-]{1,47}(?:@[1-9][0-9]{0,5})?$/;
+const CATEGORY_RE = new RegExp(`^${CATEGORY}$`);
+const MAX_TOOLS = 50;
+const MAX_URL_LENGTH = 2048;
+/** `scheme://authority` at the start of a full URL. */
+const ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*/i;
+/** A comma list, trimmed and lowercased, empty items dropped. */
+const items = (v) => v
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter((s) => s !== "");
+/** Query filters (they only narrow what a URL serves): name -> is this value accepted. */
+const FILTERS = {
+    tools: (v) => items(v).every((t) => TOOL_SELECTOR.test(t)),
+    category: (v) => items(v).every((c) => CATEGORY_RE.test(c)),
+    free: (v) => v.trim() === "0" || v.trim() === "1",
+    discovery: (v) => ["auto", "full", "search"].includes(v.trim().toLowerCase()),
+};
+/** Throws `ConfigError` unless `pathAndQuery` (from the first `/`, no fragment) has a served shape. */
+function checkShape(name, pathAndQuery) {
+    if (pathAndQuery.length > MAX_URL_LENGTH)
+        throw new ConfigError(`${name} is too long`);
+    const q = pathAndQuery.indexOf("?");
+    const rawPath = q === -1 ? pathAndQuery : pathAndQuery.slice(0, q);
+    const decoded = rawPath.replace(/%40/gi, "@");
+    if (decoded.includes("%"))
+        throw new ConfigError(`${name} has a percent-escape in its path`);
+    let path = decoded.toLowerCase();
+    if (path.length > 1 && path.endsWith("/"))
+        path = path.slice(0, -1);
+    if (!PATH_SHAPES.some((shape) => shape.test(path)))
+        throw new ConfigError(`${name} is not an MCP URL Assay serves (see "Choose a URL")`);
+    const params = new URLSearchParams(q === -1 ? "" : pathAndQuery.slice(q + 1));
+    const tools = new Set();
+    for (const [key, value] of params) {
+        const accepts = Object.hasOwn(FILTERS, key) ? FILTERS[key] : undefined;
+        if (!accepts)
+            throw new ConfigError(`${name} has an unknown filter "${key.slice(0, 32)}"`);
+        if (!accepts(value))
+            throw new ConfigError(`${name} has an invalid "${key}" filter`);
+        if (key === "tools")
+            for (const t of items(value))
+                tools.add(t);
+    }
+    if (tools.size > MAX_TOOLS)
+        throw new ConfigError(`${name} names more than ${MAX_TOOLS} tools`);
+}
+/**
+ * `value` (a full MCP URL, or a path such as `"/my/research"` resolved against `origin`) as the
+ * URL to send to. Throws `ConfigError` for a path the MCP host does not serve. The URL is sent as
+ * given: the server reads it into its canonical form.
+ */
+export function resolveMcpUrl(name, value, origin) {
+    if (typeof value !== "string" || value.trim() !== value || value === "")
+        throw new ConfigError(`${name} is not a URL`);
+    if (value.includes("#"))
+        throw new ConfigError(`${name} must not have a fragment`);
+    if (value.startsWith("/")) {
+        if (value.startsWith("//"))
+            throw new ConfigError(`${name} is not a URL`);
+        checkShape(name, value);
+        return origin + value;
+    }
+    // The raw text after the origin: `URL` would quietly resolve `.` and `..`, which the host refuses.
+    const rest = value.replace(ORIGIN, "");
+    checkShape(name, rest === "" ? "/" : rest.startsWith("?") ? `/${rest}` : rest);
+    return value;
+}
+/** `url` with a link-only token shown as `/u/…`: for `toString`, `toJSON`, `inspect` and logs. */
+export function redactMcpUrl(url) {
+    const origin = ORIGIN.exec(url)?.[0] ?? "";
+    return origin + url.slice(origin.length).replace(/\/u\/[^/?#@]+/gi, "/u/…");
+}

package/dist/mcp.d.ts

@@ -0,0 +1,23 @@
+import { AssayError } from "./errors.js";
+import { type Http } from "./http.js";
+/** The MCP protocol revision this release speaks: per-request envelope, no handshake. */
+export declare const MCP_PROTOCOL_VERSION = "2026-07-28";
+/**
+ * A minimal MCP client over HTTP (spec section 2.1): one JSON-RPC request per POST, no session,
+ * no handshake. The protocol revision rides each request in `_meta` and in headers.
+ */
+export declare class McpTransport {
+    #private;
+    private readonly http;
+    private readonly url;
+    private readonly clientInfo;
+    private readonly now;
+    constructor(http: Http, url: string, clientInfo: {
+        name: string;
+        version: string;
+    }, now?: () => number);
+    /** Sends one request and returns its `result`. Network retries resend the same bytes. */
+    request(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+/** The platform's REST error envelope (spec section 2.2) on a non-JSON-RPC answer, or `null`. */
+export declare function restError(status: number, text: string, retryAfter: string | null, nowMs: number): AssayError | null;

package/dist/mcp.js

@@ -0,0 +1,121 @@
+import { isObject } from "./core/meta.js";
+import { AssayError, errorFromServer, McpUrlNotFoundError, RateLimitError, ServerError } from "./errors.js";
+import { RPC_RATE_LIMITED, retryAfterMs } from "./http.js";
+/** The MCP protocol revision this release speaks: per-request envelope, no handshake. */
+export const MCP_PROTOCOL_VERSION = "2026-07-28";
+/**
+ * A minimal MCP client over HTTP (spec section 2.1): one JSON-RPC request per POST, no session,
+ * no handshake. The protocol revision rides each request in `_meta` and in headers.
+ */
+export class McpTransport {
+    http;
+    url;
+    clientInfo;
+    now;
+    #id = 1;
+    constructor(http, url, clientInfo, now = Date.now) {
+        this.http = http;
+        this.url = url;
+        this.clientInfo = clientInfo;
+        this.now = now;
+    }
+    /** Sends one request and returns its `result`. Network retries resend the same bytes. */
+    async request(method, params) {
+        const meta = isObject(params._meta) ? params._meta : {};
+        const body = {
+            jsonrpc: "2.0",
+            id: this.#id++,
+            method,
+            params: {
+                ...params,
+                _meta: {
+                    ...meta,
+                    "io.modelcontextprotocol/protocolVersion": MCP_PROTOCOL_VERSION,
+                    "io.modelcontextprotocol/clientCapabilities": {},
+                    "io.modelcontextprotocol/clientInfo": this.clientInfo,
+                },
+            },
+        };
+        const headers = {
+            "content-type": "application/json",
+            accept: "application/json, text/event-stream",
+            "mcp-protocol-version": MCP_PROTOCOL_VERSION,
+            "mcp-method": method,
+        };
+        if (typeof params.name === "string")
+            headers["mcp-name"] = params.name;
+        const res = await this.http.request({
+            url: this.url,
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            retry: true,
+        });
+        const msg = parseMessage(res.text, res.headers.get("content-type"));
+        if (!isObject(msg) || msg.jsonrpc !== "2.0") {
+            // A 404 from the MCP host is always about the URL (MCP_URL_NOT_FOUND, sent as the REST
+            // envelope). The fixed message never repeats the URL, which may hold a link-only token.
+            if (res.status === 404)
+                throw new McpUrlNotFoundError();
+            throw (restError(res.status, res.text, res.headers.get("retry-after"), this.now()) ??
+                new ServerError("MCP_BAD_ANSWER", "Assay sent an answer the SDK cannot read", { status: res.status }));
+        }
+        if (isObject(msg.error))
+            throw rpcError(msg.error, res.status, res.headers.get("retry-after"), this.now());
+        if (!isObject(msg.result)) {
+            throw (restError(res.status, res.text, res.headers.get("retry-after"), this.now()) ??
+                new ServerError("MCP_BAD_ANSWER", "Assay sent an answer the SDK cannot read", { status: res.status }));
+        }
+        return msg.result;
+    }
+}
+function parseMessage(text, contentType) {
+    try {
+        if (contentType?.includes("text/event-stream")) {
+            for (const line of text.split(/\r?\n/)) {
+                if (!line.startsWith("data:"))
+                    continue;
+                const m = JSON.parse(line.slice(5).trim());
+                if (isObject(m) && ("result" in m || "error" in m))
+                    return m;
+            }
+            return null;
+        }
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function rpcError(error, status, retryAfter, nowMs) {
+    const message = typeof error.message === "string" ? error.message : "the MCP request failed";
+    const data = isObject(error.data) ? error.data : {};
+    if (error.code === RPC_RATE_LIMITED) {
+        const ms = typeof data.retryAfterMs === "number" ? data.retryAfterMs : retryAfterMs(retryAfter, nowMs);
+        return new RateLimitError("RATE_LIMITED", message, { status, ...(ms !== undefined ? { retryAfterMs: ms } : {}) });
+    }
+    const code = typeof data.code === "string" ? data.code : `MCP_RPC_${String(error.code)}`;
+    return errorFromServer(code, message, { status, details: { rpcCode: error.code } });
+}
+/** The platform's REST error envelope (spec section 2.2) on a non-JSON-RPC answer, or `null`. */
+export function restError(status, text, retryAfter, nowMs) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = null;
+    }
+    const e = isObject(body) && isObject(body.error) ? body.error : null;
+    if (e === null && status >= 200 && status < 300)
+        return null;
+    const code = e && typeof e.code === "string" ? e.code : undefined;
+    const message = e && typeof e.message === "string" ? e.message : `Assay answered HTTP ${status}`;
+    const details = e && isObject(e.context) ? e.context : undefined;
+    const wait = retryAfterMs(retryAfter, nowMs);
+    return errorFromServer(code, message, {
+        status,
+        ...(details ? { details } : {}),
+        ...(wait !== undefined ? { retryAfterMs: wait } : {}),
+    });
+}

package/dist/networks.d.ts

@@ -0,0 +1,5 @@
+import { type Eip155Network, type NetworkEntry } from "./schemes/eip155/index.js";
+/** The built-in production table. */
+export declare const BUILT_IN_NETWORKS: Readonly<Record<string, Eip155Network>>;
+/** The checked table: the built-in one with `networks` merged over it, then `rpcUrls` applied. */
+export declare function networkTable(networks: Record<string, Eip155Network> | undefined, rpcUrls: Record<string, string[]> | undefined, builtIn?: Readonly<Record<string, Eip155Network>>): ReadonlyMap<string, NetworkEntry>;

package/dist/networks.js

@@ -0,0 +1,46 @@
+/**
+ * The payment network table, pinned in the SDK: per CAIP-2 network, the escrow, the asset, its
+ * decimals and default public RPC URLs. Payments are checked against this table only, never
+ * against the server, so a compromised API cannot redirect them. Changing an address means a new
+ * SDK release.
+ *
+ * The built-in table holds the network Assay's production runs on today, Robinhood Chain testnet
+ * (`eip155:46630`), with two RPC hosts from different operators. A paid call or a bind on a
+ * network that is not in the table is refused with `PaymentNetworkUnknownError`.
+ *
+ * The `networks` option configures any chain from outside (a testnet, another deployment): its
+ * entries are merged over the built-in table, adding networks, and an entry for a network the
+ * table has replaces that entry whole (fields are never mixed from two deployments). `rpcUrls`
+ * replaces only a network's RPC URLs.
+ */
+import { eip155ChainId } from "./core/caip.js";
+import { isUsableRpcUrl } from "./core/chain.js";
+import { ConfigError } from "./errors.js";
+import { eip155Networks } from "./schemes/eip155/index.js";
+/** The built-in production table. */
+export const BUILT_IN_NETWORKS = Object.freeze({
+    "eip155:46630": Object.freeze({
+        chainId: 46630,
+        escrow: "eip155:46630:0x2723AD1fEC053Fe05305e4D0c874B0402959Ce18",
+        asset: "eip155:46630/erc20:0xDbbC156dD414f43f2c952C1Be0f16A0B9a826Cd3",
+        decimals: 6,
+        rpcUrls: Object.freeze([
+            "https://rpc.testnet.chain.robinhood.com",
+            "https://robinhood-sepolia-rpc.publicnode.com",
+        ]),
+    }),
+});
+/** The checked table: the built-in one with `networks` merged over it, then `rpcUrls` applied. */
+export function networkTable(networks, rpcUrls, builtIn = BUILT_IN_NETWORKS) {
+    const table = { ...builtIn, ...networks };
+    for (const [id, urls] of Object.entries(rpcUrls ?? {})) {
+        const ok = Array.isArray(urls) && urls.length > 0 && urls.every((u) => typeof u === "string" && isUsableRpcUrl(u));
+        if (eip155ChainId(id) === null || !ok) {
+            throw new ConfigError(`rpcUrls.${id} must be a non-empty list of https URLs for an eip155 network`);
+        }
+    }
+    const merged = {};
+    for (const [id, n] of Object.entries(table))
+        merged[id] = { ...n, rpcUrls: rpcUrls?.[id] ?? n.rpcUrls };
+    return eip155Networks(merged);
+}

package/dist/resources/context.d.ts

@@ -0,0 +1,48 @@
+import type { NetworkEntry } from "../schemes/eip155/index.js";
+import type { PaymentDetails, PaymentScheme } from "../schemes/types.js";
+import type { Http } from "../http.js";
+import type { McpTransport } from "../mcp.js";
+import type { RestClient } from "../rest.js";
+import type { Signer } from "../signer.js";
+import type { PriceQuote } from "../core/meta.js";
+/** The caller's hook before a voucher is signed. Return `false` to refuse; nothing is signed. */
+export type OnPayment = (details: PaymentDetails) => boolean | void | Promise<boolean | void>;
+/**
+ * What every resource module shares. One resource area = one module that takes this. A sibling
+ * client (`assay.at(url)`) gets a copy with its own `mcpUrl`, `mcp` and `quotes`; every other
+ * field is the same object, so the HTTP stack, signers, schemes (spend limits and ledger),
+ * `onPayment` and the in-flight map are shared.
+ */
+export interface ClientContext {
+    readonly http: Http;
+    /** The MCP URL this client sends to. May hold a link-only token: never print it unredacted. */
+    readonly mcpUrl: string;
+    readonly mcp: McpTransport;
+    readonly api: RestClient;
+    readonly signers: readonly Signer[];
+    readonly schemes: ReadonlyMap<string, PaymentScheme>;
+    readonly networks: ReadonlyMap<string, NetworkEntry>;
+    /** The web app origin, where a person approves a payment key. */
+    readonly webOrigin: string;
+    /** Logical calls in flight, by idempotency key (one voucher per logical call). */
+    readonly inFlight: Map<string, {
+        fingerprint: string;
+        promise: Promise<unknown>;
+    }>;
+    readonly quotes: QuoteCache;
+    readonly onPayment: OnPayment | undefined;
+    readonly maxRetries: number;
+    readonly now: () => number;
+    readonly sleep: (ms: number) => Promise<void>;
+}
+/**
+ * G3's quotes, as seen in `tools/list`, `search_tools` and `get_tool` results, kept 60 s per tool.
+ * One cache per MCP URL: the same tool can quote differently on two URLs (entry rules).
+ */
+export declare class QuoteCache {
+    #private;
+    private readonly now;
+    constructor(now: () => number);
+    set(tool: string, quote: PriceQuote): void;
+    get(tool: string): PriceQuote | null;
+}

package/dist/resources/context.js

@@ -0,0 +1,28 @@
+/**
+ * G3's quotes, as seen in `tools/list`, `search_tools` and `get_tool` results, kept 60 s per tool.
+ * One cache per MCP URL: the same tool can quote differently on two URLs (entry rules).
+ */
+export class QuoteCache {
+    now;
+    #entries = new Map();
+    constructor(now) {
+        this.now = now;
+    }
+    set(tool, quote) {
+        this.#entries.delete(tool);
+        this.#entries.set(tool, { quote: { ...quote }, at: this.now() });
+        if (this.#entries.size > 2048)
+            this.#entries.delete(this.#entries.keys().next().value);
+    }
+    get(tool) {
+        const e = this.#entries.get(tool);
+        if (!e)
+            return null;
+        const age = this.now() - e.at;
+        if (age < 0 || age > 60_000) {
+            this.#entries.delete(tool);
+            return null;
+        }
+        return { ...e.quote };
+    }
+}