holon-sh 0.0.1-dev.15 → 0.0.1-dev.17

package/src/ext/events.ts

@@ -1,12 +1,12 @@
 // The server side of MCP Events, as the Triggers & Events Working Group's design sketch defines it:
 // https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md
-// The draft is experimental, so this lives under ext and may change with it. It serves the poll and push delivery
-// modes. Names follow the sketch, and types are the MCP SDK's own wherever it has them.
 import { ProtocolError, ProtocolErrorCode, SUBSCRIPTION_ID_META_KEY } from "@modelcontextprotocol/server";
-import type { AuthInfo, JSONRPCErrorResponse, McpServer, Server, StandardSchemaWithJSON } from "@modelcontextprotocol/server";
+import type { JSONRPCErrorResponse, McpServer, Server, ServerCapabilities, ServerContext, StandardSchemaV1, StandardSchemaWithJSON } from "@modelcontextprotocol/server";
+import { getContext } from "../context.js";
+import type { EventOccurrence as Occurrence } from "../protocol.js";
 
 /** The request a subscription came in, as Holon admitted it: read its caller with getContext. */
-export type SubscriptionContext = { authInfo?: AuthInfo | undefined } | undefined;
+export type SubscriptionContext = ServerContext["http"];
 /** How a subscription receives its events. */
 export type DeliveryModeName = "poll" | "push";
 /** A JSON-RPC error, as a subscription that is terminated or fails is told it. */
@@ -28,14 +28,7 @@ export interface Subscription<A> {
   readonly context: SubscriptionContext;
 }
 /** An occurrence as subscriptions receive it: the sketch's EventOccurrence. `cursor` is the position after it. */
-export interface EventOccurrence<D = unknown> {
-  eventId: string;
-  name: string;
-  /** When it happened, in ISO 8601. */
-  timestamp: string;
-  data: D;
-  cursor?: string;
-}
+export type EventOccurrence<D = unknown> = Occurrence<D> & { cursor?: string };
 /** An event type: the arguments a subscription gives, and the data each occurrence carries. */
 export interface EventDefinition<A, D> {
   description?: string;
@@ -55,7 +48,7 @@ export interface EventDefinition<A, D> {
   /** The data a subscription with these arguments receives of an emitted event. Without it, the data as emitted. */
   transform?: (data: D, args: A, context: SubscriptionContext) => unknown;
   /** The delivery modes this event type offers: poll and push unless given. */
-  delivery?: DeliveryModeName[];
+  delivery?: [DeliveryModeName, ...DeliveryModeName[]];
   /**
    * Whether the caller may subscribe with these arguments. A subscription is refused with Forbidden when it may not,
    * and one already open is ended when it no longer may: each poll asks, and a stream asks at each heartbeat. A
@@ -138,15 +131,6 @@ export interface Events {
 /** The identifier a server declares the Events extension under, in capabilities.extensions. */
 export const EVENTS_EXTENSION = "io.modelcontextprotocol/events";
 
-// The parts of an MCP server and of a request's context this module uses.
-interface Served {
-  registerCapabilities(capabilities: object): void;
-  setRequestHandler(method: string, schemas: object, handler: (request: any, ctx: Context) => unknown): void;
-}
-interface Context {
-  mcpReq: { id: string | number; signal: AbortSignal; notify(notification: { method: string; params: object }): Promise<void> };
-  http?: SubscriptionContext & object;
-}
 /** An emitted event, kept at its sequence for polls and reconnecting streams. */
 interface Kept { sequence: number; at: number; target: string | undefined; occurrence: EventOccurrence }
 /** A subscription held by a push stream or a poll lease. */
@@ -165,19 +149,10 @@ interface Held {
 type Reader = Pick<Held, "id" | "arguments" | "context" | "untargetable">;
 /** The subscription a request asks for, checked. */
 interface Requested { id: string; lease: string; arguments: unknown; context: SubscriptionContext }
-interface Type<A = any, D = any> {
+interface Type<A = any, D = any> extends Readonly<EventDefinition<A, D>> {
   readonly name: string;
   readonly order: number;
-  readonly description?: string | undefined;
-  readonly inputSchema: StandardSchemaWithJSON<unknown, A>;
-  readonly payloadSchema: StandardSchemaWithJSON;
-  readonly _meta?: Record<string, unknown> | undefined;
-  readonly delivery: DeliveryModeName[];
-  readonly match?: EventDefinition<A, D>["match"];
-  readonly transform?: EventDefinition<A, D>["transform"];
-  readonly authorize?: EventDefinition<A, D>["authorize"];
-  readonly onSubscribe?: EventDefinition<A, D>["onSubscribe"];
-  readonly onUnsubscribe?: EventDefinition<A, D>["onUnsubscribe"];
+  readonly delivery: NonNullable<EventDefinition<A, D>["delivery"]>;
   sequence: number;
   dropped: number;
   kept: Kept[];
@@ -192,22 +167,18 @@ interface Type<A = any, D = any> {
 }
 interface Lease { type: Type; opening: Promise<Held>; ended?: EventError; release?: () => void; timer?: ReturnType<typeof setTimeout> }
 
-const INVALID_PARAMS = ProtocolErrorCode.InvalidParams;
-const INTERNAL_ERROR = ProtocolErrorCode.InternalError;
 // The sketch's general-purpose codes, provisional until the specification allocates them.
 const NOT_FOUND = -32023;
 const FORBIDDEN = -32024;
 const RESOURCE_EXHAUSTED = -32025;
 const UNSUPPORTED = -32026;
-// Requests are checked here, against each event type's own schema.
-const params = { "~standard": { version: 1, vendor: "holon-sh", validate: (value: unknown) => ({ value: value ?? {} }) } };
+const params: StandardSchemaV1<unknown, Record<string, unknown>> = { "~standard": { version: 1, vendor: "holon-sh", validate: value => ({ value: (value ?? {}) as Record<string, unknown> }) } };
 
 const refusal = ({ code, message, data }: EventError) => new ProtocolError(code, message, data);
 const removed: EventError = { code: NOT_FOUND, message: "NotFound", data: { kind: "event" } };
 const forbidden: EventError = { code: FORBIDDEN, message: "Forbidden" };
-// What a client is told of a failure: its code when it is a JSON-RPC one, and its message.
 const described = (error: any): EventError => ({
-  code: Number.isInteger(error?.code) ? error.code : INTERNAL_ERROR,
+  code: Number.isInteger(error?.code) ? error.code : ProtocolErrorCode.InternalError,
   message: error?.message || "InternalError",
   ...(error?.data !== undefined && { data: error.data }),
 });
@@ -215,13 +186,9 @@ const described = (error: any): EventError => ({
 const canonical = (value: unknown): unknown => Array.isArray(value) ? value.map(canonical)
   : value && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical((value as Record<string, unknown>)[key])]))
   : value;
-// Who asked, as Holon admitted them: the user, the client acting for them, the agent when one acts for the user, and
-// what the token allows. A caller without a subject has no identity: nobody can tell it from another such caller.
 const caller = (context: SubscriptionContext): string | null => {
-  const authInfo = context?.authInfo;
-  const { iss = null, sub, act = null } = authInfo?.extra ?? {};
-  if (!authInfo || typeof sub !== "string") return null;
-  return JSON.stringify(canonical([iss, sub, authInfo.clientId ?? null, act, [...authInfo.scopes ?? []].sort()]));
+  const { principal } = getContext(context);
+  return principal && JSON.stringify(canonical([principal.issuer, principal.subject, principal.clientId, principal.actor ?? null, [...principal.scopes].sort()]));
 };
 const hex = (bytes: Uint8Array) => [...bytes].map(byte => byte.toString(16).padStart(2, "0")).join("");
 // A subscription's id is the same for the same caller, event type and arguments, so it survives reconnects and poll
@@ -230,21 +197,16 @@ const identify = async (who: string | null, name: string, args: unknown) => {
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify([who, name, canonical(args)])));
   return `sub_${hex(new Uint8Array(digest, 0, 16))}`;
 };
-// A caller without an identity gets an id of its own for each stream.
 const unique = () => `sub_${hex(crypto.getRandomValues(new Uint8Array(16)))}`;
-// The subscriber a subscription's arguments name, whoever the caller.
 const named = (args: unknown) => JSON.stringify(canonical(args));
-// Counts up or down under a key, and forgets a key that reaches none.
 const count = (counts: Map<string, number>, key: string, by: number) => {
   const total = (counts.get(key) ?? 0) + by;
   if (total) counts.set(key, total);
   else counts.delete(key);
 };
-// A teardown that fails has nobody to tell, and must not take the process down.
-const settle = (run: () => unknown) => { Promise.resolve().then(run).catch(() => {}); };
-const integer = (value: unknown, minimum: number) => value === undefined || Number.isInteger(value) && (value as number) >= minimum;
+const integer = (value: unknown, minimum: number): value is number | undefined => value === undefined || Number.isInteger(value) && (value as number) >= minimum;
 
-const OFFERED: DeliveryModeName[] = ["poll", "push"];
+const OFFERED: [DeliveryModeName, ...DeliveryModeName[]] = ["poll", "push"];
 // What each type keeps of what it emits, for polls and reconnecting streams: the sketch's emit buffer.
 const KEPT_EVENTS = 10_000;
 const KEPT_AGE = 10 * 60_000;
@@ -258,7 +220,6 @@ const POLL_SUBSCRIPTION_TTL = 60_000;
 // cannot be told apart, so they count together as one caller.
 const MAX_SUBSCRIPTIONS = 10_000;
 const MAX_SUBSCRIPTIONS_PER_CALLER = 1000;
-// How many event types events/list returns at a time.
 const PAGE_SIZE = 100;
 /**
  * What a stream sends before it ends and its client resumes from its cursor. The draft leaves flow control to the
@@ -283,7 +244,7 @@ export function createEvents(): Events {
   let subscribed = 0;
   const callers = new Map<string, number>();
 
-  const position = (type: Type, sequence = type.sequence) => `${epoch}.${sequence}`;
+  const position = (sequence: number) => `${epoch}.${sequence}`;
 
   // What a subscription is owed after a cursor, up to `until`: the events for it, in order, where delivery starts,
   // and where it now stands. A null cursor starts where the subscription was opened, and so does one from another
@@ -300,14 +261,14 @@ export function createEvents(): Events {
     const events: EventOccurrence[] = [];
     const failures: EventError[] = [];
     let reached = recent.length ? recent[0]!.sequence - 1 : until;
-    const start = position(type, reached);
+    const start = position(reached);
     for (const kept of recent) {
-      if (events.length === limit) return { events, failures, start, cursor: position(type, reached), truncated, hasMore: true };
+      if (events.length === limit) return { events, failures, start, cursor: position(reached), truncated, hasMore: true };
       reached = kept.sequence;
       const event = shape(type, kept, subscription, error => failures.push(error));
       if (event) events.push(event);
     }
-    return { events, failures, start, cursor: position(type, until), truncated, hasMore: false };
+    return { events, failures, start, cursor: position(until), truncated, hasMore: false };
   };
 
   // The occurrence a subscription receives, or nothing when it is not for it. An event emitted to one subscription
@@ -324,24 +285,24 @@ export function createEvents(): Events {
     } catch (error: any) {
       const { eventId } = occurrence;
       console.error(`holon-sh/ext/events: event ${eventId} of ${type.name} was skipped for a subscription:`, error);
-      failed({ code: INTERNAL_ERROR, message: `Event ${eventId} could not be delivered and was skipped`, data: { eventId, reason: String(error?.message ?? error) } });
+      failed({ code: ProtocolErrorCode.InternalError, message: `Event ${eventId} could not be delivered and was skipped`, data: { eventId, reason: String(error?.message ?? error) } });
       return undefined;
     }
-    return { ...occurrence, data, cursor: position(type, sequence) };
+    return { ...occurrence, data, cursor: position(sequence) };
   };
 
   // The event type and arguments a request names, checked as the sketch's errors require, in its order: the type,
   // the delivery mode, the request's own fields, the arguments, and then whether the caller may subscribe. A caller
   // refused loses what it holds of that subscription at once.
-  const subscription = async ({ name, arguments: args = {}, cursor, maxAgeMs, maxEvents }: Record<string, unknown>, context: SubscriptionContext, delivery: DeliveryModeName): Promise<{ type: Type; subscription: Requested }> => {
+  const subscription = async ({ name, arguments: args = {}, cursor, maxAgeMs, maxEvents }: Record<string, unknown>, context: SubscriptionContext, delivery: DeliveryModeName) => {
     const type = types.get(name as string);
     if (!type) throw refusal(removed);
     if (!type.delivery.includes(delivery)) throw refusal({ code: UNSUPPORTED, message: "Unsupported", data: { feature: "deliveryMode", value: delivery } });
-    if (cursor != null && typeof cursor !== "string") throw new ProtocolError(INVALID_PARAMS, "cursor must be a string or null");
-    if (!integer(maxAgeMs, 0)) throw new ProtocolError(INVALID_PARAMS, "maxAgeMs must be a non-negative integer");
-    if (!integer(maxEvents, 1)) throw new ProtocolError(INVALID_PARAMS, "maxEvents must be a positive integer");
+    if (cursor != null && typeof cursor !== "string") throw new ProtocolError(ProtocolErrorCode.InvalidParams, "cursor must be a string or null");
+    if (!integer(maxAgeMs, 0)) throw new ProtocolError(ProtocolErrorCode.InvalidParams, "maxAgeMs must be a non-negative integer");
+    if (!integer(maxEvents, 1)) throw new ProtocolError(ProtocolErrorCode.InvalidParams, "maxEvents must be a positive integer");
     const checked = await type.inputSchema["~standard"].validate(args);
-    if (checked.issues) throw new ProtocolError(INVALID_PARAMS, `Invalid arguments for ${name}: ${checked.issues.map(issue => issue.message).join("; ")}`);
+    if (checked.issues) throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid arguments for ${name}: ${checked.issues.map(issue => issue.message).join("; ")}`);
     const who = caller(context);
     // Polls share a lease per caller and arguments, and callers without an identity share one per arguments.
     const lease = await identify(who, type.name, checked.value);
@@ -351,7 +312,8 @@ export function createEvents(): Events {
       leases.delete(lease);
       throw refusal(forbidden);
     }
-    return { type, subscription: { id: who === null ? unique() : lease, lease, arguments: checked.value, context } };
+    const subscription: Requested = { id: who === null ? unique() : lease, lease, arguments: checked.value, context };
+    return { type, subscription, cursor: cursor ?? null, maxAgeMs, maxEvents };
   };
 
   const endSubscription = (type: Type, id: string, error: EventError) => {
@@ -364,13 +326,11 @@ export function createEvents(): Events {
   // terminated it; `close` is how the holder says its hold is over.
   const open = async (type: Type, { id, delivery, arguments: args, context }: { id: string; delivery: DeliveryModeName; arguments: unknown; context: SubscriptionContext }, end: (error: EventError) => void): Promise<Held> => {
     if (types.get(type.name) !== type) throw refusal(removed);
-    // Callers without an identity cannot be told apart, so they count together as one.
     const who = caller(context) ?? "anonymous";
     if (subscribed >= MAX_SUBSCRIPTIONS) throw refusal({ code: RESOURCE_EXHAUSTED, message: "ResourceExhausted", data: { limit: "subscriptions", max: MAX_SUBSCRIPTIONS } });
     if ((callers.get(who) ?? 0) >= MAX_SUBSCRIPTIONS_PER_CALLER) throw refusal({ code: RESOURCE_EXHAUSTED, message: "ResourceExhausted", data: { limit: "subscriptionsPerCaller", max: MAX_SUBSCRIPTIONS_PER_CALLER } });
     subscribed++;
     count(callers, who, 1);
-    // A presence keeps a subscriber's value while any of its streams or leases is open.
     const subscriber = named(args);
     const hold = (by: number) => {
       count(type.holds, subscriber, by);
@@ -396,8 +356,9 @@ export function createEvents(): Events {
       current.held.delete(held);
       if (current.held.size) return;
       if (type.subscriptions.get(id) === current) type.subscriptions.delete(id);
-      // Only a subscription that was set up is told it ended.
-      current.ready.then(subscription => { if (type.onUnsubscribe) settle(() => type.onUnsubscribe!(subscription)); }, () => {});
+      // Only a subscription that was set up is told it ended. A teardown that fails has nobody to tell, and must not
+      // take the process down.
+      current.ready.then(subscription => type.onUnsubscribe?.(subscription)).catch(() => {});
     } };
     current.held.add(held);
     try {
@@ -463,12 +424,10 @@ export function createEvents(): Events {
      * Declares an event type and returns the function that emits it. `match` decides which subscriptions receive an
      * event from their arguments, and `transform` shapes its data for each.
      */
-    event<A, D>(name: string, { description, inputSchema, payloadSchema, _meta, match, transform, delivery = OFFERED, authorize, onSubscribe, onUnsubscribe }: EventDefinition<A, D>): Emitter<D, A> {
+    event<A, D>(name: string, definition: EventDefinition<A, D>): Emitter<D, A> {
       if (types.has(name)) throw new Error(`Event ${name} is already declared.`);
-      const unknown = delivery.filter(mode => !OFFERED.includes(mode));
-      if (unknown.length || !delivery.length) throw new Error(`Event ${name} is delivered by ${delivery.join(", ") || "nothing"}, but only ${OFFERED.join(", ")} are served.`);
       const type: Type<A, D> = {
-        name, order: ++declared, description, inputSchema, payloadSchema, _meta, delivery, match, transform, authorize, onSubscribe, onUnsubscribe,
+        ...definition, name, order: ++declared, delivery: definition.delivery ?? OFFERED,
         sequence: 0, dropped: 0, kept: [], sinks: new Set(), subscriptions: new Map(), holds: new Map(), present: new Set(),
       };
       types.set(name, type);
@@ -484,7 +443,7 @@ export function createEvents(): Events {
           for (const sink of type.sinks) sink();
         },
         cursor() {
-          return position(type);
+          return position(type.sequence);
         },
         terminate(id, error = forbidden) {
           if (id !== undefined) return endSubscription(type, id, error);
@@ -530,19 +489,18 @@ export function createEvents(): Events {
 
     /** Serves the declared event types on an MCP server: events/list, events/poll and events/stream. */
     serve(mcp) {
-      // The custom methods are registered through the parts of the server this module uses.
-      const server = ("server" in mcp ? mcp.server : mcp) as unknown as Served;
+      const server = "server" in mcp ? mcp.server : mcp;
       // The sketch declares capabilities.events. The MCP SDK's client drops top-level capabilities it does not know,
       // so the extension is declared under capabilities.extensions too, where SDK clients read it.
       // Clients are never told the event types changed: over Holon's stateless HTTP, the notification reaches none.
-      server.registerCapabilities({ events: { listChanged: false }, extensions: { [EVENTS_EXTENSION]: { listChanged: false } } });
+      server.registerCapabilities({ events: { listChanged: false }, extensions: { [EVENTS_EXTENSION]: { listChanged: false } } } as ServerCapabilities);
       const json = (schema: StandardSchemaWithJSON) => schema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
       server.setRequestHandler("events/list", { params }, request => {
         const all = [...types.values()];
         let start = 0;
         if (request.cursor != null) {
           const after = Number(request.cursor);
-          if (typeof request.cursor !== "string" || !Number.isInteger(after)) throw new ProtocolError(INVALID_PARAMS, "Invalid cursor for events/list");
+          if (typeof request.cursor !== "string" || !Number.isInteger(after)) throw new ProtocolError(ProtocolErrorCode.InvalidParams, "Invalid cursor for events/list");
           start = all.findIndex(type => type.order > after);
           if (start < 0) start = all.length;
         }
@@ -561,19 +519,19 @@ export function createEvents(): Events {
       });
 
       server.setRequestHandler("events/poll", { params }, async (request, ctx) => {
-        const { type, subscription: subscribed } = await subscription(request, ctx.http, "poll");
+        const { type, subscription: subscribed, cursor, maxAgeMs, maxEvents } = await subscription(request, ctx.http, "poll");
         // Taken before the lease, which waits for onSubscribe. The sketch's poll from null returns no events and a
         // fresh cursor: this one is where the subscription opened, so the next poll has what onSubscribe emitted.
         const opened = type.sequence;
         const held = await lease(type, subscribed);
         // Each poll is answered for its own caller, with the lease's id.
-        const { events, start, failures, ...rest } = since(type, { ...subscribed, id: held.id, untargetable: held.untargetable }, request.cursor, { maxAgeMs: request.maxAgeMs, maxEvents: request.maxEvents, opened, ...(request.cursor == null && { until: opened }) });
+        const { events, start, failures, ...rest } = since(type, { ...subscribed, id: held.id, untargetable: held.untargetable }, cursor, { maxAgeMs, maxEvents, opened, ...(cursor === null && { until: opened }) });
         // A poll carries its cursor once, for the whole response.
         return { events: events.map(({ cursor, ...event }) => event), ...rest, nextPollMs: INTERVAL };
       });
 
       server.setRequestHandler("events/stream", { params }, async (request, ctx) => {
-        const { type, subscription: subscribed } = await subscription(request, ctx.http, "push");
+        const { type, subscription: subscribed, cursor: from, maxAgeMs } = await subscription(request, ctx.http, "push");
         const { signal } = ctx.mcpReq;
         const meta = { [SUBSCRIPTION_ID_META_KEY]: ctx.mcpReq.id };
         let done = false;
@@ -623,7 +581,7 @@ export function createEvents(): Events {
         // The stream follows its cursor, and emitted events wake it. What it is owed waits in the buffer, not here, so
         // a slow client is not owed more memory than one batch; when what it is owed is no longer kept, it is told of
         // the gap.
-        let cursor: string | null = request.cursor ?? null;
+        let cursor = from;
         let behind = true;
         const sink = () => {
           // Nothing emitted after the app terminated the stream is for it.
@@ -652,7 +610,7 @@ export function createEvents(): Events {
           while (!done) {
             if (behind) {
               behind = false;
-              const result = since(type, held, cursor, { ...(first && request.maxAgeMs !== undefined && { maxAgeMs: request.maxAgeMs }), opened, until });
+              const result = since(type, held, cursor, { ...(first && { maxAgeMs }), opened, until });
               // The stream is confirmed before anything else is said on it.
               if (first || result.truncated) await notify("active", { cursor: result.start, truncated: result.truncated });
               if (first) beat = heartbeats();

package/src/ext/files.client.ts

@@ -6,7 +6,7 @@ import { EXTENSION, type Download } from "./files.js";
 
 type Json = Record<string, unknown>;
 
-export interface FileConnection {
+interface FileConnection {
   client: Pick<Client, "getServerCapabilities">;
   resolved: { endpoint: URL | string; fileOrigins?: string[]; installationUID?: string };
   authorization?: string;
@@ -14,7 +14,7 @@ export interface FileConnection {
 
 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>;
+type Files = Map<string, Attachment>;
 
 const list = (value: unknown): unknown[] => Array.isArray(value) ? value : [];
 const isObject = (value: unknown): value is Json => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -26,7 +26,7 @@ function refuse(reason: string): never {
   throw new Error(reason);
 }
 
-export function settings({ client }: FileConnection): Json | undefined {
+function settings({ client }: FileConnection): Json | undefined {
   const advertised = client.getServerCapabilities()?.extensions?.[EXTENSION];
   return isObject(advertised) && advertised.revision == null ? advertised : undefined;
 }
@@ -143,6 +143,7 @@ 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: string) => host === "localhost" || host.endsWith(".localhost") || /^127\.\d+\.\d+\.\d+$/.test(host) || host === "[::1]";
 const expired = (target: { expiresAt?: string }) => target.expiresAt !== undefined && Date.parse(target.expiresAt) <= Date.now();
+const timestamp = (value: unknown): value is string | undefined => value === undefined || typeof value === "string" && TIMESTAMP.test(value) && !Number.isNaN(Date.parse(value));
 
 function parse(url: string): URL | undefined {
   try { return new URL(url); } catch { return undefined; }
@@ -156,7 +157,7 @@ function check(raw: unknown, kind: "upload" | "download", { resolved }: FileConn
   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 (!timestamp(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 ?? {}) as Record<string, string>;
   let form: Form | undefined;
@@ -175,12 +176,6 @@ function check(raw: unknown, kind: "upload" | "download", { resolved }: FileConn
       }
       form = { fileField: raw.fileField, fields: fields as Form["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 as number) < 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)) {
@@ -283,14 +278,20 @@ export async function upload(request: Json, files: Files, connection: FileConnec
   return requestState;
 }
 
-function download(raw: unknown, connection: FileConnection): Download {
+function download(raw: unknown, connection: FileConnection): Download | undefined {
   const { name, mimeType, size, digest, expiresAt }: Json = present(raw) ?? {};
-  const label = `Downloading ${quoted(typeof name === "string" ? name : undefined)}`;
+  if (name !== undefined && typeof name !== "string" || typeof mimeType !== "string" || typeof size !== "number" || !Number.isSafeInteger(size) || size < 0 || !timestamp(expiresAt)) return undefined;
+  let value: string | undefined;
+  if (digest !== undefined) {
+    const given = present(digest);
+    if (!given || Object.keys(given).some(key => key !== "algorithm" && key !== "value") || given.algorithm !== "sha-256" || typeof given.value !== "string") return undefined;
+    value = given.value;
+  }
+  const label = `Downloading ${quoted(name)}`;
   const blob = async ({ signal }: { signal?: AbortSignal } = {}) => {
     let target: Target;
     try { target = check(raw, "download", connection); } catch (error) { throw new Error(`${label} was refused: its target was rejected (${(error as Error).message}).`); }
     if (expired(target)) throw new Error(`${label} was refused: its target expired.`);
-    const declared = size as number;
     const chunks: Uint8Array[] = [];
     let received = 0;
     try {
@@ -304,26 +305,26 @@ function download(raw: unknown, connection: FileConnection): Download {
         const chunk = await reader.read();
         if (chunk.done) break;
         received += chunk.value.byteLength;
-        if (received > declared) {
+        if (received > size) {
           await reader.cancel();
-          throw new Error(`more than the declared ${declared} bytes; discarded`);
+          throw new Error(`more than the declared ${size} 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 as string });
-    if (digest && await sha256(file) !== (digest as { value: string }).value) throw new Error(`${label} failed (the bytes do not match the digest; discarded).`);
+    if (received !== size) throw new Error(`${label} failed (${received} bytes, not the declared ${size}; discarded).`);
+    const file = new Blob(chunks, { type: mimeType });
+    if (value !== undefined && await sha256(file) !== 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 }) as Download;
+  return Object.freeze({ ...(name !== undefined && { name }), mimeType, size, ...(value !== undefined && { digest: { algorithm: "sha-256" as const, value } }), ...(expiresAt !== undefined && { expiresAt }), blob });
 }
 
 export function downloads<R extends { resultType?: string; _meta?: object }>(result: R, connection: FileConnection): R & { downloads?: Download[] } {
   if (result.resultType === "input_required" || !isObject(result._meta) || !(EXTENSION in result._meta)) return result;
   const { [EXTENSION]: meta, ...rest } = result._meta;
-  const handles = settings(connection) ? list((meta as { downloads?: unknown } | null | undefined)?.downloads).map(target => download(target, connection)) : [];
+  const handles = settings(connection) ? list((meta as { downloads?: unknown } | null | undefined)?.downloads).flatMap(target => download(target, connection) ?? []) : [];
   return { ...result, _meta: rest, ...(handles.length > 0 && { downloads: handles }) };
 }

package/src/ext/files.ts

@@ -1,7 +1,7 @@
 /** Identifier of the MCP files extension (draft), the key under which a client and a server declare it in their capabilities. */
 export const EXTENSION = "io.modelcontextprotocol/files";
 
-/** A file a tool returned for the caller to fetch. Its fields come from the server and are untrusted. */
+/** A file a tool returned for the caller to fetch. Its fields come from the server: they have the types below, but their values are untrusted. */
 export interface Download {
   readonly name?: string;
   readonly mimeType: string;

package/src/link.ts

@@ -0,0 +1,136 @@
+import { Client, SdkHttpError, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import type { CacheableRequestOptions, PriorDiscovery, StandardSchemaV1 } from "@modelcontextprotocol/client";
+import { EXTENSION } from "./ext/files.js";
+import { acceptUploadRequests } from "./ext/files.client.js";
+import type { CallOptions } from "./protocol.js";
+import type { Binding, Identity, ToolSession } from "./runtime.js";
+
+interface Connection {
+  client: Client;
+  resolved: Binding;
+  authorization?: string;
+  ready: Promise<void>;
+  answered: boolean;
+  close(): Promise<void>;
+}
+
+export interface Link {
+  readonly name: string;
+  session<T>(options: CallOptions | undefined, run: (client: ToolSession, connection?: Connection) => Promise<T>): Promise<T>;
+  endpoint(what: string): Binding;
+  connect(binding: Binding): Connection;
+  close(): Promise<void>;
+}
+
+// Environment-bound calls reuse the last server/discover result for the same endpoint and token instead of discovering
+// the server on every call. A dependency keeps only its latest result, so a changed endpoint or token replaces it.
+const DISCOVERY: unique symbol = Symbol("discovery");
+const discovered = new Map<string, { key: string; prior: PriorDiscovery; expires: number }>();
+const LEGACY_VERDICT_MS = 10 * 60 * 1000;
+
+type Endpoint = Binding & { [DISCOVERY]?: string };
+/** Without an endpoint, a binding is served by the session hook or not at all. */
+type Resolved = Endpoint | { endpoint?: undefined };
+
+export function environment(name: string): Endpoint {
+  const prefix = `${name.toUpperCase().replaceAll("-", "_")}_MCP_`;
+  const endpoint = process.env[`${prefix}URL`];
+  const token = process.env[`${prefix}TOKEN`];
+  if (endpoint) return { endpoint, scoped: true, [DISCOVERY]: `${endpoint} ${token ?? ""}`, ...(token && { authProvider: { token: async () => token } }) };
+  throw new Error(`Dependency ${name} is unavailable (${prefix}URL). Provide a binding or set the environment variable.`);
+}
+
+function connect(identity: Identity, resolved: Binding, prior?: PriorDiscovery, onclose?: (connection: Connection) => void): Connection {
+  // Every client can be asked: a call answers with elicit, or the question reaches its caller. Servers must not assume a client answers: https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr#server-requirements-basic-workflow
+  // On 2026-07-28 the client sends these capabilities in every request's _meta: https://github.com/modelcontextprotocol/typescript-sdk/blob/fcef852f6cdafea07f36cf6fae69b37c8adf85be/packages/client/src/client/client.ts#L700-L711
+  const client = new Client({ name: identity.name, version: identity.version }, { capabilities: { elicitation: { form: {}, url: {} }, extensions: { [EXTENSION]: { upload: {}, download: {} } } }, versionNegotiation: { mode: "auto" } });
+  const endpoint = new URL(resolved.endpoint);
+  const transport = acceptUploadRequests(new StreamableHTTPClientTransport(endpoint, { authProvider: resolved.authProvider, fetch: async (input, init) => {
+    if (String(input) === endpoint.href) connection.authorization = new Headers(init?.headers).get("authorization") ?? undefined;
+    const response = await (resolved.fetch ?? fetch)(input, init);
+    connection.answered ||= response.ok;
+    return response;
+  }, requestInit: { credentials: "include", redirect: "error", headers: resolved.installationUID ? { "X-Holon-Installation-UID": resolved.installationUID } : {} } }));
+  transport.onclose = () => onclose?.(connection);
+  const ready = client.connect(transport, { prior }).catch(async (error: unknown) => {
+    await transport.close();
+    throw error;
+  });
+  const connection: Connection = { client, resolved, ready, answered: false, close: async () => {
+    await transport.terminateSession().catch(() => {});
+    await transport.close();
+    await ready.catch(() => {});
+  } };
+  return connection;
+}
+
+export function createLink(identity: Identity, name: string, { binding, resolve, host }: { binding: unknown; resolve?: (app: string) => Binding | undefined; host?: ToolSession | undefined }): Link {
+  const current = (): Resolved | undefined => (binding as Resolved | undefined) ?? resolve?.(name);
+  let kept: Connection | undefined;
+  const session = async <T>(options: CallOptions | undefined, run: (client: ToolSession, connection?: Connection) => Promise<T>): Promise<T> => {
+    options?.signal?.throwIfAborted();
+    if (host) return run(host);
+    const resolved = current();
+    if (!resolved?.endpoint) throw new Error(`Dependency ${name} is unavailable. Provide a binding.`);
+    const scoped = resolved.scoped === true;
+    const key = resolved[DISCOVERY];
+    const cached = discovered.get(name);
+    const prior = key !== undefined && cached?.key === key && Date.now() < cached.expires ? cached.prior : undefined;
+    const active = scoped ? connect(identity, resolved, prior) : (kept ??= connect(identity, resolved, undefined, closed => { if (kept === closed) kept = undefined; }));
+    try {
+      await untilAborted(active.ready, options?.signal);
+      if (key !== undefined && !prior) {
+        const discover = active.client.getDiscoverResult();
+        discovered.set(name, { key, prior: discover ? { kind: "modern", discover } : { kind: "legacy" }, expires: discover ? Infinity : Date.now() + LEGACY_VERDICT_MS });
+      }
+      return await run(active.client, active);
+    } catch (error) {
+      // A server that no longer speaks the discovered protocol rejects the first request without running it.
+      if (!prior || active.answered || !(SdkHttpError.isInstance(error) && error.status === 400)) throw error;
+      discovered.delete(name);
+      return session(options, run);
+    } finally { if (scoped) await active.close(); }
+  };
+  return {
+    name,
+    session,
+    endpoint(what) {
+      const resolved = current();
+      if (!resolved?.endpoint) throw new Error(`${what} requires an endpoint binding.`);
+      return resolved;
+    },
+    connect: resolved => connect(identity, resolved),
+    close: async () => { await kept?.close(); },
+  };
+}
+
+export function sleep(milliseconds: number, signal?: AbortSignal): Promise<void> {
+  return new Promise(resolve => {
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, milliseconds);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+export function untilAborted<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  return new Promise((resolve, reject) => {
+    const aborted = () => reject(signal.reason);
+    signal.addEventListener("abort", aborted, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", aborted));
+  });
+}
+
+// The MCP client ends a request after 60 s unless given a timeout. A request without one waits as long as a timer can
+// (2^31 - 1 ms, about 24.8 days). A request with one asks for progress, and progress restarts its timeout.
+export function patient(options?: CacheableRequestOptions): CacheableRequestOptions {
+  return options?.timeout === undefined
+    ? { ...options, timeout: 2 ** 31 - 1 }
+    : { onprogress: () => {}, resetTimeoutOnProgress: true, ...options };
+}
+
+export const unchecked = <T>(): StandardSchemaV1<unknown, T> => ({ "~standard": { version: 1, vendor: "holon-sh", validate: value => ({ value: (value ?? {}) as T }) } });

package/src/page.ts

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import type { McpServer } from "@modelcontextprotocol/server";
+
+// MCP Apps names a view with a ui:// URI and serves it as this type. An app has one page, so the URI names no app and
+// survives renaming one.
+// https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
+const uri = "ui://page";
+const mimeType = "text/html;profile=mcp-app";
+
+/** An app's page, as the view an MCP Apps host shows with a tool's result. */
+export interface Page {
+  /** A tool's `_meta`, so that hosts show the page with what the tool returns. */
+  meta: { ui: { resourceUri: string } };
+  /** Offers the page to a server's clients as its view. */
+  serve(server: Pick<McpServer, "registerResource">): void;
+}
+
+/**
+ * Makes an app's page a view: `file` is the page built as one HTML file, and `ui` the view's `_meta.ui`, such as its
+ * `csp`.
+ *
+ * ```ts
+ * const page = createPage(new URL("../dist/mcp/index.html", import.meta.url));
+ * server.registerTool("open", { description: "Opens it", _meta: page.meta }, open);
+ * page.serve(server);
+ * ```
+ */
+export function createPage(file: URL, ui: Record<string, unknown> = {}): Page {
+  return {
+    meta: { ui: { resourceUri: uri } },
+    serve: server =>
+      void server.registerResource("Page", uri, { mimeType }, async () => ({
+        contents: [{ uri, mimeType, text: await readFile(file, "utf8"), _meta: { ui } }],
+      })),
+  };
+}