holon-sh 0.0.1-dev.6 → 0.0.1-dev.8

package/README.md

@@ -1,8 +1,10 @@
 # Holon TypeScript SDK
 
 [![CI](https://github.com/holon-sh/sdk-ts/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/holon-sh/sdk-ts/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-holon--labs.dev-blue)](https://holon-labs.dev/docs/)
 [![Node.js](https://img.shields.io/badge/Node.js-22%2B-5FA04E?logo=node.js&logoColor=white)](https://nodejs.org/en/download)
 [![Apache 2.0 License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/holon-sh/sdk-ts/blob/main/LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/jXExyBdy)
 
 This repository contains the Node.js runtime for [`holon`](https://github.com/holon-sh/cli).
 
@@ -10,114 +12,61 @@ This repository contains the Node.js runtime for [`holon`](https://github.com/ho
 
 ```sh
 npm install holon-sh@dev
-npm install -D holon-types@next
+npm install -D holon-types typescript
 ```
 
 `holon-types` is the `holon` CLI. `holon types check` brings its own TypeScript compiler and uses the project's `typescript` when one is installed.
 
-## Invoking MCP Servers
-
-The Holon TypeScript SDK allows generation of type-safe MCP clients. See [Example](https://github.com/holon-sh/cli#example) for an explanation, or [Dependencies](https://github.com/holon-sh/cli#dependencies) to understand dependency resolution.
-
-### Type-checking MCP invocations
+## Create an app
 
 ```sh
-npx holon types check
-```
-
-<details open>
-<summary><h3>Call a tool</h3></summary>
-
-```ts
-import { apps } from "holon-sh";
-
-export async function greet(name: string): Promise<string> {
-  const greeting = await apps.bar.tools.greet({ name }, { timeout: 5000 });
-  return greeting.result;
-}
+npx create-holon-app foo
 ```
 
-Arguments are validated before sending; the result is validated against the output schema and returned.
-
-</details>
-
-<details open>
-<summary><h3>Handle errors</h3></summary>
-
-```ts
-import { ToolCallError, apps } from "holon-sh";
+## Invoking MCP Servers
 
-try {
-  await apps.bar.tools.greet({ name: "world" });
-} catch (error) {
-  if (!(error instanceof ToolCallError)) throw error;
-  error.result; // the original MCP result
+Declare dependencies under `sh.holon.requires` in a [`server.json`](https://modelcontextprotocol.io/registry/quickstart#step-4-create-server-json) beside the server, here the public [Hugging Face](https://huggingface.co/docs/hub/en/hf-mcp-server) MCP server:
+
+```json
+{
+  "name": "com.example/foo",
+  "version": "0.1.0",
+  "description": "Example Foo",
+  "_meta": {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+      "sh.holon": {
+        "requires": {
+          "huggingface": { "url": "https://huggingface.co/mcp" }
+        }
+      }
+    }
+  }
 }
 ```
 
-</details>
-
-<details open>
-<summary><h3>Read the whole result</h3></summary>
-
-`callTool` returns the full MCP result instead of throwing:
+### Type-checking MCP invocations
 
-```ts
-const result = await apps.bar.callTool({ name: "greet", arguments: { name: "world" } });
-if (result.resultType === "input_required") {
-  // call again with inputResponses and requestState
-} else if (result.isError) {
-  // inspect result.content
-} else {
-  result.structuredContent; // typed as Outputs["bar"]["greet"]
-}
+```sh
+npx holon types check
 ```
 
-</details>
-
-<details open>
-<summary><h3>Answer a server's question</h3></summary>
-
-A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Pass `elicit` to answer in place, and the call returns its usual typed output:
+A wrong tool name or argument is a type error:
 
 ```ts
-const greeting = await apps.bar.tools.greet({ name: "world" }, {
-  elicit: async ({ message }) => ({ action: "accept", content: await ask(message) }),
-});
-```
-
-Without `elicit`, the question arrives on `ToolCallError.result`, or as an `input_required` result from `callTool`. To answer later, for example in another request, call again with `inputResponses` and `requestState`.
+import { apps } from "#holon-sh";
 
-</details>
+await apps.huggingface.tools.hub_repo_search({ query: "llama" });
 
-<details open>
-<summary><h3>Read a resource</h3></summary>
+await apps.huggingface.tools.hub_repo_search({ limit: "3" });
+// error TS2322: Type 'string' is not assignable to type 'number'.
 
-A provider types a JSON resource by registering it with `mimeType: "application/json"` and an `"sh.holon/outputSchema"` JSON Schema in its `_meta`, as the `orders` server in `tests/fixtures` does. The client then offers `read` and `watch`:
+await apps.huggingface.tools.hub_repo_details({});
+// error TS2741: Property '"repo_ids"' is missing in type '{}' but required in type '{ config?: string | undefined; limit?: number | undefined; offset?: number | undefined; operations?: ("dataset_preview" | "dataset_structure" | "overview")[] | undefined; repo_ids: string[]; repo_type?: "dataset" | ... 2 more ... | undefined; split?: string | undefined; }'.
 
-```ts
-const summary = await apps.orders.resources["orders://summary"].read();
-
-const controller = new AbortController();
-await apps.orders.resources["orders://summary"].watch(value => console.log(value.total), {
-  signal: controller.signal,
-});
+await apps.huggingface.tools.hub_search({ query: "llama" });
+// error TS2339: Property 'hub_search' does not exist on type '{ readonly hf_fs: (input: { operations: { args: string[]; cmd: "attach" | "cat" | "find" | "ls" | "search" | "stat"; }[]; }, options?: ToolCallOptions | undefined) => Promise<{ results: ({ ...; } | { ...; })[]; truncated?: boolean | undefined; truncation_reason?: "output_budget" | undefined; }>; readonly hf_whoami: ...'.
 ```
 
-`watch` calls back with the current value, then on every update, until the signal aborts. It needs an endpoint binding and a server that supports resource subscriptions.
-
-</details>
-
-## Serve an [MCP App](https://modelcontextprotocol.io/extensions/apps/overview) view
-
-```ts
-import { appView } from "holon-sh/view";
-
-server.registerResource(
-  ...appView("Foo", "ui://foo/index.html", new URL("./dist/index.html", import.meta.url), {
-    csp: { connectDomains: ["https://bar.example.com"] },
-  }),
-);
-```
+## Community
 
-The page itself uses [`holon-ui`](https://github.com/holon-sh/sdk-ui).
+Ask questions and share what you're building on the [Holon Discord](https://discord.gg/jXExyBdy).

package/dist/context.d.ts

@@ -0,0 +1,55 @@
+/** Standard OpenID Connect address claims. */
+export interface AddressClaims {
+    formatted?: string;
+    street_address?: string;
+    locality?: string;
+    region?: string;
+    postal_code?: string;
+    country?: string;
+    [claim: string]: unknown;
+}
+/** Standard OpenID Connect claims. Holon drops one whose value has the wrong type; other claims pass through as JSON. */
+export interface IdentityClaims {
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    middle_name?: string;
+    nickname?: string;
+    preferred_username?: string;
+    profile?: string;
+    picture?: string;
+    website?: string;
+    email?: string;
+    email_verified?: boolean;
+    gender?: string;
+    birthdate?: string;
+    zoneinfo?: string;
+    locale?: string;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    address?: AddressClaims;
+    updated_at?: number;
+    [claim: string]: unknown;
+}
+/** The user a request acts for, as Holon admitted it. */
+export interface Principal {
+    issuer: string;
+    subject: string;
+    clientId: string;
+    scopes: string[];
+    claims: IdentityClaims;
+    actor?: Record<string, unknown>;
+}
+/** The caller of the current MCP request. principal is null for anonymous requests. */
+export interface RequestContext {
+    principal: Principal | null;
+}
+/** Read the caller from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
+export declare function getContext(context?: {
+    authInfo?: {
+        clientId: string;
+        scopes: string[];
+        extra?: Record<string, unknown>;
+    };
+}): RequestContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IACxH,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AACD,yHAAyH;AACzH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClG,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAClG,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IACrG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AACD,yDAAyD;AACzD,MAAM,WAAW,SAAS;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE;AAC3J,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAAG,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE;AAM/D,mJAAmJ;AACnJ,wBAAgB,UAAU,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;CAAO,GAAG,cAAc,CAK/I"}

package/dist/context.js

@@ -0,0 +1,9 @@
+/** Read the caller from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
+export function getContext(context = {}) {
+    const { authInfo } = context;
+    const { iss, sub, claims, act } = (authInfo?.extra ?? {});
+    if (!authInfo || typeof iss !== "string" || typeof sub !== "string")
+        return { principal: null };
+    return { principal: { issuer: iss, subject: sub, clientId: authInfo.clientId, scopes: authInfo.scopes, claims: claims ?? {}, ...(act && { actor: act }) } };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAsBA,mJAAmJ;AACnJ,MAAM,UAAU,UAAU,CAAC,OAAO,GAA2F,EAAE;IAC7H,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAa,CAAC;IACtE,IAAI,CAAC,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAChG,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;AAC9J,CAAC"}

package/dist/ext/files.client.d.ts

@@ -0,0 +1,50 @@
+import type { Client, Transport } from "@modelcontextprotocol/client";
+import { type Download } from "./files.js";
+type Json = Record<string, unknown>;
+export interface FileConnection {
+    client: Pick<Client, "getServerCapabilities">;
+    resolved: {
+        endpoint: URL | string;
+        fileOrigins?: string[];
+        installationUID?: string;
+    };
+    authorization?: string;
+}
+interface FileInput {
+    id: string;
+    name?: string;
+    mimeType: string;
+    size: number;
+    digest?: {
+        algorithm: "sha-256";
+        value: string;
+    };
+    data?: string;
+}
+interface Attachment {
+    blob: Blob;
+    input: FileInput;
+}
+export type Files = Map<string, Attachment>;
+export declare function settings({ client }: FileConnection): Json | undefined;
+export declare function isUploadRequest(error: unknown): error is {
+    data: Json;
+};
+export declare function acceptUploadRequests<T extends Transport>(transport: T): T;
+export declare function prepare(args: Json | undefined, { label, connection, schema }: {
+    label: string;
+    connection: FileConnection | undefined;
+    schema: () => Promise<unknown>;
+}): Promise<{
+    arguments: Json | undefined;
+    files: Files;
+}>;
+export declare function upload(request: Json, files: Files, connection: FileConnection, signal: AbortSignal | undefined, label: string): Promise<string>;
+export declare function downloads<R extends {
+    resultType?: string;
+    _meta?: object;
+}>(result: R, connection: FileConnection, enabled: boolean): R & {
+    downloads?: Download[];
+};
+export {};
+//# sourceMappingURL=files.client.d.ts.map

package/dist/ext/files.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.client.d.ts","sourceRoot":"","sources":["../../src/ext/files.client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAoC,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAExG,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtD,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpC,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAC9C,QAAQ,EAAE;QAAE,QAAQ,EAAE,GAAG,GAAG,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,SAAS;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,SAAS,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE;AAClJ,UAAU,UAAU;IAAG,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE;AACrD,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAY5C,wBAAgB,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,CAGrE;AAID,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAGvE;AAKD,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,SAAS,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,CAWzE;AA4CD,wBAAsB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,cAAc,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,IAAI,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC,CA4BtO;AAqID,wBAAsB,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBrJ;AAwCD,wBAAgB,SAAS,CAAC,CAAC,SAAS;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,GAAG,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;CAAE,CAKpK"}

package/dist/ext/files.client.js

@@ -0,0 +1,359 @@
+import { base64, fetchGlobal, sha256 } from "#platform";
+import { EXTENSION } from "./files.js";
+const list = (value) => Array.isArray(value) ? value : [];
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isPlain = (value) => isObject(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const present = (value) => isObject(value) ? Object.fromEntries(Object.entries(value).filter(([, member]) => member !== null)) : undefined;
+const quoted = (name) => name === undefined ? "a file" : JSON.stringify(name);
+function refuse(reason) {
+    throw new Error(reason);
+}
+export function settings({ client }) {
+    const advertised = client.getServerCapabilities()?.extensions?.[EXTENSION];
+    return isObject(advertised) && advertised.revision == null ? advertised : undefined;
+}
+const uploadRequests = new WeakSet();
+export function isUploadRequest(error) {
+    const data = error?.data;
+    return isObject(data) && uploadRequests.has(data);
+}
+// The MCP client rejects a result type it does not know and drops the result, and has no hook for extension result
+// types yet (typescript-sdk#2782). The transport hands an upload request to it as a JSON-RPC error instead, whose data is
+// the result: the client keeps an error's data as received. Every other message passes through unchanged.
+export function acceptUploadRequests(transport) {
+    let handler;
+    const receive = (message, extra) => {
+        if ("result" in message && message.result?.resultType === "upload_required") {
+            uploadRequests.add(message.result);
+            message = { jsonrpc: "2.0", id: message.id, error: { code: -32603, message: "Unsupported result type 'upload_required'", data: message.result } };
+        }
+        handler?.(message, extra);
+    };
+    Object.defineProperty(transport, "onmessage", { configurable: true, get: () => handler && receive, set: (value) => { handler = value; } });
+    return transport;
+}
+function contains(value) {
+    if (value instanceof Blob)
+        return true;
+    if (Array.isArray(value))
+        return value.some(contains);
+    return isPlain(value) && Object.values(value).some(contains);
+}
+const resolve = (root, ref) => ref.slice(1).split("/").slice(1)
+    .reduce((node, token) => node === null || typeof node !== "object" ? undefined : node[decodeURIComponent(token).replaceAll("~1", "/").replaceAll("~0", "~")], root);
+function expand(schemas, root, seen = new Set()) {
+    return schemas.flatMap(schema => {
+        if (!isObject(schema) || seen.has(schema))
+            return [];
+        seen.add(schema);
+        const target = typeof schema.$ref === "string" && schema.$ref.startsWith("#") ? resolve(root, schema.$ref) : undefined;
+        return [schema, ...expand([target, ...list(schema.anyOf), ...list(schema.oneOf), ...list(schema.allOf)], root, seen)];
+    });
+}
+function replace(value, schemas, root, path, found, label) {
+    if (value instanceof Blob) {
+        const schema = expand(schemas, root).find(schema => "x-mcp-file" in schema);
+        if (!schema)
+            throw new Error(`${label}: the Blob at ${path || "/"} is not a file argument of the tool; the tool was not called.`);
+        const input = {};
+        found.push({ blob: value, schema, input });
+        return input;
+    }
+    if (Array.isArray(value)) {
+        const all = expand(schemas, root);
+        return value.map((item, index) => replace(item, all.map(schema => index < list(schema.prefixItems).length ? list(schema.prefixItems)[index] : schema.items), root, `${path}/${index}`, found, label));
+    }
+    if (!isPlain(value))
+        return value;
+    const all = expand(schemas, root);
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, replace(item, all.map(schema => isObject(schema.properties) ? schema.properties[key] : undefined), root, `${path}/${key}`, found, label)]));
+}
+function baseName(name) {
+    const base = typeof name === "string" ? name.split(/[/\\]/).pop() : "";
+    return base && base !== "." && base !== ".." ? base : undefined;
+}
+export async function prepare(args, { label, connection, schema }) {
+    const files = new Map();
+    if (!contains(args))
+        return { arguments: args, files };
+    if (!connection)
+        throw new Error(`${label}: file arguments need an endpoint binding; the tool was not called.`);
+    const server = settings(connection);
+    if (!server)
+        throw new Error(`${label}: the server does not accept files; the tool was not called.`);
+    const root = await schema();
+    const found = [];
+    const replaced = replace(args, [root], root, "", found, label);
+    await Promise.all(found.map(async ({ blob, schema, input }) => {
+        const descriptor = present(schema["x-mcp-file"]) ?? {};
+        const name = baseName(blob.name);
+        if (blob.size > descriptor.maxSize)
+            throw new Error(`${label}: ${quoted(name)} is ${blob.size} bytes, over the tool's limit of ${descriptor.maxSize}; the tool was not called.`);
+        Object.assign(input, { id: crypto.randomUUID(), ...(name !== undefined && { name }), mimeType: blob.type || "application/octet-stream", size: blob.size });
+        if (list(schema.required).includes("digest"))
+            input.digest = { algorithm: "sha-256", value: await sha256(blob) };
+        files.set(input.id, { blob, input });
+    }));
+    let budget = Number.isSafeInteger(server.maxInlineBytes) ? server.maxInlineBytes : 0;
+    for (const { blob, input } of [...files.values()].sort((a, b) => a.blob.size - b.blob.size)) {
+        if (blob.size === 0)
+            continue;
+        if (blob.size <= budget) {
+            budget -= blob.size;
+            input.data = await base64(blob);
+        }
+        else if (!isObject(server.upload)) {
+            throw new Error(`${label}: the server cannot receive ${quoted(input.name)} (${blob.size} bytes): it takes ${budget} more bytes inline and no uploads; the tool was not called.`);
+        }
+    }
+    return { arguments: replaced, files };
+}
+const UPLOAD = new Set(["fileId", "url", "path", "method", "form", "headers", "credentials", "expiresAt", "_meta"]);
+const DOWNLOAD = new Set(["name", "mimeType", "size", "digest", "url", "path", "headers", "credentials", "expiresAt", "_meta"]);
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const FIELD_VALUE = /^(?:[\x21-\x7e\x80-\xff](?:[\t\x20-\x7e\x80-\xff]*[\x21-\x7e\x80-\xff])?)?$/;
+// https://fetch.spec.whatwg.org/#forbidden-request-header, plus Authorization.
+const FORBIDDEN = new Set(["accept-charset", "accept-encoding", "access-control-request-headers", "access-control-request-method", "authorization", "connection", "content-length", "cookie", "cookie2", "date", "dnt", "expect", "host", "keep-alive", "origin", "referer", "set-cookie", "te", "trailer", "transfer-encoding", "upgrade", "via"]);
+const OVERRIDES = new Set(["x-http-method-override", "x-http-method", "x-method-override"]);
+const ROUTING = new Set(["forwarded", "x-original-url", "x-rewrite-url", ...OVERRIDES]);
+const FORM_HEADERS = new Set(["content-type", "content-encoding", "content-range", "content-digest", "repr-digest"]);
+const FORM_NAME = /^[^\p{Cc}"\\]+$/u;
+const PATH = /^(?:\/(?!\.\.?(?:\/|$))[A-Za-z0-9\-_~.]+)+$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$/;
+const loopback = (host) => host === "localhost" || host.endsWith(".localhost") || /^127\.\d+\.\d+\.\d+$/.test(host) || host === "[::1]";
+const expired = (target) => target.expiresAt !== undefined && Date.parse(target.expiresAt) <= Date.now();
+function parse(url) {
+    try {
+        return new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+}
+function check(raw, kind, { resolved }) {
+    const target = present(raw);
+    if (!target)
+        refuse("not an object");
+    const unknown = Object.keys(target).find(key => !(kind === "upload" ? UPLOAD : DOWNLOAD).has(key));
+    if (unknown !== undefined)
+        refuse(`unknown member ${JSON.stringify(unknown)}`);
+    if (typeof target.url === "string" === (typeof target.path === "string") || [target.url, target.path].some(value => value !== undefined && typeof value !== "string"))
+        refuse("needs exactly one of url and path");
+    if (target.credentials !== "omit" && target.credentials !== "include")
+        refuse("credentials must be omit or include");
+    const { expiresAt } = target;
+    if (expiresAt !== undefined && !(typeof expiresAt === "string" && TIMESTAMP.test(expiresAt) && !Number.isNaN(Date.parse(expiresAt))))
+        refuse("expiresAt is not an RFC 3339 timestamp");
+    if (target.headers !== undefined && !(isObject(target.headers) && Object.values(target.headers).every(value => typeof value === "string")))
+        refuse("headers must map names to strings");
+    const headers = (target.headers ?? {});
+    let form;
+    if (kind === "upload") {
+        if (typeof target.fileId !== "string")
+            refuse("fileId is not a string");
+        if (target.method !== undefined && target.method !== "PUT" && target.method !== "POST")
+            refuse("method must be PUT or POST");
+        if (target.form !== undefined) {
+            const raw = present(target.form);
+            if (target.method !== "POST")
+                refuse("a form target must use POST");
+            if (!raw || Object.keys(raw).some(key => key !== "fields" && key !== "fileField") || !Array.isArray(raw.fields) || typeof raw.fileField !== "string")
+                refuse("form is malformed");
+            const fields = raw.fields.map(present);
+            if (!FORM_NAME.test(raw.fileField))
+                refuse("form fileField is not allowed");
+            for (const field of fields) {
+                if (!field || Object.keys(field).some(key => key !== "name" && key !== "value") || typeof field.name !== "string" || typeof field.value !== "string")
+                    refuse("a form field is malformed");
+                if (!FORM_NAME.test(field.name) || field.name === raw.fileField || /[\r\n\0]/.test(field.value))
+                    refuse("a form field is not allowed");
+            }
+            form = { fileField: raw.fileField, fields: fields };
+        }
+    }
+    else {
+        if (target.name !== undefined && typeof target.name !== "string")
+            refuse("name is not a string");
+        if (typeof target.mimeType !== "string")
+            refuse("mimeType is not a string");
+        if (!Number.isSafeInteger(target.size) || target.size < 0)
+            refuse("size is not a non-negative integer");
+        const digest = target.digest === undefined ? undefined : present(target.digest);
+        if (target.digest !== undefined && (!digest || Object.keys(digest).some(key => key !== "algorithm" && key !== "value") || digest.algorithm !== "sha-256" || typeof digest.value !== "string"))
+            refuse("digest is malformed");
+    }
+    const include = target.credentials === "include";
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        if (!TOKEN.test(name) || !FIELD_VALUE.test(value))
+            refuse("a header is not valid HTTP");
+        if (FORBIDDEN.has(lower) || lower.startsWith("proxy-") || lower.startsWith("sec-")
+            || OVERRIDES.has(lower) && value.split(",").some(method => ["connect", "trace", "track"].includes(method.trim().toLowerCase())))
+            refuse(`header ${name} is not allowed`);
+        if ((target.path !== undefined || include) && (ROUTING.has(lower) || lower.startsWith("x-forwarded-")))
+            refuse(`header ${name} is not allowed with this target`);
+        if (form && FORM_HEADERS.has(lower))
+            refuse(`header ${name} is not allowed with a form`);
+    }
+    const endpoint = new URL(resolved.endpoint);
+    const origins = resolved.fileOrigins && new Set(resolved.fileOrigins.map(origin => new URL(origin).origin));
+    let url;
+    let allowlisted = false;
+    if (typeof target.url === "string") {
+        const parsed = parse(target.url);
+        if (!parsed || parsed.username || parsed.password)
+            refuse("url is not an absolute URL without userinfo");
+        url = parsed;
+        allowlisted = origins?.has(url.origin) ?? false;
+        if (origins && !allowlisted)
+            refuse("url is not on fileOrigins");
+        if (url.protocol !== "https:" && !(url.protocol === "http:" && allowlisted && loopback(url.hostname)))
+            refuse("url is not https");
+        if (include && url.origin !== endpoint.origin)
+            refuse("credentials include is honored only at the server's origin");
+    }
+    else {
+        const path = target.path;
+        if (!PATH.test(path))
+            refuse("path is not a valid path");
+        if (endpoint.protocol !== "https:" && !loopback(endpoint.hostname) && !origins?.has(endpoint.origin))
+            refuse("a path under an http MCP address needs loopback or fileOrigins");
+        url = new URL(endpoint);
+        url.pathname = url.pathname.replace(/\/$/, "") + path;
+        url.hash = "";
+    }
+    return { url: url.href, path: target.path !== undefined, allowlisted, include, headers, method: (target.method ?? "PUT"), form, expiresAt };
+}
+function send(target, init, { resolved, authorization }) {
+    const headers = new Headers(target.headers);
+    if (target.include && authorization)
+        headers.set("authorization", authorization);
+    if (target.path && resolved.installationUID)
+        headers.set("x-holon-installation-uid", resolved.installationUID);
+    return (target.path || target.allowlisted ? fetch : fetchGlobal)(target.url, { ...init, headers, credentials: "omit", redirect: "error" });
+}
+const reason = (error) => {
+    const { message, cause } = (error ?? {});
+    return String(cause?.message ?? message ?? error);
+};
+const TYPE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+\/[!#$%&'*+.^_`|~0-9A-Za-z-]+(?:[ \t]*;[ \t]*[!#$%&'*+.^_`|~0-9A-Za-z-]+=(?:[!#$%&'*+.^_`|~0-9A-Za-z-]+|"(?:[\t\x20\x21\x23-\x5b\x5d-\x7e]|\\[\t\x20-\x7e])*"))*$/;
+// fetch's own FormData boundary has too little randomness for the extension (128 bits), so the body is built here,
+// encoding names and the filename as the WHATWG multipart/form-data algorithm does.
+function multipart({ fields, fileField }, { blob, input }) {
+    const boundary = `----holon${Array.from(crypto.getRandomValues(new Uint8Array(16)), byte => byte.toString(16).padStart(2, "0")).join("")}`;
+    const filename = (baseName(input.name) ?? "file").replaceAll('"', "%22").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+    const parts = fields.map(({ name, value }) => `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`);
+    parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="${fileField}"; filename="${filename}"\r\nContent-Type: ${TYPE.test(input.mimeType) ? input.mimeType : "application/octet-stream"}\r\n\r\n`, blob, `\r\n--${boundary}--\r\n`);
+    return { body: new Blob(parts), type: `multipart/form-data; boundary=${boundary}` };
+}
+async function transfer(target, file, connection, signal) {
+    const { body, type } = target.form ? multipart(target.form, file) : { body: file.blob.slice(0, file.blob.size, ""), type: undefined };
+    for (let attempt = 0;; attempt++) {
+        if (expired(target))
+            throw new Error("its target expired");
+        let response;
+        try {
+            response = await send(type ? { ...target, headers: { ...target.headers, "Content-Type": type } } : target, { method: target.method, body, signal }, connection);
+        }
+        catch (error) {
+            if (signal.aborted || target.method !== "PUT" || attempt === 2)
+                throw new Error(reason(error));
+        }
+        if (response) {
+            await response.body?.cancel();
+            if (response.ok)
+                return;
+            const retry = response.status >= 500 || response.status === 408 || response.status === 429;
+            if (target.method !== "PUT" || !retry || attempt === 2)
+                throw new Error(`HTTP ${response.status}`);
+        }
+        await new Promise(resolve => setTimeout(resolve, 200 * (attempt + 1)));
+    }
+}
+export async function upload(request, files, connection, signal, label) {
+    const fail = (reason) => new Error(`${label}: ${reason}; the tool did not run.`);
+    const { requestState, uploads } = request;
+    if (typeof requestState !== "string")
+        throw fail("the server's upload request has no requestState");
+    const waiting = new Set([...files.values()].filter(({ input }) => input.size > 0 && input.data === undefined).map(({ input }) => input.id));
+    const ids = list(uploads).map(target => target?.fileId);
+    if (!Array.isArray(uploads) || ids.length !== waiting.size || new Set(ids).size !== ids.length || !ids.every(id => waiting.has(id))) {
+        throw fail("the server's upload request does not list each file sent without data exactly once");
+    }
+    const targets = uploads.map((target) => {
+        const file = files.get(target.fileId);
+        try {
+            return { file, target: check(target, "upload", connection) };
+        }
+        catch (error) {
+            throw fail(`the upload target for ${quoted(file.input.name)} was rejected (${error.message})`);
+        }
+    });
+    const controller = new AbortController();
+    const stop = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    await Promise.all(targets.map(async ({ file, target }) => {
+        try {
+            await transfer(target, file, connection, stop);
+        }
+        catch (error) {
+            controller.abort();
+            throw fail(signal?.aborted ? "the call was cancelled during the upload" : `uploading ${quoted(file.input.name)} failed (${error.message})`);
+        }
+    }));
+    return requestState;
+}
+function download(raw, connection) {
+    const { name, mimeType, size, digest, expiresAt } = present(raw) ?? {};
+    const label = `Downloading ${quoted(typeof name === "string" ? name : undefined)}`;
+    const blob = async ({ signal } = {}) => {
+        let target;
+        try {
+            target = check(raw, "download", connection);
+        }
+        catch (error) {
+            throw new Error(`${label} was refused: its target was rejected (${error.message}).`);
+        }
+        if (expired(target))
+            throw new Error(`${label} was refused: its target expired.`);
+        const declared = size;
+        const chunks = [];
+        let received = 0;
+        try {
+            const response = await send(target, { method: "GET", signal }, connection);
+            if (response.status !== 200) {
+                await response.body?.cancel();
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const reader = response.body?.getReader();
+            while (reader) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                received += chunk.value.byteLength;
+                if (received > declared) {
+                    await reader.cancel();
+                    throw new Error(`more than the declared ${declared} bytes; discarded`);
+                }
+                chunks.push(chunk.value);
+            }
+        }
+        catch (error) {
+            throw new Error(`${label} failed (${reason(error)}).`);
+        }
+        if (received !== declared)
+            throw new Error(`${label} failed (${received} bytes, not the declared ${declared}; discarded).`);
+        const file = new Blob(chunks, { type: mimeType });
+        if (digest && await sha256(file) !== digest.value)
+            throw new Error(`${label} failed (the bytes do not match the digest; discarded).`);
+        return file;
+    };
+    return Object.freeze({ ...Object.fromEntries(Object.entries({ name, mimeType, size, digest, expiresAt }).filter(([, value]) => value !== undefined)), blob });
+}
+export function downloads(result, connection, enabled) {
+    if (result.resultType === "input_required" || !isObject(result._meta) || !(EXTENSION in result._meta))
+        return result;
+    const { [EXTENSION]: meta, ...rest } = result._meta;
+    const handles = enabled ? list(meta?.downloads).map(target => download(target, connection)) : [];
+    return { ...result, _meta: rest, ...(handles.length > 0 && { downloads: handles }) };
+}
+//# sourceMappingURL=files.client.js.map