@every-app/sdk 0.2.0 → 0.3.0-rc.1

package/dist/internal/remoteMcp.js

@@ -0,0 +1,543 @@
+/**
+ * Remote MCP apps: any remote MCP server registered on a gateway by URL
+ * (`everyapp mcp add <url>`, Admin → Apps → Add app → "Add an MCP server",
+ * `everyapp_mcp_add`), served to members' AI clients as an MCP app of the
+ * Gateway's own, like a built-in provider app (./providerApps.ts) but with
+ * its tools read from the server and each call forwarded to it with a
+ * credential the Gateway holds (docs/design/2026-10-mcp-by-url.md).
+ *
+ * The registration record is the app row's manifest: `id`, `name`,
+ * `description` and a `remote` block ({@link RemoteMcpBlock}): the one URL
+ * the Gateway ever fetches, how it authenticates ({@link RemoteMcpAuth},
+ * the credential always the NAME of a Gateway setting, never a value), how
+ * a tool's risk is decided when the server's annotations don't say, the
+ * operator's per-tool overrides, and a revision the writers bump so the
+ * Gateway re-lists the tools on first use after a change.
+ *
+ * Everything here is pure and shared by the CLI, the perimeter's registry
+ * rules, the Gateway (which serves the row and validates again at every
+ * fetch) and the settings model (./appSettings.ts), so the rules cannot
+ * drift: what the URL may be, what the credential may be called, how a
+ * server's tool names become the ToolBus's, and what risk a tool gets.
+ */
+import { CAPABILITIES } from "./capabilities.js";
+import { isRemoteMcpSecretName } from "./gatewaySettings.js";
+import { isProviderAppId } from "./providerApps.js";
+import { TOOL_NAME_PATTERN, isToolRisk } from "./tools.js";
+export const REMOTE_MCP_AUTH_KINDS = [
+    "none",
+    "bearer",
+    "header",
+    "basic",
+    "oauth",
+];
+/**
+ * How a tool's risk is decided for the app. `annotations`: from the
+ * server's hints ({@link remoteToolRisk}); `read` or `write`: every tool,
+ * whatever it says. A per-tool override wins over all three.
+ */
+export const REMOTE_MCP_RISK_DEFAULTS = [
+    "annotations",
+    "read",
+    "write",
+];
+const ID_PATTERN = /^[a-z]([a-z0-9-]*[a-z0-9])?$/;
+const ID_MAX_LENGTH = 32;
+/** App ids a remote server can't take: the Gateway's own tool prefix. */
+const RESERVED_IDS = ["everyapp"];
+const SECRET_MAX_LENGTH = 64;
+const HEADER_NAME_PATTERN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,100}$/;
+const PREFIX_MAX_LENGTH = 32;
+const URL_MAX_LENGTH = 2048;
+const NAME_MAX_LENGTH = 255;
+const DESCRIPTION_MAX_LENGTH = 1000;
+const OVERRIDES_MAX = 500;
+const UPSTREAM_NAME_MAX = 256;
+/**
+ * Headers the `header` kind may not name: the ones the Gateway sets on the
+ * request, the ones that route it, and the ones that would carry something
+ * other than this app's credential.
+ */
+const FORBIDDEN_AUTH_HEADERS = new Set([
+    "authorization",
+    "cookie",
+    "host",
+    "content-type",
+    "content-length",
+    "accept",
+    "connection",
+    "transfer-encoding",
+    "mcp-session-id",
+    "mcp-protocol-version",
+    "mcp-method",
+    "mcp-name",
+]);
+/** The default credential name for an app id: `treg` → `TREG_MCP_TOKEN`. */
+export function remoteMcpSecretName(id) {
+    return `${id.toUpperCase().replace(/-/g, "_")}_MCP_TOKEN`;
+}
+/** Whether `id` can be a remote MCP app's id (kebab-case, at most 32, not reserved, not a built-in's). */
+export function remoteMcpIdProblem(id) {
+    if (typeof id !== "string" || !ID_PATTERN.test(id)) {
+        return "the id must be kebab-case: lowercase letters, digits and hyphens, starting with a letter";
+    }
+    if (id.length > ID_MAX_LENGTH) {
+        return `the id must be at most ${ID_MAX_LENGTH} characters`;
+    }
+    if (RESERVED_IDS.includes(id))
+        return `"${id}" is reserved`;
+    if (isProviderAppId(id)) {
+        return `"${id}" is the Gateway's built-in MCP app; a remote server can't take its id`;
+    }
+    return null;
+}
+/**
+ * An app id from the server's URL: the host's registrable name, `www`,
+ * `mcp` and `api` dropped (`https://mcp.deepwiki.com/mcp` → `deepwiki`,
+ * `https://treg.to/mcp/` → `treg`); null when nothing usable is left (an
+ * IP, `localhost`), in which case the caller asks for `--name`.
+ */
+export function remoteMcpIdFromUrl(url) {
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase().replace(/\.$/, "");
+    }
+    catch {
+        return null;
+    }
+    if (!host || /^[\d.]+$/.test(host) || host.includes(":"))
+        return null;
+    const labels = host.split(".").filter((label) => label.length > 0);
+    if (labels.length < 2)
+        return null;
+    // The label before the public suffix, roughly: the last label that
+    // isn't a known two-level suffix part (co.uk, com.au).
+    const SECOND_LEVEL = new Set(["co", "com", "net", "org", "gov", "edu", "ac"]);
+    let index = labels.length - 2;
+    if (index > 0 &&
+        SECOND_LEVEL.has(labels[index]) &&
+        labels[index + 1].length === 2) {
+        index -= 1;
+    }
+    const candidate = labels[index] ?? "";
+    const id = candidate
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-")
+        .slice(0, ID_MAX_LENGTH)
+        .replace(/-+$/g, "");
+    if (!id || !ID_PATTERN.test(id))
+        return null;
+    return remoteMcpIdProblem(id) ? null : id;
+}
+function isSameOrSubdomain(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+/** The hosts whose keys the Gateway holds: a remote server is never one of them. */
+export function reservedUpstreamHosts() {
+    const hosts = new Set([
+        "api.openai.com",
+        "openrouter.ai",
+        "gateway.ai.cloudflare.com",
+        "api.cloudflare.com",
+    ]);
+    for (const capability of Object.values(CAPABILITIES)) {
+        if (capability.mode === "api_key") {
+            for (const host of capability.hosts)
+                hosts.add(host);
+        }
+        else if (capability.mode === "oauth_client") {
+            for (const endpoint of capability.token) {
+                if ("host" in endpoint && typeof endpoint.host === "string") {
+                    hosts.add(endpoint.host);
+                }
+            }
+        }
+    }
+    return [...hosts].sort();
+}
+/**
+ * Why `url` can't be a remote MCP server's address, or null when it can:
+ * `https:` (or `http:` and loopback hosts only while the Gateway itself
+ * runs on `http://`, local dev), a host name rather than an address, no
+ * credentials or fragment in it, not the Gateway's own origin or one of
+ * its app hosts, and not a provider whose key the Gateway holds. The
+ * Gateway checks the stored URL again before every fetch, so a row edited
+ * by hand is refused the same way.
+ */
+export function remoteMcpUrlProblem(url, env) {
+    if (typeof url !== "string" || !url.trim())
+        return "give the server's URL";
+    if (url.length > URL_MAX_LENGTH)
+        return "the URL is too long";
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return "the URL doesn't parse";
+    }
+    const local = env.gatewayUrl.trim().toLowerCase().startsWith("http://");
+    if (parsed.username || parsed.password) {
+        return "the URL must not carry credentials; the Gateway sends the credential from its own setting";
+    }
+    if (parsed.hash)
+        return "the URL must not have a fragment";
+    const host = parsed.hostname.toLowerCase().replace(/\.$/, "");
+    const loopback = host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host === "127.0.0.1" ||
+        host === "[::1]" ||
+        host === "::1";
+    if (parsed.protocol !== "https:") {
+        if (parsed.protocol === "http:" && local && loopback) {
+            // Local dev: a fake or local server on this machine.
+        }
+        else {
+            return local
+                ? "the URL must be https://, or http:// on localhost while the Gateway runs locally"
+                : "the URL must be https://";
+        }
+    }
+    if (!host)
+        return "the URL has no host";
+    if (!loopback && (/^[\d.]+$/.test(host) || host.startsWith("["))) {
+        return "the URL must name a host, not an IP address";
+    }
+    if (loopback && !local) {
+        return "the URL must name a public host";
+    }
+    // The Gateway's own host: any port and every subdomain of it in
+    // production (a Worker on the same zone would be the gateway or an app);
+    // in local dev the exact origin only, so a fake server on another
+    // localhost port is fine.
+    let gatewayHost = "";
+    let gatewayOrigin = "";
+    try {
+        const gateway = new URL(env.gatewayUrl);
+        gatewayHost = gateway.hostname.toLowerCase().replace(/\.$/, "");
+        gatewayOrigin = gateway.origin.toLowerCase();
+    }
+    catch {
+        gatewayHost = "";
+    }
+    if (gatewayHost) {
+        const ownHost = local
+            ? parsed.origin.toLowerCase() === gatewayOrigin
+            : isSameOrSubdomain(host, gatewayHost);
+        if (ownHost)
+            return "the URL is this Gateway's own address";
+    }
+    for (const domain of [env.appBaseDomain, env.thirdPartyDomain]) {
+        const normalized = (domain ?? "").trim().toLowerCase().replace(/\.$/, "");
+        if (normalized && isSameOrSubdomain(host, normalized)) {
+            return `the URL is on this Gateway's app domain (${normalized})`;
+        }
+    }
+    if (reservedUpstreamHosts().includes(host)) {
+        return `${host} is a provider this Gateway holds a key for; apps reach it through the Gateway's capabilities, not as an MCP app`;
+    }
+    return null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The credential name's problem, or null: in the family, and bounded. */
+export function remoteMcpSecretProblem(name) {
+    if (typeof name !== "string" || !name)
+        return "give the credential's setting name";
+    if (name.length > SECRET_MAX_LENGTH)
+        return "the credential's name is too long";
+    if (!isRemoteMcpSecretName(name)) {
+        return `the credential's name must end in _MCP_TOKEN (letters, digits and underscores), like ${remoteMcpSecretName("treg")}`;
+    }
+    return null;
+}
+/** The auth block's problem, or the block as typed. */
+export function parseRemoteMcpAuth(raw) {
+    if (!isRecord(raw) || typeof raw["kind"] !== "string") {
+        return { ok: false, problem: "auth must name a kind" };
+    }
+    const kind = raw["kind"];
+    if (!REMOTE_MCP_AUTH_KINDS.includes(kind)) {
+        return {
+            ok: false,
+            problem: `auth.kind must be one of ${REMOTE_MCP_AUTH_KINDS.join(", ")}`,
+        };
+    }
+    if (kind === "none" || kind === "oauth") {
+        return { ok: true, auth: { kind } };
+    }
+    const secretProblem = remoteMcpSecretProblem(raw["secret"]);
+    if (secretProblem)
+        return { ok: false, problem: `auth.secret: ${secretProblem}` };
+    const secret = raw["secret"];
+    if (kind === "bearer" || kind === "basic") {
+        return { ok: true, auth: { kind, secret } };
+    }
+    const header = raw["header"];
+    if (typeof header !== "string" || !HEADER_NAME_PATTERN.test(header)) {
+        return { ok: false, problem: "auth.header must be an HTTP header name" };
+    }
+    if (FORBIDDEN_AUTH_HEADERS.has(header.toLowerCase())) {
+        return {
+            ok: false,
+            problem: `auth.header can't be ${header}; use kind "bearer" or "basic" for Authorization`,
+        };
+    }
+    const prefix = raw["prefix"];
+    if (prefix !== undefined) {
+        if (typeof prefix !== "string" ||
+            prefix.length > PREFIX_MAX_LENGTH ||
+            /[\r\n]/.test(prefix)) {
+            return { ok: false, problem: "auth.prefix must be a short string" };
+        }
+    }
+    return {
+        ok: true,
+        auth: {
+            kind: "header",
+            secret,
+            header,
+            ...(typeof prefix === "string" && prefix ? { prefix } : {}),
+        },
+    };
+}
+/**
+ * The `remote` block of a stored manifest, checked field by field (a row
+ * edited by hand must not make the Gateway send a credential anywhere the
+ * rules refuse), or why it can't be read. The URL is checked against the
+ * Gateway's environment by the caller ({@link remoteMcpUrlProblem}).
+ */
+export function parseRemoteMcpBlock(raw) {
+    if (!isRecord(raw))
+        return { ok: false, problem: "remote must be an object" };
+    const url = raw["url"];
+    if (typeof url !== "string" || !url || url.length > URL_MAX_LENGTH) {
+        return { ok: false, problem: "remote.url must be a URL" };
+    }
+    const auth = parseRemoteMcpAuth(raw["auth"]);
+    if (!auth.ok)
+        return auth;
+    const risk = raw["risk"] ?? "annotations";
+    if (!REMOTE_MCP_RISK_DEFAULTS.includes(risk)) {
+        return {
+            ok: false,
+            problem: `remote.risk must be one of ${REMOTE_MCP_RISK_DEFAULTS.join(", ")}`,
+        };
+    }
+    const tools = {};
+    const rawTools = raw["tools"] ?? {};
+    if (!isRecord(rawTools))
+        return { ok: false, problem: "remote.tools must be an object" };
+    const entries = Object.entries(rawTools);
+    if (entries.length > OVERRIDES_MAX) {
+        return {
+            ok: false,
+            problem: `remote.tools has more than ${OVERRIDES_MAX} entries`,
+        };
+    }
+    for (const [name, override] of entries) {
+        if (!name || name.length > UPSTREAM_NAME_MAX) {
+            return {
+                ok: false,
+                problem: "remote.tools has a tool name that is empty or too long",
+            };
+        }
+        if (!isRecord(override)) {
+            return { ok: false, problem: `remote.tools.${name} must be an object` };
+        }
+        const out = {};
+        if (override["risk"] !== undefined) {
+            if (!isToolRisk(override["risk"])) {
+                return {
+                    ok: false,
+                    problem: `remote.tools.${name}.risk must be read, write or destructive`,
+                };
+            }
+            out.risk = override["risk"];
+        }
+        if (override["enabled"] !== undefined) {
+            if (typeof override["enabled"] !== "boolean") {
+                return {
+                    ok: false,
+                    problem: `remote.tools.${name}.enabled must be true or false`,
+                };
+            }
+            out.enabled = override["enabled"];
+        }
+        tools[name] = out;
+    }
+    const rev = raw["rev"] ?? 1;
+    if (typeof rev !== "number" || !Number.isInteger(rev) || rev < 1) {
+        return { ok: false, problem: "remote.rev must be a positive integer" };
+    }
+    return {
+        ok: true,
+        block: {
+            url,
+            auth: auth.auth,
+            risk: risk,
+            tools,
+            rev,
+        },
+    };
+}
+/**
+ * The `remote` block of a stored manifest, or null when the manifest has
+ * none (a built-in provider app's, a deployed app's) or it can't be read
+ * (such a row is a provider row the Gateway serves nothing for and lists
+ * as needing setup, see app-setup).
+ */
+export function remoteMcpOf(manifest) {
+    if (!isRecord(manifest) || manifest["remote"] === undefined)
+        return null;
+    const parsed = parseRemoteMcpBlock(manifest["remote"]);
+    return parsed.ok ? parsed.block : null;
+}
+/** Whether a stored manifest declares a remote MCP server at all (well-formed or not). */
+export function hasRemoteMcpBlock(manifest) {
+    return isRecord(manifest) && manifest["remote"] !== undefined;
+}
+/** The credential's setting name the block declares, if its kind takes one. */
+export function remoteMcpSecretOf(auth) {
+    return "secret" in auth ? auth.secret : null;
+}
+/**
+ * A description for a row that gave none: the server's origin, read as a
+ * sentence. The origin only: a path or query may carry something the
+ * registrar meant for the server alone, and the description reaches every
+ * member with access and every AI client.
+ */
+export function remoteMcpDefaultDescription(name, url) {
+    let where = "";
+    try {
+        where = new URL(url).origin;
+    }
+    catch {
+        where = "";
+    }
+    return `${name}'s MCP server${where ? ` at ${where}` : ""}, served to your AI clients through this Gateway.`;
+}
+/**
+ * The operator's override for a server tool: by the server's name, or by
+ * a name that becomes the same ToolBus name ({@link normalizeRemoteToolName}),
+ * so a server that renames `send-mail` to `send_mail` can't bring a tool the
+ * operator turned off back under the same listed name.
+ */
+export function remoteToolOverride(block, upstreamName) {
+    const exact = block.tools[upstreamName];
+    if (exact)
+        return exact;
+    const local = normalizeRemoteToolName(upstreamName);
+    if (!local)
+        return undefined;
+    for (const [key, override] of Object.entries(block.tools)) {
+        if (normalizeRemoteToolName(key) === local)
+            return override;
+    }
+    return undefined;
+}
+/** Whether a server's tool name can travel in an HTTP header (`Mcp-Name`): visible ASCII, bounded. */
+export function isHeaderSafeToolName(name) {
+    return /^[\x21-\x7e]{1,256}$/.test(name);
+}
+/** The manifest a remote MCP app's row stores, from what the registrar gave. */
+export function remoteMcpAppManifest(input) {
+    const name = (input.name ?? "").trim().slice(0, NAME_MAX_LENGTH) || input.id;
+    const description = (input.description ?? "").trim().slice(0, DESCRIPTION_MAX_LENGTH) ||
+        remoteMcpDefaultDescription(name, input.remote.url);
+    return { id: input.id, name, description, remote: input.remote };
+}
+/**
+ * A tool's risk for the Gateway. An override wins; then the app's `read`
+ * or `write` default; then the server's hints, read conservatively: an
+ * explicit `readOnlyHint: true` is `read`, an explicit `destructiveHint:
+ * true` is `destructive` (hidden until approvals exist), and anything
+ * else, a missing hint included, is `write`. The spec's missing-means-true
+ * default for `destructiveHint` is not followed: it would hide every
+ * unhinted tool.
+ */
+export function remoteToolRisk(hints, block, upstreamName) {
+    const override = remoteToolOverride(block, upstreamName)?.risk;
+    if (override)
+        return { risk: override, source: "override" };
+    if (block.risk === "read" || block.risk === "write") {
+        return { risk: block.risk, source: "app" };
+    }
+    if (hints?.readOnlyHint === true)
+        return { risk: "read", source: "hint" };
+    if (hints?.destructiveHint === true) {
+        return { risk: "destructive", source: "hint" };
+    }
+    return { risk: "write", source: "default" };
+}
+/** Whether the operator left the tool on (the default). */
+export function remoteToolEnabled(block, upstreamName) {
+    return remoteToolOverride(block, upstreamName)?.enabled !== false;
+}
+/**
+ * A server's tool name as the ToolBus lists it: lowercase snake_case, at
+ * most 48 characters (`TOOL_NAME_PATTERN`). camelCase is split
+ * (`getUser` → `get_user`), `-`, `.`, `/` and spaces become `_`, anything
+ * else is dropped, runs of `_` collapse, and a leading digit gets a `t_`
+ * in front. Null when nothing usable is left.
+ */
+export function normalizeRemoteToolName(name) {
+    if (typeof name !== "string")
+        return null;
+    let out = name
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+        .toLowerCase()
+        .replace(/[\s./:-]+/g, "_")
+        .replace(/[^a-z0-9_]/g, "")
+        .replace(/_{2,}/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (!out)
+        return null;
+    if (/^[0-9]/.test(out))
+        out = `t_${out}`;
+    out = out.slice(0, 48).replace(/_+$/g, "");
+    return TOOL_NAME_PATTERN.test(out) ? out : null;
+}
+/**
+ * The request headers that carry the credential for `auth`, from the
+ * setting's value. The value never appears anywhere else.
+ */
+export function remoteMcpAuthHeaders(auth, value) {
+    switch (auth.kind) {
+        case "none":
+        case "oauth":
+            return {};
+        case "bearer":
+            return { authorization: `Bearer ${value}` };
+        case "basic":
+            return { authorization: `Basic ${base64(value)}` };
+        case "header":
+            return { [auth.header]: `${auth.prefix ?? ""}${value}` };
+    }
+}
+function base64(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+/** Plain words for an auth kind, for lists and dialogs. */
+export function remoteMcpAuthLabel(auth) {
+    switch (auth.kind) {
+        case "none":
+            return "no credential";
+        case "bearer":
+            return "bearer token";
+        case "basic":
+            return "user and password";
+        case "header":
+            return `header ${auth.header}`;
+        case "oauth":
+            return "OAuth (not supported yet)";
+    }
+}

package/dist/internal/tools.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The internal tools contract (v1) between the gateway's ToolBus and an app's
+ * `everyApp()` wrapper. Two reserved endpoints, reached only over the
+ * gateway's service binding and never public:
+ *
+ *   POST /__everyapp/tools/list  x-everyapp-system JWT (purpose "tools.list")
+ *   POST /__everyapp/tools/call  x-everyapp-identity JWT, chan "mcp" + tc claim
+ *
+ * MCP itself (protocol eras, headers, envelopes) stays in the gateway; apps
+ * only ever speak this small versioned JSON shape. Both sides import the
+ * shapes, paths and the catalog hash from here so they cannot drift.
+ */
+export declare const TOOLS_PROTOCOL_VERSION = 1;
+export declare const TOOLS_PATH_PREFIX = "/__everyapp/tools";
+export declare const TOOLS_LIST_PATH = "/__everyapp/tools/list";
+export declare const TOOLS_CALL_PATH = "/__everyapp/tools/call";
+export declare const TOOL_RISKS: readonly ["read", "write", "destructive"];
+export type ToolRisk = (typeof TOOL_RISKS)[number];
+/** Scopes the gateway mints on `chan: "mcp"` identities, one per risk. */
+export declare const MCP_READ_SCOPE = "mcp:read";
+export declare const MCP_WRITE_SCOPE = "mcp:write";
+/** Never minted in v1: destructive tools are hidden until approvals exist. */
+export declare const MCP_DESTRUCTIVE_SCOPE = "mcp:destructive";
+/** Local tool names: lowercase snake_case, at most 48 characters. */
+export declare const TOOL_NAME_PATTERN: RegExp;
+export declare function isToolRisk(value: unknown): value is ToolRisk;
+/** The exact scope a `chan: "mcp"` identity must carry to call a tool. */
+export declare function requiredScopeForRisk(risk: ToolRisk): string;
+export interface ToolAnnotationsV1 {
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/** One tool as an app describes it to the gateway. */
+export interface ToolDescriptorV1 {
+    name: string;
+    title?: string;
+    description: string;
+    risk: ToolRisk;
+    /** JSON Schema (draft 2020-12) of the arguments; always `type: "object"`. */
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: ToolAnnotationsV1;
+}
+export interface ToolsListRequestV1 {
+    v: 1;
+}
+export interface ToolsListResponseV1 {
+    v: 1;
+    /** The SDK version that produced the catalog. */
+    sdk: string;
+    /** {@link catalogHash} of `instructions` + `tools`. */
+    hash: string;
+    instructions?: string;
+    tools: ToolDescriptorV1[];
+    /** Tools the SDK left out because it can't describe them, and why. */
+    warnings?: string[];
+}
+/** The `tc` identity claim: binds a `chan: "mcp"` token to one call. */
+export interface ToolCallClaim {
+    id: string;
+    name: string;
+}
+export interface ToolsCallRequestV1 {
+    v: 1;
+    name: string;
+    arguments: Record<string, unknown>;
+    /** Must equal the identity token's `tc.id`. */
+    callId: string;
+}
+export interface ToolContentBlockV1 {
+    type: string;
+    [key: string]: unknown;
+}
+export interface ToolCallResultV1 {
+    content: ToolContentBlockV1[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+export type ToolsErrorCodeV1 = "unknown_tool" | "invalid_arguments" | "invalid_request" | "forbidden" | "unauthenticated" | "method_not_allowed" | "misconfigured";
+export interface ToolIssueV1 {
+    message: string;
+    path?: (string | number)[];
+}
+export interface ToolsErrorV1 {
+    code: ToolsErrorCodeV1;
+    message: string;
+    issues?: ToolIssueV1[];
+}
+export interface ToolsCallSuccessV1 {
+    v: 1;
+    /** The app's current catalog hash; the gateway re-syncs on a mismatch. */
+    catalogHash: string;
+    result: ToolCallResultV1;
+}
+export interface ToolsErrorResponseV1 {
+    v: 1;
+    error: ToolsErrorV1;
+}
+export type ToolsCallResponseV1 = ToolsCallSuccessV1 | ToolsErrorResponseV1;
+/**
+ * JSON with object keys sorted at every depth, so equal values always
+ * serialize identically. `undefined` members are dropped, as JSON.stringify
+ * does.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * `sha256:<hex>` over the canonical JSON of a catalog. The SDK reports it with
+ * every list and call; the gateway stores it at sync and re-syncs when a call
+ * reports a different one.
+ */
+export declare function catalogHash(catalog: {
+    instructions?: string;
+    tools: readonly ToolDescriptorV1[];
+}): Promise<string>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/internal/tools.d.ts.map

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