@tabai/sdk 0.2.0

package/dist/http/metering-claim.js

@@ -0,0 +1,99 @@
+/**
+ * The metering claim: what a signed metered request binds, and who may sign it.
+ *
+ * ## Two signers, one digest
+ *
+ * A metered call records a delivery on chain and spends the Service operator's
+ * gas, so a metering endpoint anyone can reach must know the call was meant.
+ * Two parties can say so, and the digest they sign is the same string:
+ *
+ *   - **The operator**, from the Service's own front, which has authenticated
+ *     its caller however it likes. `Tab-Operator-Signature` carries it.
+ *   - **The Agent**, whose Open Tab the charge lands on. `Tab-Agent-Signature`
+ *     carries it, recovered against the address in `Tab-Agent`, so the one
+ *     party that pays for the call is the one that asked for it, and a
+ *     stranger who knows an Agent's address can put nothing on its tab.
+ *
+ * The digest binds the method, the path, the Agent, the tool, the unit count
+ * and a timestamp. Binding the Agent and the units is the point: a signature
+ * over the path alone would be a bearer token that replays against a
+ * different Agent for a different amount. The timestamp bounds replay to a
+ * window the gateway checks.
+ *
+ * ## Why it is written out and not JSON
+ *
+ * Newline-separated and fully ordered, so two different claims can never
+ * produce one digest. JSON key order is not guaranteed across
+ * implementations, and a signature over a reordered object would fail for a
+ * caller who did nothing wrong.
+ *
+ * Requirements: 12.1, 12.2, 21.5
+ */
+import { encodeBytes32String } from "ethers";
+/** The headers a signed metering request carries, by who signed it. */
+export const METERING_HEADER = {
+    operatorSignature: "Tab-Operator-Signature",
+    operatorIssuedAt: "Tab-Operator-Issued-At",
+    agentSignature: "Tab-Agent-Signature",
+    agentIssuedAt: "Tab-Agent-Issued-At",
+};
+/** The exact string a signer signs, with EIP-191 `personal_sign`. */
+export function meteringDigest(claim) {
+    return [
+        "tab-metering-request",
+        claim.method.toUpperCase(),
+        claim.path,
+        claim.agent.toLowerCase(),
+        claim.tool.toLowerCase(),
+        String(claim.units),
+        String(claim.issuedAt),
+    ].join("\n");
+}
+/** A tool name as the caller gave it, packed to the key the price list holds, unless it already is one. */
+export function toolKeyOf(tool) {
+    return (/^0x[0-9a-fA-F]{64}$/.test(tool) ? tool : encodeBytes32String(tool)).toLowerCase();
+}
+/**
+ * A header provider that signs every metered call as the Agent.
+ *
+ * Put it on a Service entry in `tab.config` and `tab_call` sends
+ * `Tab-Agent-Signature` and `Tab-Agent-Issued-At` with each call, signed by
+ * the key the factory returns. A factory, like the strategies, so the key is
+ * built only when a call is made and every read stays keyless; one that
+ * returns nothing sends the call unsigned, and a gateway that requires a
+ * signature says so in its refusal.
+ *
+ * It signs only when the key it is given is the Agent the call is metered
+ * against, because that is what the gateway recovers the signature against.
+ * A key for anyone else adds nothing and the Service decides: one that
+ * requires a signature refuses by name, and one that does not is unaffected.
+ * That is the case where the Agent comes from somewhere other than this
+ * config, such as a wallet the MetaMask Agent Wallet plugin reads, and it is
+ * an honest "this key is not that Agent" rather than a signature that could
+ * only be rejected.
+ */
+export function agentSignedMetering(signer, options = {}) {
+    const now = options.now ?? (() => Date.now());
+    return async (request) => {
+        const wallet = signer();
+        if (wallet === undefined)
+            return {};
+        const address = (await wallet.getAddress()).toLowerCase();
+        if (address !== request.agent.toLowerCase())
+            return {};
+        const issuedAt = now();
+        const digest = meteringDigest({
+            method: request.method,
+            path: new URL(request.url).pathname,
+            agent: address,
+            tool: toolKeyOf(request.tool),
+            units: 1,
+            issuedAt,
+        });
+        return {
+            [METERING_HEADER.agentSignature]: await wallet.signMessage(digest),
+            [METERING_HEADER.agentIssuedAt]: String(issuedAt),
+        };
+    };
+}
+//# sourceMappingURL=metering-claim.js.map

package/dist/http/metering-claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metering-claim.js","sourceRoot":"","sources":["../../src/http/metering-claim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAI7C,uEAAuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,iBAAiB,EAAE,wBAAwB;IAC3C,gBAAgB,EAAE,wBAAwB;IAC1C,cAAc,EAAE,qBAAqB;IACrC,aAAa,EAAE,qBAAqB;CAC5B,CAAC;AAcX,qEAAqE;AACrE,MAAM,UAAU,cAAc,CAAC,KAA2B;IACxD,OAAO;QACL,sBAAsB;QACtB,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE;QAC1B,KAAK,CAAC,IAAI;QACV,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE;QACzB,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE;QACxB,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;QACnB,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC;KACvB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAQD,2GAA2G;AAC3G,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AAC7F,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAwC,EACxC,UAA2C,EAAE;IAE7C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9C,OAAO,KAAK,EAAE,OAA6B,EAAE,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;QACxB,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC1D,IAAI,OAAO,KAAK,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE;YAAE,OAAO,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,cAAc,CAAC;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,IAAI,EAAE,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ;YACnC,KAAK,EAAE,OAAO;YACd,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;YAC7B,KAAK,EAAE,CAAC;YACR,QAAQ;SACT,CAAC,CAAC;QACH,OAAO;YACL,CAAC,eAAe,CAAC,cAAc,CAAC,EAAE,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;YAClE,CAAC,eAAe,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;SAClD,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The metering claim: what a signed metered request binds, and who may sign it.\n *\n * ## Two signers, one digest\n *\n * A metered call records a delivery on chain and spends the Service operator's\n * gas, so a metering endpoint anyone can reach must know the call was meant.\n * Two parties can say so, and the digest they sign is the same string:\n *\n *   - **The operator**, from the Service's own front, which has authenticated\n *     its caller however it likes. `Tab-Operator-Signature` carries it.\n *   - **The Agent**, whose Open Tab the charge lands on. `Tab-Agent-Signature`\n *     carries it, recovered against the address in `Tab-Agent`, so the one\n *     party that pays for the call is the one that asked for it, and a\n *     stranger who knows an Agent's address can put nothing on its tab.\n *\n * The digest binds the method, the path, the Agent, the tool, the unit count\n * and a timestamp. Binding the Agent and the units is the point: a signature\n * over the path alone would be a bearer token that replays against a\n * different Agent for a different amount. The timestamp bounds replay to a\n * window the gateway checks.\n *\n * ## Why it is written out and not JSON\n *\n * Newline-separated and fully ordered, so two different claims can never\n * produce one digest. JSON key order is not guaranteed across\n * implementations, and a signature over a reordered object would fail for a\n * caller who did nothing wrong.\n *\n * Requirements: 12.1, 12.2, 21.5\n */\n\nimport { encodeBytes32String } from \"ethers\";\n\nimport type { ServiceHeaderProvider, ServiceHeaderRequest } from \"../payments/config.js\";\n\n/** The headers a signed metering request carries, by who signed it. */\nexport const METERING_HEADER = {\n  operatorSignature: \"Tab-Operator-Signature\",\n  operatorIssuedAt: \"Tab-Operator-Issued-At\",\n  agentSignature: \"Tab-Agent-Signature\",\n  agentIssuedAt: \"Tab-Agent-Issued-At\",\n} as const;\n\n/** The fields a metering request signature binds. */\nexport interface MeteringRequestClaim {\n  readonly method: string;\n  readonly path: string;\n  readonly agent: string;\n  /** The 32-byte tool key the price list is keyed by, never the label. */\n  readonly tool: string;\n  readonly units: number;\n  /** Milliseconds since the epoch, as the caller stated it. */\n  readonly issuedAt: number;\n}\n\n/** The exact string a signer signs, with EIP-191 `personal_sign`. */\nexport function meteringDigest(claim: MeteringRequestClaim): string {\n  return [\n    \"tab-metering-request\",\n    claim.method.toUpperCase(),\n    claim.path,\n    claim.agent.toLowerCase(),\n    claim.tool.toLowerCase(),\n    String(claim.units),\n    String(claim.issuedAt),\n  ].join(\"\\n\");\n}\n\n/** A signer that can `personal_sign`. An ethers `Wallet` satisfies it. */\nexport interface MeteringSigner {\n  getAddress(): Promise<string>;\n  signMessage(message: string): Promise<string>;\n}\n\n/** A tool name as the caller gave it, packed to the key the price list holds, unless it already is one. */\nexport function toolKeyOf(tool: string): string {\n  return (/^0x[0-9a-fA-F]{64}$/.test(tool) ? tool : encodeBytes32String(tool)).toLowerCase();\n}\n\n/**\n * A header provider that signs every metered call as the Agent.\n *\n * Put it on a Service entry in `tab.config` and `tab_call` sends\n * `Tab-Agent-Signature` and `Tab-Agent-Issued-At` with each call, signed by\n * the key the factory returns. A factory, like the strategies, so the key is\n * built only when a call is made and every read stays keyless; one that\n * returns nothing sends the call unsigned, and a gateway that requires a\n * signature says so in its refusal.\n *\n * It signs only when the key it is given is the Agent the call is metered\n * against, because that is what the gateway recovers the signature against.\n * A key for anyone else adds nothing and the Service decides: one that\n * requires a signature refuses by name, and one that does not is unaffected.\n * That is the case where the Agent comes from somewhere other than this\n * config, such as a wallet the MetaMask Agent Wallet plugin reads, and it is\n * an honest \"this key is not that Agent\" rather than a signature that could\n * only be rejected.\n */\nexport function agentSignedMetering(\n  signer: () => MeteringSigner | undefined,\n  options: { readonly now?: () => number } = {},\n): ServiceHeaderProvider {\n  const now = options.now ?? (() => Date.now());\n  return async (request: ServiceHeaderRequest) => {\n    const wallet = signer();\n    if (wallet === undefined) return {};\n    const address = (await wallet.getAddress()).toLowerCase();\n    if (address !== request.agent.toLowerCase()) return {};\n    const issuedAt = now();\n    const digest = meteringDigest({\n      method: request.method,\n      path: new URL(request.url).pathname,\n      agent: address,\n      tool: toolKeyOf(request.tool),\n      units: 1,\n      issuedAt,\n    });\n    return {\n      [METERING_HEADER.agentSignature]: await wallet.signMessage(digest),\n      [METERING_HEADER.agentIssuedAt]: String(issuedAt),\n    };\n  };\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `@tabai/sdk` is the published client surface. It may draw on `./_shared/index.js`
+ * and on nothing else inside the workspace.
+ *
+ * Three surfaces, and the shape of the product is visible in how they relate:
+ *
+ * - **`payments/`** - the strategy seam. The interface a Settlement goes through,
+ *   the Monad strategy this package ships, and the three ways a consumer adds a
+ *   strategy of their own without editing a file in here (R23.1, R23.6).
+ * - **`http/`**, the wire contract and the Agent's side of it. `headers.ts` is the
+ *   single definition of the `Tab-*` format, and `client-402.ts` is the post-paid
+ *   402 client that reads it (R23.2).
+ * - **`server/`**, the Service's side. `tabPostPaid` accrues after a delivery and
+ *   never withholds a response, with adapters for Hono, Express, and Next.js
+ *   (R23.3).
+ * - **`proxy/`** - the Service's front door. `createTabProxy` forwards a request
+ *   upstream under the metering plugin and runs hooks around it (R23.4), and a
+ *   hook can attach the Settlement that covers a proxied request (R23.5).
+ * - **`x402/`** - the prepaid protocol beside the credit one. A Tab `402` can
+ *   offer an x402 payment for the one call it refused, an Agent with an x402
+ *   signer can take it, and a Service can front an x402 upstream and meter the
+ *   Agent for what it paid.
+ *
+ * **`http/headers.ts` is deliberately the only place the wire format exists.** The
+ * client parses with it and the server formats with it, so the two halves cannot
+ * drift apart without a test failing in one file, rather than mis-parsing silently
+ * between two.
+ *
+ * Nothing exported from this package throws. Every fallible call returns a
+ * `Result` from `./_shared/index.js` (R21.5). The one exception is named and deliberate:
+ * the Hono and Next.js adapters re-raise a handler's own thrown value, because a
+ * framework's contract for a failed handler is an exception and the adapter is the
+ * boundary where a `Result` becomes whatever the host expects.
+ */
+export declare const WORKSPACE_ID_SDK: "@tabai/sdk";
+export declare const SHARED_WORKSPACE_ID: "./_shared/index.js";
+export { ok, err, wrap, causeOf } from "./_shared/index.js";
+export type { Result, TabError, ErrorCategory, Address, Bytes32, Hex } from "./_shared/index.js";
+export * from "./logger.js";
+export * from "./errors.js";
+export * from "./payments/index.js";
+export * from "./http/index.js";
+export * from "./server/index.js";
+export * from "./proxy/index.js";
+export * from "./x402/index.js";
+export * from "./mcp/index.js";
+export * from "./cli/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,eAAO,MAAM,gBAAgB,EAAG,YAAqB,CAAC;AAEtD,eAAO,MAAM,mBAAmB,iBAAe,CAAC;AAKhD,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAE5F,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,51 @@
+/**
+ * `@tabai/sdk` is the published client surface. It may draw on `./_shared/index.js`
+ * and on nothing else inside the workspace.
+ *
+ * Three surfaces, and the shape of the product is visible in how they relate:
+ *
+ * - **`payments/`** - the strategy seam. The interface a Settlement goes through,
+ *   the Monad strategy this package ships, and the three ways a consumer adds a
+ *   strategy of their own without editing a file in here (R23.1, R23.6).
+ * - **`http/`**, the wire contract and the Agent's side of it. `headers.ts` is the
+ *   single definition of the `Tab-*` format, and `client-402.ts` is the post-paid
+ *   402 client that reads it (R23.2).
+ * - **`server/`**, the Service's side. `tabPostPaid` accrues after a delivery and
+ *   never withholds a response, with adapters for Hono, Express, and Next.js
+ *   (R23.3).
+ * - **`proxy/`** - the Service's front door. `createTabProxy` forwards a request
+ *   upstream under the metering plugin and runs hooks around it (R23.4), and a
+ *   hook can attach the Settlement that covers a proxied request (R23.5).
+ * - **`x402/`** - the prepaid protocol beside the credit one. A Tab `402` can
+ *   offer an x402 payment for the one call it refused, an Agent with an x402
+ *   signer can take it, and a Service can front an x402 upstream and meter the
+ *   Agent for what it paid.
+ *
+ * **`http/headers.ts` is deliberately the only place the wire format exists.** The
+ * client parses with it and the server formats with it, so the two halves cannot
+ * drift apart without a test failing in one file, rather than mis-parsing silently
+ * between two.
+ *
+ * Nothing exported from this package throws. Every fallible call returns a
+ * `Result` from `./_shared/index.js` (R21.5). The one exception is named and deliberate:
+ * the Hono and Next.js adapters re-raise a handler's own thrown value, because a
+ * framework's contract for a failed handler is an exception and the adapter is the
+ * boundary where a `Result` becomes whatever the host expects.
+ */
+import { WORKSPACE_ID } from "./_shared/index.js";
+export const WORKSPACE_ID_SDK = "@tabai/sdk";
+export const SHARED_WORKSPACE_ID = WORKSPACE_ID;
+// Every fallible call returns a `Result`, so a consumer needs its type and its
+// constructors from the package it installed; `./_shared/index.js` is inlined at pack
+// time and has no name on npm to import them from.
+export { ok, err, wrap, causeOf } from "./_shared/index.js";
+export * from "./logger.js";
+export * from "./errors.js";
+export * from "./payments/index.js";
+export * from "./http/index.js";
+export * from "./server/index.js";
+export * from "./proxy/index.js";
+export * from "./x402/index.js";
+export * from "./mcp/index.js";
+export * from "./cli/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAqB,CAAC;AAEtD,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAEhD,+EAA+E;AAC/E,iFAAiF;AACjF,mDAAmD;AACnD,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAGvD,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC","sourcesContent":["/**\n * `@tabai/sdk` is the published client surface. It may draw on `./_shared/index.js`\n * and on nothing else inside the workspace.\n *\n * Three surfaces, and the shape of the product is visible in how they relate:\n *\n * - **`payments/`** - the strategy seam. The interface a Settlement goes through,\n *   the Monad strategy this package ships, and the three ways a consumer adds a\n *   strategy of their own without editing a file in here (R23.1, R23.6).\n * - **`http/`**, the wire contract and the Agent's side of it. `headers.ts` is the\n *   single definition of the `Tab-*` format, and `client-402.ts` is the post-paid\n *   402 client that reads it (R23.2).\n * - **`server/`**, the Service's side. `tabPostPaid` accrues after a delivery and\n *   never withholds a response, with adapters for Hono, Express, and Next.js\n *   (R23.3).\n * - **`proxy/`** - the Service's front door. `createTabProxy` forwards a request\n *   upstream under the metering plugin and runs hooks around it (R23.4), and a\n *   hook can attach the Settlement that covers a proxied request (R23.5).\n * - **`x402/`** - the prepaid protocol beside the credit one. A Tab `402` can\n *   offer an x402 payment for the one call it refused, an Agent with an x402\n *   signer can take it, and a Service can front an x402 upstream and meter the\n *   Agent for what it paid.\n *\n * **`http/headers.ts` is deliberately the only place the wire format exists.** The\n * client parses with it and the server formats with it, so the two halves cannot\n * drift apart without a test failing in one file, rather than mis-parsing silently\n * between two.\n *\n * Nothing exported from this package throws. Every fallible call returns a\n * `Result` from `./_shared/index.js` (R21.5). The one exception is named and deliberate:\n * the Hono and Next.js adapters re-raise a handler's own thrown value, because a\n * framework's contract for a failed handler is an exception and the adapter is the\n * boundary where a `Result` becomes whatever the host expects.\n */\n\nimport { WORKSPACE_ID } from \"./_shared/index.js\";\n\nexport const WORKSPACE_ID_SDK = \"@tabai/sdk\" as const;\n\nexport const SHARED_WORKSPACE_ID = WORKSPACE_ID;\n\n// Every fallible call returns a `Result`, so a consumer needs its type and its\n// constructors from the package it installed; `./_shared/index.js` is inlined at pack\n// time and has no name on npm to import them from.\nexport { ok, err, wrap, causeOf } from \"./_shared/index.js\";\nexport type { Result, TabError, ErrorCategory, Address, Bytes32, Hex } from \"./_shared/index.js\";\n\nexport * from \"./logger.js\";\nexport * from \"./errors.js\";\nexport * from \"./payments/index.js\";\nexport * from \"./http/index.js\";\nexport * from \"./server/index.js\";\nexport * from \"./proxy/index.js\";\nexport * from \"./x402/index.js\";\nexport * from \"./mcp/index.js\";\nexport * from \"./cli/index.js\";\n"]}

package/dist/logger.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The SDK logger.
+ *
+ * The seam needs somewhere to put a warning that is not an error: a duplicate
+ * strategy id replaces the earlier registration rather than throwing, and a
+ * consumer has to be able to see that happen without the SDK deciding for them
+ * that it deserves a crash. Design section 9.3 names the behaviour; this is the
+ * sink it writes to.
+ *
+ * The interface is four methods and one optional field bag, so a consumer can
+ * hand in `pino`, `winston`, or a closure over an array in a test without an
+ * adapter. Nothing here formats, filters, or buffers.
+ *
+ * Requirements: 23.6
+ */
+/** Structured fields attached to one log line. Values are rendered by the sink. */
+export type LogFields = Record<string, unknown>;
+export interface Logger {
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+}
+/** Discards every line. The right default inside a library test. */
+export declare const silentLogger: Logger;
+/**
+ * Writes to the host console, prefixing every line with `tab:` so a Service
+ * operator can tell an SDK line from their own.
+ */
+export declare const consoleLogger: Logger;
+/**
+ * The logger used when a caller supplies none.
+ *
+ * The console rather than silence, because the one thing this sink exists to
+ * carry, a strategy registration that replaced another, is invisible
+ * otherwise, and a silently swapped payment strategy is the kind of surprise
+ * that costs money.
+ */
+export declare const defaultLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAClD;AAED,oEAAoE;AACpE,eAAO,MAAM,YAAY,EAAE,MAK1B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAK3B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,MAAsB,CAAC"}

package/dist/logger.js

@@ -0,0 +1,50 @@
+/**
+ * The SDK logger.
+ *
+ * The seam needs somewhere to put a warning that is not an error: a duplicate
+ * strategy id replaces the earlier registration rather than throwing, and a
+ * consumer has to be able to see that happen without the SDK deciding for them
+ * that it deserves a crash. Design section 9.3 names the behaviour; this is the
+ * sink it writes to.
+ *
+ * The interface is four methods and one optional field bag, so a consumer can
+ * hand in `pino`, `winston`, or a closure over an array in a test without an
+ * adapter. Nothing here formats, filters, or buffers.
+ *
+ * Requirements: 23.6
+ */
+/** Discards every line. The right default inside a library test. */
+export const silentLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/**
+ * Writes to the host console, prefixing every line with `tab:` so a Service
+ * operator can tell an SDK line from their own.
+ */
+export const consoleLogger = {
+    debug: (message, fields) => emit("debug", message, fields),
+    info: (message, fields) => emit("info", message, fields),
+    warn: (message, fields) => emit("warn", message, fields),
+    error: (message, fields) => emit("error", message, fields),
+};
+/**
+ * The logger used when a caller supplies none.
+ *
+ * The console rather than silence, because the one thing this sink exists to
+ * carry, a strategy registration that replaced another, is invisible
+ * otherwise, and a silently swapped payment strategy is the kind of surprise
+ * that costs money.
+ */
+export const defaultLogger = consoleLogger;
+function emit(level, message, fields) {
+    const line = `tab: ${message}`;
+    if (fields === undefined) {
+        console[level](line);
+        return;
+    }
+    console[level](line, fields);
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH,oEAAoE;AACpE,MAAM,CAAC,MAAM,YAAY,GAAW;IAClC,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;IACf,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAW;IACnC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;IAC1D,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC;IACxD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC;IACxD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;CAC3D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAW,aAAa,CAAC;AAEnD,SAAS,IAAI,CAAC,KAA0C,EAAE,OAAe,EAAE,MAAkB;IAC3F,MAAM,IAAI,GAAG,QAAQ,OAAO,EAAE,CAAC;IAC/B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC/B,CAAC","sourcesContent":["/**\n * The SDK logger.\n *\n * The seam needs somewhere to put a warning that is not an error: a duplicate\n * strategy id replaces the earlier registration rather than throwing, and a\n * consumer has to be able to see that happen without the SDK deciding for them\n * that it deserves a crash. Design section 9.3 names the behaviour; this is the\n * sink it writes to.\n *\n * The interface is four methods and one optional field bag, so a consumer can\n * hand in `pino`, `winston`, or a closure over an array in a test without an\n * adapter. Nothing here formats, filters, or buffers.\n *\n * Requirements: 23.6\n */\n\n/** Structured fields attached to one log line. Values are rendered by the sink. */\nexport type LogFields = Record<string, unknown>;\n\nexport interface Logger {\n  debug(message: string, fields?: LogFields): void;\n  info(message: string, fields?: LogFields): void;\n  warn(message: string, fields?: LogFields): void;\n  error(message: string, fields?: LogFields): void;\n}\n\n/** Discards every line. The right default inside a library test. */\nexport const silentLogger: Logger = {\n  debug: () => {},\n  info: () => {},\n  warn: () => {},\n  error: () => {},\n};\n\n/**\n * Writes to the host console, prefixing every line with `tab:` so a Service\n * operator can tell an SDK line from their own.\n */\nexport const consoleLogger: Logger = {\n  debug: (message, fields) => emit(\"debug\", message, fields),\n  info: (message, fields) => emit(\"info\", message, fields),\n  warn: (message, fields) => emit(\"warn\", message, fields),\n  error: (message, fields) => emit(\"error\", message, fields),\n};\n\n/**\n * The logger used when a caller supplies none.\n *\n * The console rather than silence, because the one thing this sink exists to\n * carry, a strategy registration that replaced another, is invisible\n * otherwise, and a silently swapped payment strategy is the kind of surprise\n * that costs money.\n */\nexport const defaultLogger: Logger = consoleLogger;\n\nfunction emit(level: \"debug\" | \"info\" | \"warn\" | \"error\", message: string, fields?: LogFields): void {\n  const line = `tab: ${message}`;\n  if (fields === undefined) {\n    console[level](line);\n    return;\n  }\n  console[level](line, fields);\n}\n"]}

package/dist/mcp/assets.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Assets at the MCP boundary.
+ *
+ * An Asset is named to a model as `<chainId>:<address>`, the same shape the
+ * `Tab-Charge-Asset` header carries, so the string a tool result shows is the
+ * string a tool argument accepts. `TabBook` keys an Asset by token address alone;
+ * the chain id travels with it here because the SDK can be pointed at Monad
+ * Mainnet or Monad Testnet and a bare address is ambiguous between the two.
+ *
+ * The canonical stablecoins are known by symbol and decimals. Any other address
+ * is still a valid Asset, it is just one this SDK has no facts about, and the
+ * tool results say so rather than guessing.
+ */
+import type { Address, Result } from "../_shared/index.js";
+import type { AssetRef } from "../payments/strategy.js";
+export type AssetString = string;
+export interface AssetFacts {
+    readonly chainId: number;
+    readonly address: Address;
+    readonly symbol: string | null;
+    readonly decimals: number | null;
+    /** True when the address is a canonical stablecoin on that chain, or a configured test token. */
+    readonly curatedAsset: boolean;
+}
+export declare const formatAsset: (chainId: bigint | number, address: string) => AssetString;
+export declare const assetStringOf: (asset: AssetRef) => AssetString;
+/** The chain ids this SDK knows how to describe. */
+export declare const KNOWN_CHAIN_IDS: readonly [143, 10143];
+export declare function parseAsset(value: unknown, label?: string, env?: NodeJS.ProcessEnv): Result<AssetRef>;
+export declare function assetFacts(chainId: bigint | number, address: string, env?: NodeJS.ProcessEnv): AssetFacts;
+//# sourceMappingURL=assets.d.ts.map

package/dist/mcp/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../src/mcp/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iGAAiG;IACjG,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,GAAG,MAAM,EAAE,SAAS,MAAM,KAAG,WACzB,CAAC;AAEhD,eAAO,MAAM,aAAa,GAAI,OAAO,QAAQ,KAAG,WAAwD,CAAC;AAEzG,oDAAoD;AACpD,eAAO,MAAM,eAAe,uBAA0D,CAAC;AA6BvF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAU,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,QAAQ,CAAC,CA2ClH;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,UAAU,CAQtH"}

package/dist/mcp/assets.js

@@ -0,0 +1,78 @@
+import { MAINNET_ASSETS, MONAD_MAINNET, MONAD_TESTNET, TESTNET_ASSETS, isAddress, ok } from "../_shared/index.js";
+import { validationError } from "../errors.js";
+export const formatAsset = (chainId, address) => `${String(chainId)}:${address.toLowerCase()}`;
+export const assetStringOf = (asset) => formatAsset(asset.chainId, asset.address);
+/** The chain ids this SDK knows how to describe. */
+export const KNOWN_CHAIN_IDS = [MONAD_MAINNET.chainId, MONAD_TESTNET.chainId];
+/**
+ * The stablecoins this SDK can name, per chain. On Testnet that is Circle's
+ * USDC from the shared table plus the mock token the deployment shipped, read
+ * from `MOCK_USDC_ADDRESS`. The mock is named `mUSDC` here although its own
+ * `symbol()` says `USDC`, because a Service that accepts both must show two
+ * Assets and not one word twice.
+ */
+function knownAssets(chainId, env) {
+    if (chainId === MONAD_MAINNET.chainId) {
+        return Object.values(MAINNET_ASSETS).map((asset) => ({
+            address: asset.address.toLowerCase(),
+            symbol: asset.symbol,
+            decimals: asset.decimals,
+        }));
+    }
+    if (chainId === MONAD_TESTNET.chainId) {
+        const known = Object.values(TESTNET_ASSETS).map((asset) => ({
+            address: asset.address.toLowerCase(),
+            symbol: asset.symbol,
+            decimals: asset.decimals,
+        }));
+        const mock = env["MOCK_USDC_ADDRESS"];
+        return mock !== undefined && isAddress(mock) ? [...known, { address: mock.toLowerCase(), symbol: "mUSDC", decimals: 6 }] : known;
+    }
+    return [];
+}
+export function parseAsset(value, label = "asset", env = process.env) {
+    if (typeof value !== "string") {
+        return validationError("ASSET_MALFORMED", `${label} must be a string of the form chainId:tokenAddress, received ${typeof value}`, {
+            details: { label },
+        });
+    }
+    const colon = value.indexOf(":");
+    if (colon <= 0) {
+        return validationError("ASSET_MALFORMED", `${label} must be chainId:tokenAddress, for example 143:${MAINNET_ASSETS.USDC.address.toLowerCase()}, received \`${value}\``, { details: { label, value } });
+    }
+    const rawChainId = value.slice(0, colon);
+    const rawAddress = value.slice(colon + 1);
+    if (!/^[0-9]+$/.test(rawChainId)) {
+        return validationError("ASSET_CHAIN_ID_MALFORMED", `${label} must start with a decimal chain id, received \`${rawChainId}\``, {
+            details: { label, chainId: rawChainId },
+        });
+    }
+    if (!isAddress(rawAddress)) {
+        return validationError("ASSET_ADDRESS_MALFORMED", `${label} must end in a 20-byte 0x address, received \`${rawAddress}\``, {
+            details: { label, address: rawAddress },
+        });
+    }
+    const chainId = Number(rawChainId);
+    if (!KNOWN_CHAIN_IDS.includes(chainId)) {
+        return validationError("ASSET_CHAIN_UNSUPPORTED", `chain id ${rawChainId} is not a Monad network; the supported ids are ${KNOWN_CHAIN_IDS.join(" and ")}`, { details: { label, chainId: rawChainId, supported: KNOWN_CHAIN_IDS.join(", ") } });
+    }
+    const facts = assetFacts(chainId, rawAddress, env);
+    return ok({
+        chainId: BigInt(chainId),
+        address: rawAddress.toLowerCase(),
+        // An unknown token is assumed to be a six-decimal stablecoin, which is what
+        // every Asset Tab settles in. The facts say when that is a guess.
+        decimals: facts.decimals ?? 6,
+        symbol: facts.symbol ?? "TOKEN",
+    });
+}
+export function assetFacts(chainId, address, env = process.env) {
+    const lowered = address.toLowerCase();
+    const numeric = typeof chainId === "bigint" ? Number(chainId) : chainId;
+    const known = knownAssets(numeric, env).find((asset) => asset.address === lowered);
+    if (known !== undefined) {
+        return { chainId: numeric, address: lowered, symbol: known.symbol, decimals: known.decimals, curatedAsset: true };
+    }
+    return { chainId: numeric, address: lowered, symbol: null, decimals: null, curatedAsset: false };
+}
+//# sourceMappingURL=assets.js.map

package/dist/mcp/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../src/mcp/assets.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Assets at the MCP boundary.\n *\n * An Asset is named to a model as `<chainId>:<address>`, the same shape the\n * `Tab-Charge-Asset` header carries, so the string a tool result shows is the\n * string a tool argument accepts. `TabBook` keys an Asset by token address alone;\n * the chain id travels with it here because the SDK can be pointed at Monad\n * Mainnet or Monad Testnet and a bare address is ambiguous between the two.\n *\n * The canonical stablecoins are known by symbol and decimals. Any other address\n * is still a valid Asset, it is just one this SDK has no facts about, and the\n * tool results say so rather than guessing.\n */\nimport type { Address, Result } from \"../_shared/index.js\";\nimport { MAINNET_ASSETS, MONAD_MAINNET, MONAD_TESTNET, TESTNET_ASSETS, isAddress, ok } from \"../_shared/index.js\";\nimport { validationError } from \"../errors.js\";\nimport type { AssetRef } from \"../payments/strategy.js\";\n\nexport type AssetString = string;\n\nexport interface AssetFacts {\n  readonly chainId: number;\n  readonly address: Address;\n  readonly symbol: string | null;\n  readonly decimals: number | null;\n  /** True when the address is a canonical stablecoin on that chain, or a configured test token. */\n  readonly curatedAsset: boolean;\n}\n\nexport const formatAsset = (chainId: bigint | number, address: string): AssetString =>\n  `${String(chainId)}:${address.toLowerCase()}`;\n\nexport const assetStringOf = (asset: AssetRef): AssetString => formatAsset(asset.chainId, asset.address);\n\n/** The chain ids this SDK knows how to describe. */\nexport const KNOWN_CHAIN_IDS = [MONAD_MAINNET.chainId, MONAD_TESTNET.chainId] as const;\n\n/**\n * The stablecoins this SDK can name, per chain. On Testnet that is Circle's\n * USDC from the shared table plus the mock token the deployment shipped, read\n * from `MOCK_USDC_ADDRESS`. The mock is named `mUSDC` here although its own\n * `symbol()` says `USDC`, because a Service that accepts both must show two\n * Assets and not one word twice.\n */\nfunction knownAssets(chainId: number, env: NodeJS.ProcessEnv): readonly { address: string; symbol: string; decimals: number }[] {\n  if (chainId === MONAD_MAINNET.chainId) {\n    return Object.values(MAINNET_ASSETS).map((asset) => ({\n      address: asset.address.toLowerCase(),\n      symbol: asset.symbol,\n      decimals: asset.decimals,\n    }));\n  }\n  if (chainId === MONAD_TESTNET.chainId) {\n    const known = Object.values(TESTNET_ASSETS).map((asset) => ({\n      address: asset.address.toLowerCase(),\n      symbol: asset.symbol,\n      decimals: asset.decimals,\n    }));\n    const mock = env[\"MOCK_USDC_ADDRESS\"];\n    return mock !== undefined && isAddress(mock) ? [...known, { address: mock.toLowerCase(), symbol: \"mUSDC\", decimals: 6 }] : known;\n  }\n  return [];\n}\n\nexport function parseAsset(value: unknown, label = \"asset\", env: NodeJS.ProcessEnv = process.env): Result<AssetRef> {\n  if (typeof value !== \"string\") {\n    return validationError(\"ASSET_MALFORMED\", `${label} must be a string of the form chainId:tokenAddress, received ${typeof value}`, {\n      details: { label },\n    });\n  }\n  const colon = value.indexOf(\":\");\n  if (colon <= 0) {\n    return validationError(\n      \"ASSET_MALFORMED\",\n      `${label} must be chainId:tokenAddress, for example 143:${MAINNET_ASSETS.USDC.address.toLowerCase()}, received \\`${value}\\``,\n      { details: { label, value } },\n    );\n  }\n  const rawChainId = value.slice(0, colon);\n  const rawAddress = value.slice(colon + 1);\n  if (!/^[0-9]+$/.test(rawChainId)) {\n    return validationError(\"ASSET_CHAIN_ID_MALFORMED\", `${label} must start with a decimal chain id, received \\`${rawChainId}\\``, {\n      details: { label, chainId: rawChainId },\n    });\n  }\n  if (!isAddress(rawAddress)) {\n    return validationError(\"ASSET_ADDRESS_MALFORMED\", `${label} must end in a 20-byte 0x address, received \\`${rawAddress}\\``, {\n      details: { label, address: rawAddress },\n    });\n  }\n  const chainId = Number(rawChainId);\n  if (!(KNOWN_CHAIN_IDS as readonly number[]).includes(chainId)) {\n    return validationError(\n      \"ASSET_CHAIN_UNSUPPORTED\",\n      `chain id ${rawChainId} is not a Monad network; the supported ids are ${KNOWN_CHAIN_IDS.join(\" and \")}`,\n      { details: { label, chainId: rawChainId, supported: KNOWN_CHAIN_IDS.join(\", \") } },\n    );\n  }\n  const facts = assetFacts(chainId, rawAddress, env);\n  return ok({\n    chainId: BigInt(chainId),\n    address: rawAddress.toLowerCase() as Address,\n    // An unknown token is assumed to be a six-decimal stablecoin, which is what\n    // every Asset Tab settles in. The facts say when that is a guess.\n    decimals: facts.decimals ?? 6,\n    symbol: facts.symbol ?? \"TOKEN\",\n  });\n}\n\nexport function assetFacts(chainId: bigint | number, address: string, env: NodeJS.ProcessEnv = process.env): AssetFacts {\n  const lowered = address.toLowerCase() as Address;\n  const numeric = typeof chainId === \"bigint\" ? Number(chainId) : chainId;\n  const known = knownAssets(numeric, env).find((asset) => asset.address === lowered);\n  if (known !== undefined) {\n    return { chainId: numeric, address: lowered, symbol: known.symbol, decimals: known.decimals, curatedAsset: true };\n  }\n  return { chainId: numeric, address: lowered, symbol: null, decimals: null, curatedAsset: false };\n}\n"]}

package/dist/mcp/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The MCP surface: four tools, their declared schemas, and the server that
+ * serves them. (R25.1, R25.2, R25.3)
+ *
+ * `tab_discover` finds Services, `tab_call` uses one and is metered onto the
+ * Agent's Open Tab, `tab_status` reports what the Agent owes and may still
+ * spend, and `tab_settle` pays it down. Three of the four are keyless reads.
+ * Only `tab_settle` signs, and it signs through the same payment-strategy seam
+ * the rest of this package settles through.
+ */
+export * from "./json-schema.js";
+export * from "./schemas.js";
+export * from "./assets.js";
+export * from "./json.js";
+export * from "./registry-client.js";
+export * from "./settings.js";
+export * from "./toolset.js";
+export * from "./server.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,19 @@
+/**
+ * The MCP surface: four tools, their declared schemas, and the server that
+ * serves them. (R25.1, R25.2, R25.3)
+ *
+ * `tab_discover` finds Services, `tab_call` uses one and is metered onto the
+ * Agent's Open Tab, `tab_status` reports what the Agent owes and may still
+ * spend, and `tab_settle` pays it down. Three of the four are keyless reads.
+ * Only `tab_settle` signs, and it signs through the same payment-strategy seam
+ * the rest of this package settles through.
+ */
+export * from "./json-schema.js";
+export * from "./schemas.js";
+export * from "./assets.js";
+export * from "./json.js";
+export * from "./registry-client.js";
+export * from "./settings.js";
+export * from "./toolset.js";
+export * from "./server.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC","sourcesContent":["/**\n * The MCP surface: four tools, their declared schemas, and the server that\n * serves them. (R25.1, R25.2, R25.3)\n *\n * `tab_discover` finds Services, `tab_call` uses one and is metered onto the\n * Agent's Open Tab, `tab_status` reports what the Agent owes and may still\n * spend, and `tab_settle` pays it down. Three of the four are keyless reads.\n * Only `tab_settle` signs, and it signs through the same payment-strategy seam\n * the rest of this package settles through.\n */\n\nexport * from \"./json-schema.js\";\nexport * from \"./schemas.js\";\nexport * from \"./assets.js\";\nexport * from \"./json.js\";\nexport * from \"./registry-client.js\";\nexport * from \"./settings.js\";\nexport * from \"./toolset.js\";\nexport * from \"./server.js\";\n"]}

package/dist/mcp/json-schema.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The JSON Schema subset the MCP tools declare, and a validator for it.
+ *
+ * ## Why this is written here rather than pulled in
+ *
+ * An MCP tool declares its input and output shape as JSON Schema, and a model
+ * reads that declaration to decide what to send. A declaration nothing enforces
+ * is a promise, not a contract: the first tool that accepts an out-of-range
+ * `limit` or emits an amount as a `number` has broken the schema its caller was
+ * reasoning against, and nothing in the process notices. So the four tools in
+ * this package validate every input against the schema they publish, and the
+ * test suite validates every output against the schema they publish (task 16.3).
+ *
+ * The validator is 200 lines rather than a dependency because the schemas here
+ * use ten keywords between them, this package adds no dependency for the MCP
+ * surface, and a validator whose supported keyword set is visible in one file
+ * cannot silently ignore a keyword a schema relies on. {@link validateJsonValue}
+ * fails loudly on a keyword it does not implement instead of passing the value,
+ * which is the property a hand-written validator has to have to be trustworthy.
+ *
+ * ## Everything returns a Result
+ *
+ * Nothing here throws, including on a malformed schema. A schema is authored in
+ * this package, so a bad one is a bug rather than input, but a bug that surfaces
+ * as an `INTERNAL` `Result` at a tool boundary is reported to the model as a
+ * failed call, and a bug that surfaces as a thrown value takes the stdio
+ * transport down with it.
+ *
+ * Requirements: 21.5, 25.1, 25.2
+ */
+import type { Result } from "../_shared/index.js";
+/** The seven JSON Schema primitive type names. */
+export type JsonSchemaType = "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
+/** Every keyword {@link validateJsonValue} understands. Anything else is a failure, not a pass. */
+export declare const SUPPORTED_KEYWORDS: readonly ["type", "title", "description", "properties", "required", "additionalProperties", "items", "enum", "const", "pattern", "minLength", "maxLength", "minimum", "maximum", "minItems", "maxItems", "default", "examples"];
+/**
+ * One node of the schema subset.
+ *
+ * `type` may be an array, which is how a nullable field is declared here:
+ * `{ type: ["string", "null"] }`. There is no `nullable` keyword, because that
+ * one is OpenAPI's rather than JSON Schema's and a model reading the tool
+ * declaration would be reading a keyword that does not mean what it says.
+ */
+export interface JsonSchema {
+    readonly type?: JsonSchemaType | readonly JsonSchemaType[];
+    readonly title?: string;
+    readonly description?: string;
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+    readonly items?: JsonSchema;
+    readonly enum?: readonly (string | number | boolean | null)[];
+    readonly const?: string | number | boolean | null;
+    readonly pattern?: string;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly default?: unknown;
+    readonly examples?: readonly unknown[];
+}
+/** An object-typed schema, which is what every tool input and output is. */
+export interface JsonObjectSchema extends JsonSchema {
+    readonly type: "object";
+    readonly properties: Readonly<Record<string, JsonSchema>>;
+}
+/**
+ * Validates a value against a schema and returns it unchanged when it conforms.
+ *
+ * `code` names the failure so a caller can tell an input rejection from an
+ * output-shape bug without parsing the message.
+ */
+export declare function validateJsonValue<T>(schema: JsonSchema, value: unknown, label: string, code?: string): Result<T>;
+/**
+ * Fills in the declared top-level defaults of an object schema.
+ *
+ * Only the top level, because that is where every default in this package's
+ * schemas sits and a defaulting pass that reached into arrays would be inventing
+ * entries a caller did not send. A non-object value is handed back untouched for
+ * {@link validateJsonValue} to reject with a type problem, which is a better
+ * message than one about defaults.
+ */
+export declare function applyJsonDefaults(schema: JsonSchema, value: unknown): unknown;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/mcp/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../src/mcp/json-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAK5C,kDAAkD;AAClD,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,SAAS,GACT,MAAM,CAAC;AAEX,mGAAmG;AACnG,eAAO,MAAM,kBAAkB,iOAmBrB,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,SAAS,cAAc,EAAE,CAAC;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CACxC;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;CAC3D;AA2HD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,IAAI,SAAoB,GACvB,MAAM,CAAC,CAAC,CAAC,CAoBX;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAQ7E"}