@deeprelay/mcp 0.0.1 → 0.1.1

package/README.md

@@ -1 +1,194 @@
-Placeholder for @deeprelay/mcp. The real deeprelay MCP server is published by CI from deeprelay-dev/deeprelay over OIDC trusted publishing, starting at 0.1.0.
+# deeprelay MCP server
+
+This server connects Claude Code, Claude Desktop, Cursor, or any other
+[MCP](https://modelcontextprotocol.io) client straight to the deeprelay
+serverless inference API. The agent can browse models and their prices, run
+chat, embeddings, image and video generation inside a budget you approve, read
+your balance and usage, manage webhook endpoints, lower or clear your spending
+limit, and create checkout or billing links, all without leaving the editor.
+
+**29 tools in three tiers: reads are free, writes confirm once, money tools
+quote a price and require explicit confirmation.** The server enforces these
+rules, so they do not depend on the agent behaving well.
+
+This is a **local stdio server**. Your client spawns it as a subprocess and
+talks JSON-RPC over stdin/stdout. Nothing is hosted or proxied: your API key
+stays on your machine, and the server calls `https://api.deeprelay.ai/v1`
+directly.
+
+Full documentation: **<https://deeprelay.ai/docs/mcp>**
+
+## Requirements
+
+- Node 22 or newer
+- A deeprelay API key, created in the dashboard
+
+## Setup
+
+The server runs with `npx -y @deeprelay/mcp@latest`. Your client launches it
+for you.
+
+### Claude Code: `.mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "deeprelay": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@deeprelay/mcp@latest"],
+      "env": {
+        "DEEPRELAY_API_KEY": "${DEEPRELAY_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Claude Code fills in `${DEEPRELAY_API_KEY}` from your shell when it spawns the
+server, so the key stays out of the file and out of version control.
+
+### Claude Desktop: `claude_desktop_config.json`
+
+Claude Desktop does not expand shell variables, so write the value literally:
+
+```json
+{
+  "mcpServers": {
+    "deeprelay": {
+      "command": "npx",
+      "args": ["-y", "@deeprelay/mcp@latest"],
+      "env": {
+        "DEEPRELAY_API_KEY": "deeprelay_live_..."
+      }
+    }
+  }
+}
+```
+
+The file is at `~/Library/Application Support/Claude/claude_desktop_config.json`
+on macOS and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Restart
+the app after editing it.
+
+For Cursor and other clients, see <https://deeprelay.ai/docs/mcp>.
+
+Restart your client, then ask the agent to run `deeprelay_auth_status`. If the
+key is set up correctly, it returns your balance, spending limit and session
+budget.
+
+## Configuration
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `DEEPRELAY_API_KEY` | yes | The API key. Put it in the client's `env` block only; it must never be passed in args/argv, where it would show up in `ps` output and shell history. |
+| `DEEPRELAY_API_BASE` | no | Base URL override, for example `https://api.demo.deeprelay.ai/v1`. Unset means production (`https://api.deeprelay.ai/v1`). |
+
+Startup is **offline**. The server checks that the key is present and that the
+base URL is valid, and makes no network call at boot. A bad key surfaces as a
+clear error on the first tool call. The key is never echoed in a result, an
+error or a confirmation prompt.
+
+**Use a dedicated key** for agent work, so you can revoke it on its own and see
+its usage separately. A `read_only` key covers all 17 free tools and cannot
+write or spend. Checkout, the billing portal and spending-limit changes also
+need the org-admin role. **No key scope limits how much a key can spend.** Your
+organization's spending limit and the session budget below do.
+
+## The three tiers
+
+| Tier | Tools | What happens before it runs |
+| --- | --- | --- |
+| Free, read-only | 17 | Nothing. No confirmation, no charge, no change. |
+| Writes: single confirmation | 8 | One confirmation. The first call describes the change and returns a `confirmation_token`. The second call, with the same arguments plus the token, runs it. |
+| Money tools | 4 | A price. Priced from the catalog, then checked against the per-call ceiling and the session budget. |
+
+Tokens are single-use, expire after five minutes, and are bound to the exact
+arguments that were quoted. No argument or instruction can replace a token.
+Where the client supports MCP elicitation, the server asks you directly and
+your answer goes through the same token.
+
+## Money tools: one session budget
+
+Chat, embeddings, image and video share **one session budget**, and a session is
+one server process.
+
+- The first money call asks you to approve a **$5.00** session budget. The agent
+  can propose a different amount with `session_budget_usd` (**$1–$100**).
+  Confirming approves the budget and runs the call.
+- Calls inside the budget then run with no further prompt.
+- Any single call estimated above the **$0.50 per-call ceiling** is confirmed on
+  its own. The ceiling is checked before the budget. A model with no published
+  rate is treated the same way and is never assumed to be free.
+- When the budget is spent, the next call asks for a new budget.
+
+Estimates are reserved before each call and replaced by the actual cost
+afterwards. A failed call releases its reservation.
+
+**Video is quoted as a floor, not a cap.** `deeprelay_videos_create` reserves
+the floor price. When `deeprelay_videos_get` or `deeprelay_videos_list` sees the
+job completed, the reservation settles at the actual `cost_cents`. Failed,
+cancelled or expired jobs are not billed. If the server exits before the job
+finishes, the reservation is dropped and the real charge appears in
+`deeprelay_usage_get` and `deeprelay_balance_get`.
+
+> Do not run a spend-capable agent with the client's own approval prompts
+> disabled. The client could then accept confirmations for you. Set an
+> organization spending limit as the ceiling that lasts across sessions.
+
+## Writes: one confirmation
+
+- `deeprelay_webhooks_create` states that deeprelay will **send event data to
+  this URL**. The signing secret is returned once and can never be read again.
+- `deeprelay_spending_limit_update` is **lower-only**: a raise is refused before
+  any confirmation exists. Raise a limit in the dashboard.
+- `deeprelay_spending_limit_clear` **removes the limit entirely**, after one
+  confirmation that names the limit and says inference is then bounded only by
+  your balance. With no limit set it reports "nothing to clear" and changes
+  nothing. From the agent's side a limit can be lowered or cleared, never
+  raised.
+- `deeprelay_subscription_checkout`, `deeprelay_billing_portal` and
+  `deeprelay_deposits_create_crypto` **only create links** (or a deposit
+  address). They never charge. Nothing is paid until you complete the step
+  yourself.
+- `deeprelay_deposits_create_crypto` is listed only on accounts with crypto
+  deposits enabled. It stays hidden at startup and appears once the account is
+  shown to have the feature.
+
+## Tools
+
+**Free, read-only (17):** `deeprelay_auth_status`, `deeprelay_health`,
+`deeprelay_models_list`, `deeprelay_models_get`,
+`deeprelay_inference_preflight`, `deeprelay_usage_get`,
+`deeprelay_balance_get`, `deeprelay_spending_limit_get`,
+`deeprelay_subscription_get`, `deeprelay_deposits_list`,
+`deeprelay_deposits_get`, `deeprelay_referrals_get`,
+`deeprelay_webhooks_list`, `deeprelay_webhooks_get`, `deeprelay_videos_list`,
+`deeprelay_videos_get`, `deeprelay_videos_content`.
+
+**Writes: single confirmation (8):** `deeprelay_webhooks_create`,
+`deeprelay_webhooks_delete`, `deeprelay_spending_limit_update`,
+`deeprelay_spending_limit_clear`, `deeprelay_subscription_checkout`, `deeprelay_billing_portal`,
+`deeprelay_deposits_create_crypto`, `deeprelay_videos_cancel`.
+
+**Money (4):** `deeprelay_chat_completion`, `deeprelay_embeddings_create`,
+`deeprelay_images_generate`, `deeprelay_videos_create`.
+
+`deeprelay_health` calls the unauthenticated liveness endpoint, so it answers
+even when the key is wrong or revoked; the server itself still needs
+`DEEPRELAY_API_KEY` set to start. `deeprelay_usage_get` reports serverless
+inference usage: optional `modality` (`chat`, `image`, `video`, `embedding`),
+`model`, `bucket`, `start` and `end`; with no `modality` or `model` it covers
+all four modalities and returns `total_cost_cents` plus per-modality subtotals.
+`deeprelay_videos_content` saves the MP4
+to a local file (under the system temp directory by default, or an absolute
+`output_path`) instead of returning it inline.
+
+Per-tool arguments and the full guide are at <https://deeprelay.ai/docs/mcp>.
+
+## Support
+
+See <https://deeprelay.ai/docs>.
+
+## License
+
+Apache-2.0

package/dist/auth.d.ts

@@ -0,0 +1,52 @@
+import { Configuration } from "@deeprelay/sdk";
+import type { Env } from "./tools/types.js";
+export type { Env };
+/** The only source of the API credential. */
+export declare const API_KEY_ENV = "DEEPRELAY_API_KEY";
+/** Optional base-URL override (demo, staging, self-hosted). */
+export declare const API_BASE_ENV = "DEEPRELAY_API_BASE";
+/** The default API base. Must stay production (invariant 3). */
+export declare const PROD_API_BASE = "https://api.deeprelay.ai/v1";
+/** A configuration problem found before any request is made. */
+export declare class StartupConfigError extends Error {
+    /** The concrete fix, printed under the problem line. */
+    readonly remedy: string;
+    constructor(message: string, remedy: string);
+}
+/**
+ * Return the API key from the environment, or throw StartupConfigError.
+ *
+ * Presence only: keys are opaque, so there is no format probe and no network
+ * call. The value is returned verbatim and is never logged or interpolated.
+ */
+export declare function requireApiKey(env?: Env): string;
+/**
+ * Resolve the API base URL.
+ *
+ * Unset or blank resolves to PROD_API_BASE. An override must parse as an
+ * absolute http(s) URL; trailing slashes are trimmed so path joins in the SDK
+ * never produce `//`.
+ */
+export declare function resolveBaseUrl(env?: Env): string;
+/**
+ * Build the single SDK Configuration every tool uses.
+ *
+ * The SDK owns turning accessToken into the bearer header. The User-Agent set
+ * here overrides the SDK's own `deeprelay-sdk-ts/<v>` default, because the
+ * SDK merges caller headers over its defaults.
+ */
+export declare function buildConfiguration(env?: Env, options?: BuildConfigurationOptions): Configuration;
+export interface BuildConfigurationOptions {
+    /**
+     * Build a keyless Configuration when DEEPRELAY_API_KEY is unset. Only the
+     * unauthenticated liveness probe (deeprelay_health) sets this, so an agent
+     * can tell "the API is up" apart from "my key is missing". A set key is
+     * still attached, and a bad base URL still throws.
+     */
+    allowMissingKey?: boolean;
+}
+/**
+ * Render a startup failure for stderr: the problem on the first line and the
+ * remedy on the second. Always redacted, never a stack trace.
+ */
+export declare function describeStartupError(err: unknown, env?: Env): string;

package/dist/auth.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StartupConfigError = exports.PROD_API_BASE = exports.API_BASE_ENV = exports.API_KEY_ENV = void 0;
+exports.requireApiKey = requireApiKey;
+exports.resolveBaseUrl = resolveBaseUrl;
+exports.buildConfiguration = buildConfiguration;
+exports.describeStartupError = describeStartupError;
+// Startup configuration and the one API-client construction site
+// (Phase 104, D-12: authored fresh; D-15: @deeprelay/sdk is the client).
+//
+// Invariants this module owns:
+//
+//  1. Boot performs no I/O. The key is presence-checked and the base URL is
+//     parsed, and that is all. A network probe at startup would turn a
+//     transient blip into "the server will not start", which an operator
+//     cannot tell apart from a bad key. A bad key surfaces instead as a mapped
+//     401 on the first real call (errors.ts).
+//  2. The key is read from the environment only: DEEPRELAY_API_KEY. It is
+//     never taken from argv (it would show up in `ps` and shell history) and
+//     never read from a credentials file on disk.
+//  3. Unset DEEPRELAY_API_BASE means production. A customer package that
+//     quietly defaulted to a non-production stack would appear to work while
+//     billing the wrong account.
+//  4. Every tool builds its client through buildConfiguration(). It is the only
+//     place in the package that constructs a Configuration, so the
+//     `deeprelay-mcp/<version>` User-Agent is stamped package-wide and no tool
+//     can go out under the wrapped SDK's own default.
+//  5. Every message this module produces goes through redactSecrets().
+const sdk_1 = require("@deeprelay/sdk");
+const errors_js_1 = require("./errors.js");
+const version_js_1 = require("./version.js");
+/** The only source of the API credential. */
+exports.API_KEY_ENV = "DEEPRELAY_API_KEY";
+/** Optional base-URL override (demo, staging, self-hosted). */
+exports.API_BASE_ENV = "DEEPRELAY_API_BASE";
+/** The default API base. Must stay production (invariant 3). */
+exports.PROD_API_BASE = "https://api.deeprelay.ai/v1";
+/** A configuration problem found before any request is made. */
+class StartupConfigError extends Error {
+    /** The concrete fix, printed under the problem line. */
+    remedy;
+    constructor(message, remedy) {
+        super(message);
+        this.name = "StartupConfigError";
+        this.remedy = remedy;
+    }
+}
+exports.StartupConfigError = StartupConfigError;
+const MISSING_KEY_REMEDY = `Set ${exports.API_KEY_ENV} in the "env" block of this server's entry in your MCP client configuration ` +
+    `(create a key at deeprelay.ai; a dedicated key for agent use can be revoked on its own).`;
+const BAD_BASE_REMEDY = `Set ${exports.API_BASE_ENV} to an absolute http(s) URL such as https://api.demo.deeprelay.ai/v1, ` +
+    `or unset it to use production (${exports.PROD_API_BASE}).`;
+/**
+ * Return the API key from the environment, or throw StartupConfigError.
+ *
+ * Presence only: keys are opaque, so there is no format probe and no network
+ * call. The value is returned verbatim and is never logged or interpolated.
+ */
+function requireApiKey(env = process.env) {
+    const key = env[exports.API_KEY_ENV];
+    if (key === undefined || key.trim() === "") {
+        throw new StartupConfigError(`${exports.API_KEY_ENV} is not set.`, MISSING_KEY_REMEDY);
+    }
+    return key;
+}
+/**
+ * Resolve the API base URL.
+ *
+ * Unset or blank resolves to PROD_API_BASE. An override must parse as an
+ * absolute http(s) URL; trailing slashes are trimmed so path joins in the SDK
+ * never produce `//`.
+ */
+function resolveBaseUrl(env = process.env) {
+    const raw = env[exports.API_BASE_ENV]?.trim();
+    if (raw === undefined || raw === "") {
+        return exports.PROD_API_BASE;
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new StartupConfigError(`${exports.API_BASE_ENV} is not a valid absolute URL.`, BAD_BASE_REMEDY);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new StartupConfigError(`${exports.API_BASE_ENV} must use http or https (got ${url.protocol.replace(/:$/, "")}).`, BAD_BASE_REMEDY);
+    }
+    return raw.replace(/\/+$/, "");
+}
+/**
+ * Build the single SDK Configuration every tool uses.
+ *
+ * The SDK owns turning accessToken into the bearer header. The User-Agent set
+ * here overrides the SDK's own `deeprelay-sdk-ts/<v>` default, because the
+ * SDK merges caller headers over its defaults.
+ */
+function buildConfiguration(env = process.env, options = {}) {
+    const accessToken = options.allowMissingKey === true ? optionalApiKey(env) : requireApiKey(env);
+    const basePath = resolveBaseUrl(env);
+    return new sdk_1.Configuration({
+        ...(accessToken === undefined ? {} : { accessToken }),
+        basePath,
+        headers: { "User-Agent": `deeprelay-mcp/${(0, version_js_1.readVersion)()}` },
+    });
+}
+function optionalApiKey(env) {
+    const key = env[exports.API_KEY_ENV];
+    return key === undefined || key.trim() === "" ? undefined : key;
+}
+/**
+ * Render a startup failure for stderr: the problem on the first line and the
+ * remedy on the second. Always redacted, never a stack trace.
+ */
+function describeStartupError(err, env = process.env) {
+    if (err instanceof StartupConfigError) {
+        return (0, errors_js_1.redactSecrets)(`deeprelay-mcp: ${err.message}\n${err.remedy}`, env);
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return (0, errors_js_1.redactSecrets)(`deeprelay-mcp: failed to start: ${message.replace(/\s+/g, " ").trim()}\n` +
+        `Check the ${exports.API_KEY_ENV} and ${exports.API_BASE_ENV} settings in your MCP client configuration.`, env);
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":";;;AAgEA,sCAMC;AASD,wCAmBC;AASD,gDAQC;AAqBD,oDAUC;AAlJD,iEAAiE;AACjE,yEAAyE;AACzE,EAAE;AACF,+BAA+B;AAC/B,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,yEAAyE;AACzE,+EAA+E;AAC/E,8CAA8C;AAC9C,0EAA0E;AAC1E,6EAA6E;AAC7E,kDAAkD;AAClD,yEAAyE;AACzE,6EAA6E;AAC7E,iCAAiC;AACjC,gFAAgF;AAChF,mEAAmE;AACnE,+EAA+E;AAC/E,sDAAsD;AACtD,uEAAuE;AACvE,wCAA+C;AAE/C,2CAA4C;AAE5C,6CAA2C;AAI3C,6CAA6C;AAChC,QAAA,WAAW,GAAG,mBAAmB,CAAC;AAE/C,+DAA+D;AAClD,QAAA,YAAY,GAAG,oBAAoB,CAAC;AAEjD,gEAAgE;AACnD,QAAA,aAAa,GAAG,6BAA6B,CAAC;AAE3D,gEAAgE;AAChE,MAAa,kBAAmB,SAAQ,KAAK;IAC3C,wDAAwD;IAC/C,MAAM,CAAS;IAExB,YAAY,OAAe,EAAE,MAAc;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AATD,gDASC;AAED,MAAM,kBAAkB,GACtB,OAAO,mBAAW,8EAA8E;IAChG,0FAA0F,CAAC;AAE7F,MAAM,eAAe,GACnB,OAAO,oBAAY,wEAAwE;IAC3F,kCAAkC,qBAAa,IAAI,CAAC;AAEtD;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,MAAW,OAAO,CAAC,GAAG;IAClD,MAAM,GAAG,GAAG,GAAG,CAAC,mBAAW,CAAC,CAAC;IAC7B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,kBAAkB,CAAC,GAAG,mBAAW,cAAc,EAAE,kBAAkB,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,MAAW,OAAO,CAAC,GAAG;IACnD,MAAM,GAAG,GAAG,GAAG,CAAC,oBAAY,CAAC,EAAE,IAAI,EAAE,CAAC;IACtC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACpC,OAAO,qBAAa,CAAC;IACvB,CAAC;IAED,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,kBAAkB,CAAC,GAAG,oBAAY,+BAA+B,EAAE,eAAe,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1D,MAAM,IAAI,kBAAkB,CAC1B,GAAG,oBAAY,gCAAgC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EACjF,eAAe,CAChB,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,MAAW,OAAO,CAAC,GAAG,EAAE,UAAqC,EAAE;IAChG,MAAM,WAAW,GAAG,OAAO,CAAC,eAAe,KAAK,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAChG,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACrC,OAAO,IAAI,mBAAa,CAAC;QACvB,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;QACrD,QAAQ;QACR,OAAO,EAAE,EAAE,YAAY,EAAE,iBAAiB,IAAA,wBAAW,GAAE,EAAE,EAAE;KAC5D,CAAC,CAAC;AACL,CAAC;AAYD,SAAS,cAAc,CAAC,GAAQ;IAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,mBAAW,CAAC,CAAC;IAC7B,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,SAAgB,oBAAoB,CAAC,GAAY,EAAE,MAAW,OAAO,CAAC,GAAG;IACvE,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;QACtC,OAAO,IAAA,yBAAa,EAAC,kBAAkB,GAAG,CAAC,OAAO,KAAK,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,IAAA,yBAAa,EAClB,mCAAmC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI;QACxE,aAAa,mBAAW,QAAQ,oBAAY,6CAA6C,EAC3F,GAAG,CACJ,CAAC;AACJ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,83 @@
+import type { Env } from "./tools/types.js";
+/** What replaces anything credential-shaped. */
+export declare const REDACTED = "[REDACTED]";
+/**
+ * Strip credentials out of arbitrary text. Two passes, because either alone
+ * leaves a hole:
+ *
+ *   1. the configured key's literal value, which catches a key of any shape
+ *      (a placeholder, another vendor's key pasted by mistake);
+ *   2. the deeprelay token shape, which catches a DIFFERENT key echoed back by
+ *      the API, one this process never held and so cannot match by value.
+ */
+export declare function redactSecrets(text: string, env?: Env): string;
+/**
+ * Field names whose string VALUES are credential material. Both spellings,
+ * because SDK models are camelCase and raw bodies are snake_case. Exact match:
+ * a substring rule would also swallow ordinary fields such as `secret_rotated_at`
+ * style metadata or URLs the user needs.
+ *
+ * The webhook create tool reveals the new endpoint's signing secret exactly
+ * once through an explicit reveal path in tools/result.ts. Nothing else ever
+ * bypasses this set.
+ */
+export declare const CREDENTIAL_KEYS: ReadonlySet<string>;
+/**
+ * Return a copy of `value` with every string under a CREDENTIAL_KEYS field
+ * replaced by REDACTED, at any depth and inside arrays. The input is never
+ * mutated. Non-string credential values (null, absent) are left alone so the
+ * agent is not told a secret exists where none does. Class instances such as
+ * Date are returned whole rather than flattened.
+ */
+export declare function sanitizeCredentialFields(value: unknown): unknown;
+/**
+ * A spend or write tool's quote step refusing to price a request. Throwing is
+ * what keeps a guardrail from minting a confirmation token for something that
+ * has no quote: no quote, no token, no execution. The mapper keeps this
+ * error's own wording.
+ */
+export declare class QuoteUnavailableError extends Error {
+    constructor(message: string);
+}
+/**
+ * The HTTP status of an SDK error, or undefined for anything that never got a
+ * response. Duck-typed as a fallback so a bundling or version skew that breaks
+ * instanceof cannot change behaviour. Exported so callers can branch on a
+ * status (e.g. a 404 spending limit meaning "none configured") consistently
+ * with the mapper.
+ */
+export declare function httpStatusOf(err: unknown): number | undefined;
+/** The parts of an API error body worth keeping. */
+export interface ErrorEnvelope {
+    code?: string;
+    message?: string;
+}
+export interface MapErrorOptions {
+    env?: Env;
+    /** A short summary already lifted from the body (see readErrorEnvelope). */
+    details?: string;
+    /** The API's stable error code, when known. */
+    code?: string;
+}
+/**
+ * Turn any thrown value into an agent-legible Error. Synchronous so the
+ * mapping is directly testable; tool handlers normally call mapSdkErrorAsync,
+ * which reads the response body first.
+ *
+ * `context` names what was being attempted ("listing models"), so a failure
+ * several calls deep stays attributable.
+ */
+export declare function mapSdkError(err: unknown, context: string, options?: MapErrorOptions): Error;
+/**
+ * Read `{ code, message }` out of an SDK error's response body. Accepts both
+ * shapes the API returns: the OpenAI envelope `{ error: { code, message } }`
+ * and problem+json `{ code, detail }`. Fails closed: anything that is not
+ * recognisably one of those yields an empty envelope, never the raw body.
+ * Reads a clone, so the caller's Response is left unconsumed.
+ */
+export declare function readErrorEnvelope(err: unknown): Promise<ErrorEnvelope>;
+/**
+ * The funnel tool handlers call: read the body once, then map. A 401 never
+ * uses the body (see statusSentence).
+ */
+export declare function mapSdkErrorAsync(err: unknown, context: string, env?: Env): Promise<Error>;