@nimblebrain/synapse 0.18.0 → 0.20.0

package/dist/{chunk-3YSXPBEQ.js → chunk-TR2YNWZ5.js}

@@ -1,5 +1,17 @@
-import { detectHost, foldFontFaces, applyTheme, fontFacesKey, extractTheme } from './chunk-HKRTDGXN.js';
-import { INITIALIZE_METHOD, LATEST_PROTOCOL_VERSION, HOST_CONTEXT_CHANGED_METHOD, INITIALIZED_METHOD, MESSAGE_METHOD, OPEN_LINK_METHOD, RESOURCE_TEARDOWN_METHOD, TOOL_CANCELLED_METHOD, TOOL_INPUT_PARTIAL_METHOD, TOOL_INPUT_METHOD, TOOL_RESULT_METHOD } from '@modelcontextprotocol/ext-apps';
+import { extractHostFontCss, applyTheme, extractTheme } from './chunk-DJS2FKBN.js';
+import { TOOLS_CALL_METHOD, NIMBLEBRAIN_EXTENSIONS, resolveEventMethod, KEYDOWN_METHOD } from './chunk-H3INUKA3.js';
+import { App, TOOL_INPUT_METHOD, TOOL_INPUT_PARTIAL_METHOD, TOOL_RESULT_METHOD, TOOL_CANCELLED_METHOD, applyHostFonts, HOST_CONTEXT_CHANGED_METHOD, RESOURCE_TEARDOWN_METHOD, SIZE_CHANGED_METHOD } from '@modelcontextprotocol/ext-apps';
+import { CallToolResultSchema, ResultSchema } from '@modelcontextprotocol/sdk/types.js';
+
+// src/errors.ts
+var HostCapabilityError = class extends Error {
+  capability;
+  constructor(feature, capability) {
+    super(`${feature} is not supported in this host: it did not declare ${capability}`);
+    this.name = "HostCapabilityError";
+    this.capability = capability;
+  }
+};
 
 // src/internals.ts
 var INTERNALS = /* @__PURE__ */ new WeakMap();
@@ -63,14 +75,18 @@ function parseCallToolResult(result) {
 }
 
 // src/task-handle.ts
-var TOOLS_CALL_METHOD = "tools/call";
+var TASKS_EXTENSION_ID = "io.modelcontextprotocol/tasks";
+function readHostTasksCapability(capabilities) {
+  const entry = capabilities?.experimental?.[TASKS_EXTENSION_ID];
+  return entry && typeof entry === "object" && !Array.isArray(entry) ? entry : void 0;
+}
 var TASKS_GET_METHOD = "tasks/get";
 var TASKS_RESULT_METHOD = "tasks/result";
 var TASKS_CANCEL_METHOD = "tasks/cancel";
 var TASKS_STATUS_NOTIFICATION_METHOD = "notifications/tasks/status";
-function createTaskStatusRouter(transport) {
+function createTaskStatusRouter(subscribe) {
   const listeners = /* @__PURE__ */ new Map();
-  const unsub = transport.onMessage(TASKS_STATUS_NOTIFICATION_METHOD, (rawParams) => {
+  const unsub = subscribe(TASKS_STATUS_NOTIFICATION_METHOD, (rawParams) => {
     if (!rawParams) return;
     const params = rawParams;
     const taskId = params.taskId;
@@ -109,18 +125,17 @@ async function callToolAsTask(app, toolName, args, options) {
   const deps = internalsFor(app);
   const hostTasks = deps.hostTasksCapability;
   if (!hostTasks?.requests?.tools?.call) {
-    throw new Error(
-      "callToolAsTask: host did not advertise tasks.requests.tools.call in its capabilities. Per MCP 2025-11-25 \xA7, requestors MUST NOT task-augment a tools/call without matching receiver capability. Fall back to `app.callTool`."
+    throw new HostCapabilityError(
+      "callToolAsTask",
+      `${TASKS_EXTENSION_ID} with requests.tools.call`
     );
   }
   const taskParam = {};
   if (options?.ttl !== void 0) taskParam.ttl = options.ttl;
-  const crossServer = options?.internal ?? deps.internalApp;
   const callParams = {
     name: toolName,
     arguments: args ?? {},
-    task: taskParam,
-    ...crossServer ? { server: deps.appName } : {}
+    task: taskParam
   };
   const raw = await deps.request(
     TOOLS_CALL_METHOD,
@@ -232,32 +247,18 @@ function parseToolResultParams(params) {
   }
   return { content: rawContent ?? null, structuredContent: null, raw };
 }
-var DATA_CHANGED_METHOD = "synapse/data-changed";
-var ACTION_METHOD = "synapse/action";
-var REQUEST_FILE_METHOD = "synapse/request-file";
-var DOWNLOAD_FILE_METHOD = "synapse/download-file";
-var EVENT_MAP = {
-  "tool-result": TOOL_RESULT_METHOD,
-  "tool-input": TOOL_INPUT_METHOD,
-  "tool-input-partial": TOOL_INPUT_PARTIAL_METHOD,
-  "tool-cancelled": TOOL_CANCELLED_METHOD,
-  teardown: RESOURCE_TEARDOWN_METHOD
-};
-function resolveEventMethod(name) {
-  return EVENT_MAP[name] ?? name;
-}
 
 // src/keyboard.ts
 var KeyboardForwarder = class {
   listener;
   destroyed = false;
-  constructor(transport, customKeys) {
+  constructor(send, customKeys) {
     const config = customKeys ?? null;
     this.listener = (event) => {
       if (this.destroyed) return;
       if (this.shouldForward(event, config)) {
         event.preventDefault();
-        transport.send("synapse/keydown", {
+        send(KEYDOWN_METHOD, {
           key: event.key,
           ctrlKey: event.ctrlKey,
           metaKey: event.metaKey,
@@ -289,271 +290,125 @@ var KeyboardForwarder = class {
     return false;
   }
 };
-
-// src/resize.ts
 function createResizer(send, autoResize) {
   let destroyed = false;
   let observer = null;
-  let rafId = null;
   function measureAndSend() {
     if (destroyed) return;
     const width = document.body.scrollWidth;
     const height = document.body.scrollHeight;
-    send("ui/notifications/size-changed", { width, height });
+    send(SIZE_CHANGED_METHOD, { width, height });
   }
   function resize(width, height) {
     if (destroyed) return;
     if (width !== void 0 && height !== void 0) {
-      send("ui/notifications/size-changed", { width, height });
+      send(SIZE_CHANGED_METHOD, { width, height });
     } else {
       measureAndSend();
     }
   }
-  if (autoResize && typeof ResizeObserver !== "undefined") {
-    observer = new ResizeObserver(() => {
-      if (destroyed) return;
-      if (rafId !== null) cancelAnimationFrame(rafId);
-      rafId = requestAnimationFrame(() => {
-        rafId = null;
-        measureAndSend();
-      });
-    });
-    observer.observe(document.body);
-  }
   function destroy() {
     if (destroyed) return;
     destroyed = true;
-    if (rafId !== null) cancelAnimationFrame(rafId);
     observer?.disconnect();
     observer = null;
   }
   return { resize, measureAndSend, destroy };
 }
 
-// src/transport.ts
-var SynapseTransport = class {
-  counter = 0;
-  destroyed = false;
-  pending = /* @__PURE__ */ new Map();
-  handlers = /* @__PURE__ */ new Map();
-  listener;
-  constructor() {
-    this.listener = (event) => this.handleMessage(event);
-    window.addEventListener("message", this.listener);
-  }
-  send(method, params) {
-    if (this.destroyed) return;
-    const msg = {
-      jsonrpc: "2.0",
-      method,
-      ...params !== void 0 && { params }
-    };
-    window.parent.postMessage(msg, "*");
-  }
-  request(method, params) {
-    if (this.destroyed) {
-      return Promise.reject(new Error("Transport destroyed"));
-    }
-    const id = `syn-${++this.counter}`;
-    const msg = {
-      jsonrpc: "2.0",
-      method,
-      id,
-      ...params !== void 0 && { params }
-    };
-    return new Promise((resolve, reject) => {
-      this.pending.set(id, { resolve, reject });
-      window.parent.postMessage(msg, "*");
-    });
-  }
-  onMessage(method, callback) {
-    if (!this.handlers.has(method)) {
-      this.handlers.set(method, /* @__PURE__ */ new Set());
-    }
-    this.handlers.get(method)?.add(callback);
-    return () => {
-      const set = this.handlers.get(method);
-      if (set) {
-        set.delete(callback);
-        if (set.size === 0) {
-          this.handlers.delete(method);
-        }
-      }
-    };
-  }
-  destroy() {
-    if (this.destroyed) return;
-    this.destroyed = true;
-    window.removeEventListener("message", this.listener);
-    const error = new Error("Transport destroyed");
-    for (const entry of this.pending.values()) {
-      entry.reject(error);
-    }
-    this.pending.clear();
-    this.handlers.clear();
-  }
-  handleMessage(event) {
-    if (this.destroyed) return;
-    const data = event.data;
-    if (!data || data.jsonrpc !== "2.0") return;
-    if ("id" in data && data.id && !("method" in data)) {
-      const response = data;
-      const entry = this.pending.get(response.id);
-      if (!entry) return;
-      this.pending.delete(response.id);
-      if (response.error) {
-        const err = new Error(response.error.message);
-        err.code = response.error.code;
-        err.data = response.error.data;
-        entry.reject(err);
-      } else {
-        entry.resolve(response.result);
-      }
-      return;
-    }
-    if ("method" in data && !("id" in data && data.id)) {
-      const notification = data;
-      const set = this.handlers.get(notification.method);
-      if (set) {
-        for (const handler of set) {
-          handler(notification.params);
-        }
-      }
-    }
-  }
-};
-
 // src/connect.ts
-var READ_RESOURCE_METHOD = "resources/read";
-var UPDATE_MODEL_CONTEXT_METHOD = "ui/update-model-context";
+var NIMBLEBRAIN_HOST = "nimblebrain";
+var CHAT_CONTEXT_META_KEY = "ai.nimblebrain/context";
+var NO_DEADLINE = { timeout: 2147483647 };
+var MAPPED_EVENTS = [
+  ["toolinput", TOOL_INPUT_METHOD],
+  ["toolinputpartial", TOOL_INPUT_PARTIAL_METHOD],
+  ["toolresult", TOOL_RESULT_METHOD],
+  ["toolcancelled", TOOL_CANCELLED_METHOD]
+];
 async function connect(options) {
-  const { name, version, autoResize = false, internal = false, forwardKeys } = options;
-  const transport = new SynapseTransport();
+  const { name, version, autoResize = false, forwardKeys } = options;
   let destroyed = false;
-  let hostContext = {};
   let hostInfo = { name: "unknown", version: "unknown" };
   let isNimbleBrainHost = false;
   let toolInfo = null;
   let containerDimensions = null;
+  let hostCapabilities = {};
   let hostTasksCapability;
   let keyboard = null;
-  let fontFaces;
-  function resolveTheme() {
-    const theme = extractTheme(hostContext);
-    return fontFaces ? { ...theme, fontFaces } : theme;
-  }
-  const handlers = /* @__PURE__ */ new Map();
-  const themeCallbacks = /* @__PURE__ */ new Set();
-  const hostContextCallbacks = /* @__PURE__ */ new Set();
-  const dataCallbacks = /* @__PURE__ */ new Set();
-  const actionCallbacks = /* @__PURE__ */ new Set();
-  const resizer = createResizer((method, params) => transport.send(method, params), autoResize);
-  resizer.measureAndSend();
+  let appliedTheme = { mode: "light", tokens: {} };
   const appCapabilities = {
     tasks: {
       cancel: {},
       requests: { tools: { call: {} } }
     }
   };
-  const initParams = {
-    protocolVersion: LATEST_PROTOCOL_VERSION,
-    appInfo: { name, version },
-    appCapabilities
-  };
-  const result = await transport.request(
-    INITIALIZE_METHOD,
-    initParams
+  const client = new App(
+    { name, version },
+    appCapabilities,
+    { autoResize }
   );
-  if (result) {
-    const detected = detectHost(result);
-    isNimbleBrainHost = detected.isNimbleBrain;
-    hostInfo = {
-      name: result.hostInfo?.name ?? "unknown",
-      version: result.hostInfo?.version ?? "unknown"
-    };
-    const rawTasks = result.hostCapabilities?.tasks;
-    hostTasksCapability = rawTasks && typeof rawTasks === "object" && !Array.isArray(rawTasks) ? rawTasks : void 0;
-    const ctx = result.hostContext;
-    if (ctx) {
-      hostContext = ctx;
-      fontFaces = foldFontFaces(fontFaces, ctx);
-      if (ctx.toolInfo && typeof ctx.toolInfo === "object") {
-        toolInfo = { tool: ctx.toolInfo.tool ?? {} };
-      }
-      if (ctx.containerDimensions && typeof ctx.containerDimensions === "object") {
-        containerDimensions = ctx.containerDimensions;
-      }
-      const theme = resolveTheme();
-      applyTheme(theme.mode, theme.tokens, theme.fontFaces);
-    }
+  function currentContext() {
+    return client.getHostContext() ?? {};
+  }
+  function resolveTheme() {
+    return extractTheme(currentContext());
   }
-  if (forwardKeys && isNimbleBrainHost) {
-    keyboard = new KeyboardForwarder(transport, forwardKeys === true ? void 0 : forwardKeys);
+  function applyFontsFrom(ctx) {
+    const css = extractHostFontCss(ctx);
+    if (css !== void 0 && typeof document !== "undefined") applyHostFonts(css);
   }
-  function fanOutRaw(method, params) {
+  function applyResolvedTheme() {
+    const theme = resolveTheme();
+    applyTheme(theme.mode, theme.tokens);
+    appliedTheme = theme;
+    return theme;
+  }
+  const handlers = /* @__PURE__ */ new Map();
+  const themeCallbacks = /* @__PURE__ */ new Set();
+  const hostContextCallbacks = /* @__PURE__ */ new Set();
+  function fanOut(method, payload) {
     const set = handlers.get(method);
     if (!set) return;
-    for (const handler of set) handler(params);
+    for (const handler of set) handler(payload);
+  }
+  function sendRaw(method, params) {
+    if (destroyed) return;
+    void client.notification({ method, params }).catch(() => {
+    });
+  }
+  function requestRaw(method, params) {
+    return client.request({ method, params }, ResultSchema, NO_DEADLINE);
+  }
+  for (const [event, method] of MAPPED_EVENTS) {
+    client.addEventListener(event, (params) => {
+      if (destroyed) return;
+      fanOut(
+        method,
+        method === TOOL_RESULT_METHOD ? parseToolResultParams(params) : params
+      );
+    });
   }
-  transport.onMessage(HOST_CONTEXT_CHANGED_METHOD, (params) => {
+  client.addEventListener("hostcontextchanged", (params) => {
     if (destroyed) return;
-    const ctx = params ?? {};
-    const prevTheme = resolveTheme();
-    hostContext = { ...hostContext, ...ctx };
-    fontFaces = foldFontFaces(fontFaces, ctx);
-    const nextTheme = resolveTheme();
-    applyTheme(nextTheme.mode, nextTheme.tokens, nextTheme.fontFaces);
-    for (const cb of hostContextCallbacks) cb(hostContext);
-    fanOutRaw(HOST_CONTEXT_CHANGED_METHOD, params);
+    const prevTheme = appliedTheme;
+    applyFontsFrom(params);
+    const nextTheme = applyResolvedTheme();
+    const merged = currentContext();
+    for (const cb of hostContextCallbacks) cb(merged);
+    fanOut(HOST_CONTEXT_CHANGED_METHOD, params);
     if (!themesEqual(prevTheme, nextTheme)) {
       for (const cb of themeCallbacks) cb(nextTheme);
     }
   });
-  transport.onMessage(DATA_CHANGED_METHOD, (params) => {
-    if (destroyed) return;
-    fanOutRaw(DATA_CHANGED_METHOD, params);
-    if (!params) return;
-    const event = {
-      source: "agent",
-      server: params.server ?? "",
-      tool: params.tool ?? ""
-    };
-    for (const cb of dataCallbacks) cb(event);
-  });
-  transport.onMessage(ACTION_METHOD, (params) => {
+  client.onteardown = (params) => {
+    if (!destroyed) fanOut(RESOURCE_TEARDOWN_METHOD, params);
+    return {};
+  };
+  client.fallbackNotificationHandler = async (notification) => {
     if (destroyed) return;
-    fanOutRaw(ACTION_METHOD, params);
-    if (!params || typeof params.type !== "string") return;
-    const action2 = {
-      type: params.type,
-      payload: params.payload ?? {},
-      requiresConfirmation: params.requiresConfirmation === true,
-      label: typeof params.label === "string" ? params.label : void 0
-    };
-    for (const cb of actionCallbacks) cb(action2);
-  });
-  const subscribedMethods = /* @__PURE__ */ new Set([
-    HOST_CONTEXT_CHANGED_METHOD,
-    DATA_CHANGED_METHOD,
-    ACTION_METHOD
-  ]);
-  function ensureTransportSub(method) {
-    if (subscribedMethods.has(method)) return;
-    subscribedMethods.add(method);
-    const isToolResult = method === TOOL_RESULT_METHOD;
-    transport.onMessage(method, (params) => {
-      if (destroyed) return;
-      const set = handlers.get(method);
-      if (!set) return;
-      for (const handler of set) {
-        if (isToolResult) {
-          handler(parseToolResultParams(params));
-        } else {
-          handler(params);
-        }
-      }
-    });
-  }
+    fanOut(notification.method, notification.params);
+  };
   function subscribe(event, handler) {
     switch (event) {
       case "theme-changed":
@@ -566,21 +421,10 @@ async function connect(options) {
         return () => {
           hostContextCallbacks.delete(handler);
         };
-      case "data-changed":
-        dataCallbacks.add(handler);
-        return () => {
-          dataCallbacks.delete(handler);
-        };
-      case "action":
-        actionCallbacks.add(handler);
-        return () => {
-          actionCallbacks.delete(handler);
-        };
       default: {
         const method = resolveEventMethod(event);
         if (!handlers.has(method)) handlers.set(method, /* @__PURE__ */ new Set());
         handlers.get(method)?.add(handler);
-        ensureTransportSub(method);
         return () => {
           const set = handlers.get(method);
           if (set) {
@@ -596,8 +440,36 @@ async function connect(options) {
       if (typeof handler === "function") subscribe(event, handler);
     }
   }
-  transport.send(INITIALIZED_METHOD, {});
-  const taskRouter = createTaskStatusRouter(transport);
+  await client.connect();
+  const hostVersion = client.getHostVersion();
+  hostInfo = {
+    name: hostVersion?.name ?? "unknown",
+    version: hostVersion?.version ?? "unknown"
+  };
+  isNimbleBrainHost = hostInfo.name === NIMBLEBRAIN_HOST;
+  hostCapabilities = client.getHostCapabilities() ?? {};
+  hostTasksCapability = readHostTasksCapability(hostCapabilities);
+  const initialContext = client.getHostContext();
+  if (initialContext) {
+    if (initialContext.toolInfo && typeof initialContext.toolInfo === "object") {
+      toolInfo = {
+        tool: initialContext.toolInfo.tool ?? {}
+      };
+    }
+    if (initialContext.containerDimensions && typeof initialContext.containerDimensions === "object") {
+      containerDimensions = initialContext.containerDimensions;
+    }
+    applyFontsFrom(initialContext);
+    applyResolvedTheme();
+  }
+  if (forwardKeys && hostCapabilities.experimental?.[NIMBLEBRAIN_EXTENSIONS.keydown.capability] !== void 0) {
+    keyboard = new KeyboardForwarder(sendRaw, forwardKeys === true ? void 0 : forwardKeys);
+  }
+  const resizer = createResizer(sendRaw);
+  if (!autoResize) resizer.measureAndSend();
+  const taskRouter = createTaskStatusRouter(
+    (method, handler) => subscribe(method, handler)
+  );
   const app = {
     get theme() {
       return resolveTheme();
@@ -606,7 +478,10 @@ async function connect(options) {
       return { ...hostInfo };
     },
     get hostContext() {
-      return hostContext;
+      return currentContext();
+    },
+    get hostCapabilities() {
+      return hostCapabilities;
     },
     get isNimbleBrainHost() {
       return isNimbleBrainHost;
@@ -631,52 +506,62 @@ async function connect(options) {
     },
     openLink(url) {
       if (destroyed) return;
+      if (!hostCapabilities.openLinks) {
+        window.open(url, "_blank", "noopener");
+        return;
+      }
       const params = { url };
-      transport.request(OPEN_LINK_METHOD, params).catch(() => {
+      client.openLink(params, NO_DEADLINE).catch(() => {
         window.open(url, "_blank", "noopener");
       });
     },
     updateModelContext(state, summary) {
-      if (destroyed) return;
+      if (destroyed || !hostCapabilities.updateModelContext) return;
       const params = {
         structuredContent: state,
         ...summary !== void 0 && {
           content: [{ type: "text", text: summary }]
         }
       };
-      transport.send(UPDATE_MODEL_CONTEXT_METHOD, params);
+      client.updateModelContext(params, NO_DEADLINE).catch(() => {
+      });
     },
-    async callTool(toolName, args, callOptions) {
-      const server = callOptions?.server ?? (internal ? name : void 0);
+    async callTool(toolName, args) {
+      if (!hostCapabilities.serverTools) {
+        throw new HostCapabilityError("callTool", "serverTools");
+      }
       const params = {
         name: toolName,
-        arguments: args ?? {},
-        ...server !== void 0 && { server }
+        arguments: args ?? {}
       };
-      const raw = await transport.request(TOOLS_CALL_METHOD, params);
+      const raw = await client.request(
+        { method: TOOLS_CALL_METHOD, params },
+        CallToolResultSchema,
+        NO_DEADLINE
+      );
       return parseToolResult(raw);
     },
     async readServerResource(params) {
-      const raw = await transport.request(
-        READ_RESOURCE_METHOD,
-        params
-      );
-      return raw;
+      if (!hostCapabilities.serverResources) {
+        throw new HostCapabilityError("readServerResource", "serverResources");
+      }
+      return await client.readServerResource(params, NO_DEADLINE);
     },
     sendMessage(text, context) {
-      if (destroyed) return;
+      if (destroyed || !hostCapabilities.message) return;
       const textBlock = {
         type: "text",
         text,
-        // `_meta.context` is a NimbleBrain convention; other hosts ignore it,
+        // The chat context is a NimbleBrain host field; other hosts ignore it,
         // but there is no reason to spend the bytes off one.
-        ...isNimbleBrainHost && context && { _meta: { context } }
+        ...isNimbleBrainHost && context && { _meta: { [CHAT_CONTEXT_META_KEY]: context } }
       };
       const params = {
         role: "user",
         content: [textBlock]
       };
-      transport.send(MESSAGE_METHOD, params);
+      client.sendMessage(params, NO_DEADLINE).catch(() => {
+      });
     },
     destroy() {
       if (destroyed) return;
@@ -687,34 +572,28 @@ async function connect(options) {
       handlers.clear();
       themeCallbacks.clear();
       hostContextCallbacks.clear();
-      dataCallbacks.clear();
-      actionCallbacks.clear();
-      transport.destroy();
+      void client.close();
     }
   };
   registerInternals(app, {
     send(method, params) {
-      if (destroyed) return;
-      transport.send(method, params);
+      sendRaw(method, params);
     },
     request(method, params) {
-      return transport.request(method, params);
+      return requestRaw(method, params);
     },
     onMessage(method, handler) {
-      return transport.onMessage(method, handler);
+      return subscribe(method, handler);
     },
     taskRouter,
     get hostTasksCapability() {
       return hostTasksCapability;
-    },
-    appName: name,
-    internalApp: internal
+    }
   });
   return app;
 }
 function themesEqual(a, b) {
   if (a.mode !== b.mode) return false;
-  if (fontFacesKey(a.fontFaces) !== fontFacesKey(b.fontFaces)) return false;
   const aKeys = Object.keys(a.tokens);
   const bKeys = Object.keys(b.tokens);
   if (aKeys.length !== bKeys.length) return false;
@@ -725,57 +604,55 @@ function themesEqual(a, b) {
 }
 
 // src/extensions.ts
+function hostSupports(app, extension) {
+  const { capability } = NIMBLEBRAIN_EXTENSIONS[extension];
+  return app.hostCapabilities.experimental?.[capability] !== void 0;
+}
 var DEFAULT_MAX_FILE_SIZE = 26214400;
 function action(app, name, params) {
-  if (!app.isNimbleBrainHost) return;
-  internalsFor(app).send(ACTION_METHOD, { action: name, ...params });
-}
-function downloadFile(app, filename, content, mimeType) {
-  const resolvedMime = mimeType || (content instanceof Blob ? content.type : "") || "application/octet-stream";
-  const blob = content instanceof Blob ? content : new Blob([content], { type: resolvedMime });
-  internalsFor(app).send(DOWNLOAD_FILE_METHOD, {
-    data: blob,
-    filename,
-    mimeType: resolvedMime
-  });
+  if (!hostSupports(app, "action")) return;
+  internalsFor(app).send(NIMBLEBRAIN_EXTENSIONS.action.method, { action: name, ...params });
 }
 async function pickFile(app, options) {
-  if (!app.isNimbleBrainHost) {
-    throw new Error("pickFile is not supported in this host");
-  }
-  const result = await requestFile(app, options, false);
-  if (result === null) return null;
-  return Array.isArray(result) ? result[0] ?? null : result;
+  requireRequestFile("pickFile", app);
+  const files = await requestFile(app, options, false);
+  return files[0] ?? null;
 }
 async function pickFiles(app, options) {
-  if (!app.isNimbleBrainHost) {
-    throw new Error("pickFiles is not supported in this host");
+  requireRequestFile("pickFiles", app);
+  return await requestFile(app, options, true);
+}
+function requireRequestFile(feature, app) {
+  if (!hostSupports(app, "requestFile")) {
+    throw new HostCapabilityError(feature, NIMBLEBRAIN_EXTENSIONS.requestFile.capability);
   }
-  const result = await requestFile(app, options, true);
-  if (result === null) return [];
-  return Array.isArray(result) ? result : [result];
 }
 async function requestFile(app, options, multiple) {
-  const result = await internalsFor(app).request(REQUEST_FILE_METHOD, {
+  const result = await internalsFor(app).request(NIMBLEBRAIN_EXTENSIONS.requestFile.method, {
     accept: options?.accept,
     maxSize: options?.maxSize ?? DEFAULT_MAX_FILE_SIZE,
     multiple
   });
-  if (result == null) return null;
-  if (Array.isArray(result)) {
-    return result.map(validateFileResult);
+  const files = result?.files;
+  if (files === void 0) {
+    throw new Error(
+      "ai.nimblebrain/request-file returned no `files`. The host is older than this SDK targets: it answers the picker with a bare array or `null`, which a spec-compliant client cannot parse."
+    );
+  }
+  if (!Array.isArray(files)) {
+    throw new Error("ai.nimblebrain/request-file returned a `files` field that is not an array.");
   }
-  return validateFileResult(result);
+  return files.map(validateFileResult);
 }
 function validateFileResult(value) {
   if (typeof value !== "object" || value === null || typeof value.id !== "string") {
     throw new Error(
-      "synapse/request-file returned a result without a string `id`. The host appears to be on a version older than this SDK targets \u2014 @nimblebrain/synapse 0.8.0+ requires a host with POST /v1/resources (NimbleBrain \u2265 the version that ships PR #93)."
+      "ai.nimblebrain/request-file returned a result without a string `id`. The host appears to be on a version older than this SDK targets \u2014 @nimblebrain/synapse 0.8.0+ requires a host with POST /v1/resources (NimbleBrain \u2265 the version that ships PR #93)."
     );
   }
   return value;
 }
 
-export { action, callToolAsTask, connect, downloadFile, pickFile, pickFiles };
-//# sourceMappingURL=chunk-3YSXPBEQ.js.map
-//# sourceMappingURL=chunk-3YSXPBEQ.js.map
+export { HostCapabilityError, action, callToolAsTask, connect, hostSupports, internalsFor, pickFile, pickFiles };
+//# sourceMappingURL=chunk-TR2YNWZ5.js.map
+//# sourceMappingURL=chunk-TR2YNWZ5.js.map