stitchkit 0.53.1 → 0.54.0

package/dist/tools.js

@@ -4,29 +4,37 @@ import {
 } from "./index-yez419px.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
-  contractOnlyService
-} from "./index-yydqk4fh.js";
+  DEFAULT_PROCESS_SIGNALS,
+  contractOnlyService,
+  defaultSignalSource,
+  guardSignalCallback,
+  reportSignalError
+} from "./index-b15rtha1.js";
 import {
   assertToolName,
   assertUniqueToolName,
   buildToolPresentationSchema,
   coerceJsonArgs,
+  collectToolSurface,
   collectTools,
   createCli,
+  createRuntimeToolFactory,
   createToolRunner,
+  defineCliCommand,
+  defineRuntimeTool,
   executeToolMethod,
   fetchGuarded,
   fetchPinnedDocument,
   flattenToolJsonSchema,
   formatToolError,
   isObjectPresentationSchema,
-  pollUntil,
   presentationMetadata,
   readCapped,
+  runWaitOperation,
   toolErrorFromResult,
   toolResultFromError,
   writeDownload
-} from "./index-6j4j5wf9.js";
+} from "./index-7vb44hy8.js";
 import {
   isWithinDir,
   realPathWithinDir,
@@ -54,148 +62,6 @@ import {
 
 // src/tools/agent.ts
 import { jsonSchema, tool } from "ai";
-
-// src/tools/runtime-tool.ts
-function defineRuntimeTool(definition) {
-  if (definition.transports?.length === 0) {
-    throw new Error(`Runtime tool "${definition.name}" must expose at least one transport`);
-  }
-  return definition;
-}
-function createRuntimeToolFactory(config) {
-  function parseContext(context) {
-    const parsed = config.context.parse(context);
-    return {
-      ...context,
-      ...parsed,
-      params: undefined,
-      input: context.input
-    };
-  }
-  function define(definition) {
-    if (definition.output !== undefined) {
-      const { action: action2, method: method2, meta: meta2, handler: handler2, ...tool2 } = definition;
-      const identity2 = {
-        serviceName: config.serviceName,
-        action: action2,
-        method: method2,
-        ...config.scope !== undefined && { scope: config.scope },
-        ...(meta2 ?? config.meta) !== undefined && { meta: meta2 ?? config.meta }
-      };
-      return defineRuntimeTool({
-        ...tool2,
-        identity: identity2,
-        handler: (context) => handler2(parseContext(context))
-      });
-    }
-    const { action, method, meta, handler, ...tool } = definition;
-    const identity = {
-      serviceName: config.serviceName,
-      action,
-      method,
-      ...config.scope !== undefined && { scope: config.scope },
-      ...(meta ?? config.meta) !== undefined && { meta: meta ?? config.meta }
-    };
-    return defineRuntimeTool({
-      ...tool,
-      identity,
-      handler: (context) => handler(parseContext(context))
-    });
-  }
-  return { define };
-}
-function runtimeToolSupports(definition, transport) {
-  if (definition.transports?.length === 0) {
-    throw new Error(`Runtime tool "${definition.name}" must expose at least one transport`);
-  }
-  return !definition.transports || definition.transports.includes(transport);
-}
-function runtimeToolIdentity(definition) {
-  return {
-    method: definition.identity.method,
-    desc: definition.description,
-    serviceName: definition.identity.serviceName,
-    key: definition.identity.action,
-    toolName: definition.name,
-    scope: definition.identity.scope,
-    meta: definition.identity.meta,
-    annotations: definition.annotations,
-    ui: definition.ui,
-    mcp: definition.mcp
-  };
-}
-function runtimeToolMountable(definition, assertName = true) {
-  if (assertName) {
-    assertToolName(definition.name, definition.identity.serviceName, definition.identity.action);
-  }
-  const method = {
-    ...runtimeToolIdentity(definition),
-    inputSchema: definition.input,
-    outputSchema: definition.output,
-    handler: definition.handler
-  };
-  return {
-    method,
-    name: definition.name,
-    argumentSchema: definition.input,
-    presentationSchema: buildToolPresentationSchema({
-      inputSchema: definition.input,
-      unrepresentable: "any"
-    }),
-    shouldExtend: false
-  };
-}
-
-// src/tools/surface.ts
-function duplicateLabel(transport) {
-  if (transport === "MCP")
-    return "MCP tool name";
-  if (transport === "AGENT")
-    return "agent tool name";
-  return "CLI command";
-}
-function collectToolSurface({
-  surface,
-  transport,
-  assertUniqueNames = true,
-  ...collectConfig
-}) {
-  const entries = [];
-  const names = new Set;
-  const append = (entry) => {
-    if (assertUniqueNames) {
-      assertUniqueToolName(entry.mountable.name, names.has(entry.mountable.name), duplicateLabel(transport));
-    }
-    names.add(entry.mountable.name);
-    entries.push(entry);
-  };
-  for (const service of surface.services ?? []) {
-    for (const mountable of collectTools(service, transport, collectConfig)) {
-      append({
-        kind: "contract",
-        service: service.name,
-        action: mountable.method.key,
-        mountable
-      });
-    }
-  }
-  if (transport === "CLI")
-    return entries;
-  for (const definition of surface.runtimeTools ?? []) {
-    if (!runtimeToolSupports(definition, transport))
-      continue;
-    append({
-      kind: "runtime",
-      service: definition.identity.serviceName,
-      action: definition.identity.action,
-      mountable: runtimeToolMountable(definition, collectConfig.assertNames),
-      definition
-    });
-  }
-  return entries;
-}
-
-// src/tools/agent.ts
 function mountAgent(services, config = {}) {
   const serviceList = Array.isArray(services) ? services : [services];
   const tools = {};
@@ -262,6 +128,426 @@ function mountAgent(services, config = {}) {
   }
   return tools;
 }
+// src/tools/download-core.ts
+import { basename, extname, resolve } from "node:path";
+import { z } from "zod";
+var DEFAULT_MAX_BYTES = 100 * 1024 * 1024;
+var MIME_EXT = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+  "image/gif": ".gif",
+  "video/mp4": ".mp4",
+  "video/webm": ".webm",
+  "audio/mpeg": ".mp3",
+  "audio/wav": ".wav",
+  "audio/ogg": ".ogg"
+};
+var DownloadResultSchema = z.object({
+  path: z.string(),
+  size: z.number().int().nonnegative(),
+  mimeType: z.string()
+});
+
+class DownloadOperationError extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "DownloadOperationError";
+  }
+}
+function extensionFor(url, mime) {
+  if (MIME_EXT[mime])
+    return MIME_EXT[mime];
+  try {
+    const ext = extname(new URL(url).pathname).toLowerCase();
+    if (ext)
+      return ext;
+  } catch {}
+  return ".bin";
+}
+function baseNameFor(url) {
+  try {
+    const path = new URL(url).pathname;
+    return (basename(path, extname(path)) || "download").slice(0, 60);
+  } catch {
+    return "download";
+  }
+}
+async function runDownloadOperation(config) {
+  const res = await fetchGuarded(new URL(config.url), config.allowPrivateHosts ?? false, {
+    timeoutMs: config.timeoutMs,
+    signal: config.signal
+  });
+  if (!res.ok) {
+    throw new DownloadOperationError("DOWNLOAD_HTTP_ERROR", `HTTP ${res.status}`, 502);
+  }
+  const mimeType = (res.headers.get("content-type") ?? "").split(";")[0]?.trim() || "application/octet-stream";
+  const max = config.maxBytes ?? DEFAULT_MAX_BYTES;
+  const declared = Number(res.headers.get("content-length") ?? 0);
+  if (declared > max) {
+    await res.body?.cancel();
+    throw new DownloadOperationError("DOWNLOAD_TOO_LARGE", `file exceeds the ${max}-byte cap`, 413);
+  }
+  const buffer = await readCapped(res, max);
+  if (!buffer) {
+    throw new DownloadOperationError("DOWNLOAD_TOO_LARGE", `file exceeds the ${max}-byte cap`, 413);
+  }
+  const dir = resolve(config.dir);
+  const filePath = resolve(dir, `${baseNameFor(config.url)}${extensionFor(config.url, mimeType)}`);
+  await writeDownload(dir, filePath, buffer);
+  return { path: filePath, size: buffer.length, mimeType };
+}
+
+// src/tools/native-definition.ts
+function managedNativeIdentity(identity, method) {
+  return { ...identity, method };
+}
+
+// src/tools/define-download-tool.ts
+function defineDownloadTool(config) {
+  return defineRuntimeTool({
+    name: config.name ?? "download",
+    description: config.description,
+    identity: managedNativeIdentity(config.identity, "POST"),
+    input: config.input,
+    output: DownloadResultSchema,
+    transports: config.transports,
+    annotations: config.annotations,
+    present: config.present,
+    handler: async (context) => {
+      const url = await config.resolveUrl(context.input, context);
+      if (!url) {
+        throw new AppError("DOWNLOAD_NOT_FOUND", "Nothing to download", 404);
+      }
+      try {
+        return await runDownloadOperation({
+          url,
+          dir: config.dirFromInput?.(context.input) ?? config.defaultDir,
+          allowPrivateHosts: config.allowPrivateHosts,
+          maxBytes: config.maxBytes,
+          timeoutMs: config.timeoutMs,
+          signal: context.signal
+        });
+      } catch (error) {
+        if (error instanceof DownloadOperationError) {
+          throw new AppError(error.code, `Download failed: ${error.message}`, error.status);
+        }
+        throw error;
+      }
+    }
+  });
+}
+// src/tools/define-upload-tool.ts
+import { z as z2 } from "zod";
+
+// src/tools/upload-core.ts
+function runUploadOperation(path, upload, signal) {
+  signal?.throwIfAborted();
+  return upload(path, signal);
+}
+
+// src/tools/define-upload-tool.ts
+var UploadToolInputSchema = z2.object({
+  path: z2.string().min(1).describe("Path to a local file on this machine")
+});
+function defineUploadTool(config) {
+  return defineRuntimeTool({
+    name: config.name ?? "upload",
+    description: config.description,
+    identity: managedNativeIdentity(config.identity, "POST"),
+    input: UploadToolInputSchema,
+    output: config.output,
+    transports: config.transports,
+    annotations: config.annotations,
+    present: config.present,
+    handler: async (context) => runUploadOperation(context.input.path, (path) => config.upload(path, context), context.signal)
+  });
+}
+// src/tools/view-file.ts
+import { readFile, stat } from "node:fs/promises";
+import { extname as extname2, resolve as resolve2 } from "node:path";
+import { z as z3 } from "zod";
+var MAX_INLINE_BYTES = 20 * 1024 * 1024;
+var MAX_VIEW_FILES = 20;
+var EXT_MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg",
+  ".m4a": "audio/mp4",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".mov": "video/quicktime"
+};
+var McpAnnotationsSchema = z3.object({
+  audience: z3.array(z3.enum(["user", "assistant"])).optional(),
+  priority: z3.number().optional()
+});
+var McpMediaContentSchema = z3.discriminatedUnion("type", [
+  z3.object({ type: z3.literal("text"), text: z3.string() }),
+  z3.object({
+    type: z3.literal("image"),
+    data: z3.string(),
+    mimeType: z3.string(),
+    annotations: McpAnnotationsSchema.optional()
+  }),
+  z3.object({
+    type: z3.literal("audio"),
+    data: z3.string(),
+    mimeType: z3.string(),
+    annotations: McpAnnotationsSchema.optional()
+  })
+]);
+var ViewFileErrorSchema = z3.object({
+  path: z3.string(),
+  message: z3.string()
+});
+var ViewFileOutputSchema = z3.object({
+  content: z3.array(McpMediaContentSchema),
+  errors: z3.array(ViewFileErrorSchema)
+});
+async function fetchSource(pathOrUrl, options, maxBytes) {
+  const extMime = EXT_MIME[extname2(pathOrUrl).toLowerCase()];
+  if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) {
+    const url = new URL(pathOrUrl);
+    const res = await fetchGuarded(url, options.allowPrivateHosts ?? false, {
+      timeoutMs: options.timeoutMs,
+      signal: options.signal
+    });
+    if (!res.ok)
+      throw new Error(`HTTP ${res.status}`);
+    const headerMime = (res.headers.get("content-type") ?? "").split(";")[0]?.trim() ?? "";
+    const mimeType = headerMime || extMime || "application/octet-stream";
+    if (mimeType.startsWith("video/")) {
+      await res.body?.cancel();
+      return { video: true, mimeType, bytesRead: 0 };
+    }
+    const declared = Number(res.headers.get("content-length") ?? 0);
+    if (declared > maxBytes) {
+      await res.body?.cancel();
+      return { tooLarge: true, mimeType, bytesRead: 0 };
+    }
+    const buffer2 = await readCapped(res, maxBytes);
+    return buffer2 ? { buffer: buffer2, mimeType, bytesRead: buffer2.length } : { tooLarge: true, mimeType, bytesRead: maxBytes };
+  }
+  if (!options.baseDir) {
+    throw new Error("local file paths are disabled — set baseDir to allow them");
+  }
+  options.signal?.throwIfAborted();
+  if (!extMime) {
+    throw new Error("refusing to read a non-media file");
+  }
+  const root = resolve2(options.baseDir);
+  const target = resolve2(root, pathOrUrl);
+  if (!isWithinDir(root, target)) {
+    throw new Error("path escapes the allowed directory");
+  }
+  const realTarget = await realPathWithinDir(root, target);
+  if (realTarget === null) {
+    throw new Error("path escapes the allowed directory");
+  }
+  const info = await stat(realTarget).catch(() => null);
+  if (!info?.isFile())
+    throw new Error("file not found");
+  if (info.size > maxBytes)
+    return { tooLarge: true, mimeType: extMime, bytesRead: 0 };
+  const buffer = await readFile(realTarget, { signal: options.signal });
+  return { buffer, mimeType: extMime, bytesRead: buffer.length };
+}
+async function resolveMediaWithinBudget(pathOrUrl, options, maxBytes) {
+  if (maxBytes <= 0) {
+    return {
+      content: [
+        { type: "text", text: `[media] total inline budget exhausted — ${pathOrUrl}` }
+      ],
+      bytes: 0
+    };
+  }
+  const extMime = EXT_MIME[extname2(pathOrUrl).toLowerCase()];
+  if (extMime?.startsWith("video/")) {
+    return {
+      content: [{ type: "text", text: `[video] ${extMime} — ${pathOrUrl}` }],
+      bytes: 0
+    };
+  }
+  const result = await fetchSource(pathOrUrl, options, maxBytes);
+  if ("video" in result) {
+    return {
+      content: [{ type: "text", text: `[video] ${result.mimeType} — ${pathOrUrl}` }],
+      bytes: result.bytesRead
+    };
+  }
+  if ("tooLarge" in result) {
+    return {
+      content: [
+        { type: "text", text: `[${result.mimeType}] too large to inline — ${pathOrUrl}` }
+      ],
+      bytes: result.bytesRead
+    };
+  }
+  const { buffer, mimeType } = result;
+  const sizeKb = (buffer.length / 1024).toFixed(0);
+  if (mimeType.startsWith("image/")) {
+    return {
+      content: [
+        {
+          type: "image",
+          data: buffer.toString("base64"),
+          mimeType,
+          annotations: { audience: ["user", "assistant"], priority: 0.9 }
+        },
+        { type: "text", text: `[image] ${mimeType}, ${sizeKb}KB` }
+      ],
+      bytes: buffer.length
+    };
+  }
+  if (mimeType.startsWith("audio/")) {
+    return {
+      content: [
+        {
+          type: "audio",
+          data: buffer.toString("base64"),
+          mimeType,
+          annotations: { audience: ["user", "assistant"], priority: 0.9 }
+        },
+        { type: "text", text: `[audio] ${mimeType}, ${sizeKb}KB` }
+      ],
+      bytes: buffer.length
+    };
+  }
+  return {
+    content: [{ type: "text", text: `[${mimeType}] ${sizeKb}KB — ${pathOrUrl}` }],
+    bytes: buffer.length
+  };
+}
+async function resolveMedia(pathOrUrl, options = {}) {
+  return (await resolveMediaWithinBudget(pathOrUrl, options, MAX_INLINE_BYTES)).content;
+}
+var ViewFileInputSchema = z3.object({
+  paths: z3.union([z3.string(), z3.array(z3.string()).max(MAX_VIEW_FILES)]).describe("Media URL(s) or file path(s) to view")
+});
+async function runViewFileOperation(paths, options = {}, signal) {
+  const list = Array.isArray(paths) ? paths : [paths];
+  const content = [];
+  const errors = [];
+  let remainingBytes = MAX_INLINE_BYTES;
+  for (const pathOrUrl of list) {
+    signal?.throwIfAborted();
+    try {
+      const resolved = await resolveMediaWithinBudget(pathOrUrl, { ...options, signal }, remainingBytes);
+      remainingBytes -= resolved.bytes;
+      content.push(...resolved.content);
+    } catch (error) {
+      if (signal?.aborted)
+        throw signal.reason ?? error;
+      const message = error instanceof Error ? error.message : String(error);
+      errors.push({ path: pathOrUrl, message });
+      content.push({ type: "text", text: `[${pathOrUrl}] Error: ${message}` });
+    }
+  }
+  return ViewFileOutputSchema.parse({ content, errors });
+}
+function mountViewFile(server, options = {}) {
+  server.registerTool("view_file", {
+    description: "View media (image, audio, video) by URL or local path — returns it as content you can SEE / HEAR. Pass several paths to view multiple files at once. Use it on a generation `output` url to inspect the result.",
+    inputSchema: ViewFileInputSchema.shape,
+    annotations: { title: "View Media", readOnlyHint: true, idempotentHint: true }
+  }, async (args) => {
+    const result = await runViewFileOperation(args.paths, options);
+    return { content: result.content };
+  });
+}
+
+// src/tools/define-view-file-tool.ts
+function defineViewFileTool(config) {
+  const defaults = {
+    mcp: (output) => ({ content: output.content }),
+    agent: (output) => ({
+      type: "content",
+      value: output.content.map((part) => {
+        if (part.type === "text")
+          return part;
+        return {
+          type: "file",
+          data: { type: "data", data: part.data },
+          mediaType: part.mimeType
+        };
+      })
+    })
+  };
+  return defineRuntimeTool({
+    name: config.name ?? "view_file",
+    description: config.description,
+    identity: managedNativeIdentity(config.identity, "GET"),
+    input: ViewFileInputSchema,
+    output: ViewFileOutputSchema,
+    transports: config.transports,
+    annotations: config.annotations ?? {
+      title: "View Media",
+      readOnlyHint: true,
+      idempotentHint: true
+    },
+    present: { ...defaults, ...config.present },
+    handler: (context) => runViewFileOperation(context.input.paths, {
+      baseDir: config.baseDir,
+      allowPrivateHosts: config.allowPrivateHosts,
+      timeoutMs: config.timeoutMs
+    }, context.signal)
+  });
+}
+// src/tools/define-wait-tool.ts
+function defineWaitTool(config) {
+  const renderedMcp = config.render ? {
+    mcp: (state) => {
+      const rendered = config.render?.(state, false);
+      return {
+        content: [
+          {
+            type: "text",
+            text: rendered?.text ?? JSON.stringify(state, null, 2)
+          }
+        ]
+      };
+    }
+  } : undefined;
+  const present = renderedMcp || config.present ? { ...renderedMcp, ...config.present } : undefined;
+  return defineRuntimeTool({
+    name: config.name ?? "wait",
+    description: config.description,
+    identity: managedNativeIdentity(config.identity, "GET"),
+    input: config.input,
+    output: config.state,
+    transports: config.transports,
+    annotations: config.annotations,
+    present,
+    handler: async (context) => {
+      const result = await runWaitOperation({
+        input: context.input,
+        poll: async (input) => config.state.parse(await config.poll(input, context)),
+        done: config.done,
+        backoff: config.backoff,
+        timeoutSec: config.timeoutFromInput?.(context.input) ?? config.defaultTimeout,
+        signal: context.signal
+      });
+      const rendered = config.render?.(result.state, result.timedOut);
+      if (result.timedOut) {
+        throw new AppError("WAIT_TIMEOUT", rendered?.text ?? "Wait timed out before the operation completed", 408);
+      }
+      if (rendered?.isError) {
+        throw new AppError("WAIT_FAILED", rendered.text, 409);
+      }
+      return result.state;
+    }
+  });
+}
 // src/tools/invoker.ts
 function createToolInvoker(services, config) {
   const serviceList = Array.isArray(services) ? services : [services];
@@ -358,7 +644,7 @@ import {
   createRequestStateCodec,
   McpServer
 } from "@modelcontextprotocol/server";
-import { z as z2 } from "zod";
+import { z as z5 } from "zod";
 
 // src/tools/mcp-app.ts
 import { readFileSync } from "node:fs";
@@ -975,13 +1261,13 @@ function runInMcpRequestContext(context, toolName, body) {
 import {
   isCallToolResult
 } from "@modelcontextprotocol/server";
-import { z } from "zod";
+import { z as z4 } from "zod";
 function mountPreparedRuntimeMcp(server, tools, config) {
   for (const { definition, descriptor } of tools) {
     const { mountable } = descriptor;
     const toolConfig = {
       description: definition.description,
-      inputSchema: z.looseObject({}).meta(presentationMetadata(descriptor.inputSchema))
+      inputSchema: z4.looseObject({}).meta(presentationMetadata(descriptor.inputSchema))
     };
     if (descriptor.outputSchema)
       toolConfig.outputSchema = descriptor.outputSchema;
@@ -1070,7 +1356,7 @@ function mountPreparedMcp(mcpServer, prepared, config = {}) {
     const { mountable } = descriptor;
     const toolConfig = {
       description: mountable.method.desc,
-      inputSchema: z2.looseObject({}).meta(presentationMetadata(descriptor.inputSchema))
+      inputSchema: z5.looseObject({}).meta(presentationMetadata(descriptor.inputSchema))
     };
     if (descriptor.outputSchema)
       toolConfig.outputSchema = descriptor.outputSchema;
@@ -1324,8 +1610,8 @@ function createMcpHandler(config) {
   const authByCarrier = new WeakMap;
   let closed = false;
   let resolveClosed;
-  const closedSignal = new Promise((resolve) => {
-    resolveClosed = resolve;
+  const closedSignal = new Promise((resolve3) => {
+    resolveClosed = resolve3;
   });
   const sdkHandler = createSdkMcpHandler(({ authInfo }) => {
     const resolved = authInfo ? authByCarrier.get(authInfo) : undefined;
@@ -1409,9 +1695,103 @@ async function createStdioMcpServer(config) {
     maxSubscriptions: 0
   });
 }
+// src/tools/mcp-stdio-signals.ts
+var bound = new WeakSet;
+function bindStdioProcessSignals(handle, options = {}) {
+  if (bound.has(handle)) {
+    throw new Error("[stitchkit] bindStdioProcessSignals: this stdio handle is already bound; close the first binding before creating another");
+  }
+  bound.add(handle);
+  const signals = [...new Set(options.signals ?? DEFAULT_PROCESS_SIGNALS)];
+  const source = options.signalSource ?? defaultSignalSource;
+  const handlers = [];
+  let started = false;
+  let sameTurnAsStart = false;
+  let closed = false;
+  let resolveChain = () => {
+    return;
+  };
+  let rejectChain = () => {
+    return;
+  };
+  const promise = new Promise((resolve3, reject) => {
+    resolveChain = resolve3;
+    rejectChain = reject;
+  });
+  promise.catch(() => {
+    return;
+  });
+  const removeListeners = () => {
+    if (closed)
+      return;
+    closed = true;
+    for (const [signal, handler] of handlers)
+      source.off(signal, handler);
+    if (!started)
+      bound.delete(handle);
+  };
+  const close = () => {
+    const hadStarted = started;
+    removeListeners();
+    if (!hadStarted)
+      resolveChain();
+  };
+  const run = async (signal) => {
+    try {
+      await options.onClose?.(signal);
+    } catch (error) {
+      reportSignalError("prepare", error, options.onError);
+    }
+    try {
+      await handle.close();
+    } catch (error) {
+      rejectChain(error);
+      reportSignalError("close", error, options.onError);
+      removeListeners();
+      return;
+    }
+    resolveChain();
+    try {
+      await options.onComplete?.();
+    } catch (error) {
+      reportSignalError("complete", error, options.onError);
+    } finally {
+      removeListeners();
+    }
+  };
+  const onSignal = (signal) => {
+    if (!started) {
+      started = true;
+      sameTurnAsStart = true;
+      queueMicrotask(() => {
+        sameTurnAsStart = false;
+      });
+      run(signal).catch((error) => reportSignalError("close", error, options.onError));
+      return;
+    }
+    if (sameTurnAsStart)
+      return;
+    removeListeners();
+    guardSignalCallback(() => options.onRepeatedSignal?.(signal), "close", options.onError);
+    let restored = false;
+    try {
+      restored = source.raiseDefault(signal);
+    } catch (error) {
+      reportSignalError("close", error, options.onError);
+    }
+    if (!restored) {
+      guardSignalCallback(() => options.onEscalationBlocked?.(signal), "close", options.onError);
+    }
+  };
+  for (const signal of signals) {
+    const handler = () => onSignal(signal);
+    handlers.push([signal, handler]);
+    source.on(signal, handler);
+  }
+  return { promise, close };
+}
 // src/tools/mount-download.ts
-import { basename, extname, resolve } from "node:path";
-import { z as z3 } from "zod";
+import { z as z6 } from "zod";
 
 // src/tools/native-result.ts
 function textResult(text, isError = false) {
@@ -1420,84 +1800,43 @@ function textResult(text, isError = false) {
 }
 
 // src/tools/mount-download.ts
-var DEFAULT_MAX_BYTES = 100 * 1024 * 1024;
-var MIME_EXT = {
-  "image/png": ".png",
-  "image/jpeg": ".jpg",
-  "image/webp": ".webp",
-  "image/gif": ".gif",
-  "video/mp4": ".mp4",
-  "video/webm": ".webm",
-  "audio/mpeg": ".mp3",
-  "audio/wav": ".wav",
-  "audio/ogg": ".ogg"
-};
-function extensionFor(url, mime) {
-  if (MIME_EXT[mime])
-    return MIME_EXT[mime];
-  try {
-    const ext = extname(new URL(url).pathname).toLowerCase();
-    if (ext)
-      return ext;
-  } catch {}
-  return ".bin";
-}
-function baseNameFor(url) {
-  try {
-    const path = new URL(url).pathname;
-    return (basename(path, extname(path)) || "download").slice(0, 60);
-  } catch {
-    return "download";
-  }
-}
 function mountDownload(server, config) {
   const name = config.name ?? "download";
   assertToolName(name, "<native>", "download");
-  server.registerTool(name, { description: config.description, inputSchema: z3.object(config.inputSchema) }, async (rawArgs) => {
+  server.registerTool(name, { description: config.description, inputSchema: z6.object(config.inputSchema) }, async (rawArgs) => {
     const args = isRecord(rawArgs) ? rawArgs : {};
     try {
       const url = await config.resolveUrl(args);
       if (!url)
         return textResult("Nothing to download.", true);
-      const res = await fetchGuarded(new URL(url), config.allowPrivateHosts ?? false, {
+      const result = await runDownloadOperation({
+        url,
+        dir: config.dirFromArgs?.(args) ?? config.defaultDir,
+        allowPrivateHosts: config.allowPrivateHosts,
+        maxBytes: config.maxBytes,
         timeoutMs: config.timeoutMs
       });
-      if (!res.ok)
-        return textResult(`Download failed: HTTP ${res.status}`, true);
-      const mimeType = (res.headers.get("content-type") ?? "").split(";")[0]?.trim() || "application/octet-stream";
-      const max = config.maxBytes ?? DEFAULT_MAX_BYTES;
-      const declared = Number(res.headers.get("content-length") ?? 0);
-      if (declared > max) {
-        await res.body?.cancel();
-        return textResult(`Download failed: file exceeds the ${max}-byte cap`, true);
-      }
-      const buffer = await readCapped(res, max);
-      if (!buffer)
-        return textResult(`Download failed: file exceeds the ${max}-byte cap`, true);
-      const dir = resolve(config.dirFromArgs?.(args) ?? config.defaultDir);
-      const filePath = resolve(dir, `${baseNameFor(url)}${extensionFor(url, mimeType)}`);
-      await writeDownload(dir, filePath, buffer);
-      return textResult(JSON.stringify({ path: filePath, size: buffer.length, mimeType }, null, 2));
+      return textResult(JSON.stringify(result, null, 2));
     } catch (err) {
       return textResult(`Download failed: ${err instanceof Error ? err.message : String(err)}`, true);
     }
   });
 }
 // src/tools/mount-upload.ts
-import { z as z4 } from "zod";
+import { z as z7 } from "zod";
 function mountUpload(server, config) {
   const name = config.name ?? "upload";
   assertToolName(name, "<native>", "upload");
   server.registerTool(name, {
     description: config.description,
-    inputSchema: { path: z4.string().describe("Path to a local file on this machine") }
+    inputSchema: { path: z7.string().describe("Path to a local file on this machine") }
   }, async (rawArgs) => {
     const args = isRecord(rawArgs) ? rawArgs : {};
     const path = typeof args.path === "string" ? args.path : "";
     if (!path)
       return textResult("Provide `path`.", true);
     try {
-      const uploaded = await config.upload(path);
+      const uploaded = await runUploadOperation(path, config.upload);
       return textResult(JSON.stringify(uploaded ?? null, null, 2));
     } catch (err) {
       return textResult(`Upload failed: ${err instanceof Error ? err.message : String(err)}`, true);
@@ -1505,15 +1844,16 @@ function mountUpload(server, config) {
   });
 }
 // src/tools/mount-wait.ts
-import { z as z5 } from "zod";
+import { z as z8 } from "zod";
 function mountWait(server, config) {
   const name = config.name ?? "wait";
   assertToolName(name, "<native>", "wait");
-  server.registerTool(name, { description: config.description, inputSchema: z5.object(config.inputSchema) }, async (rawArgs) => {
+  server.registerTool(name, { description: config.description, inputSchema: z8.object(config.inputSchema) }, async (rawArgs) => {
     const args = isRecord(rawArgs) ? rawArgs : {};
     try {
-      const { state, timedOut } = await pollUntil({
-        poll: () => config.poll(args),
+      const { state, timedOut } = await runWaitOperation({
+        input: args,
+        poll: (input) => config.poll(input),
         done: config.done,
         backoff: config.backoff,
         timeoutSec: config.timeoutFromArgs?.(args) ?? config.defaultTimeout
@@ -1527,19 +1867,19 @@ function mountWait(server, config) {
 }
 // src/tools/oauth-provider.ts
 import { randomUUID } from "node:crypto";
-import { z as z6 } from "zod";
+import { z as z9 } from "zod";
 function isPlainDisplayCharacter(character) {
   const codePoint = character.codePointAt(0);
   return codePoint !== undefined && codePoint >= 32 && codePoint !== 127 && character !== "<" && character !== ">";
 }
-var CimdClientMetadataSchema = z6.object({
-  client_id: z6.url(),
-  redirect_uris: z6.array(z6.url()).min(1),
-  client_name: z6.string().trim().min(1).max(200).refine((value) => Array.from(value).every(isPlainDisplayCharacter), {
+var CimdClientMetadataSchema = z9.object({
+  client_id: z9.url(),
+  redirect_uris: z9.array(z9.url()).min(1),
+  client_name: z9.string().trim().min(1).max(200).refine((value) => Array.from(value).every(isPlainDisplayCharacter), {
     message: "client_name must be plain display text"
   }),
-  token_endpoint_auth_method: z6.literal("none"),
-  application_type: z6.enum(["native", "web"]).optional()
+  token_endpoint_auth_method: z9.literal("none"),
+  application_type: z9.enum(["native", "web"]).optional()
 });
 function createSecureClientMetadataFetcher(policy = {}) {
   assertPositiveInteger("cimd.maxBytes", policy.maxBytes ?? DEFAULT_CIMD_MAX_BYTES);
@@ -2332,168 +2672,6 @@ function summarizeTransports(surface) {
     sources
   };
 }
-// src/tools/view-file.ts
-import { readFile, stat } from "node:fs/promises";
-import { extname as extname2, resolve as resolve2 } from "node:path";
-import { z as z7 } from "zod";
-var MAX_INLINE_BYTES = 20 * 1024 * 1024;
-var MAX_VIEW_FILES = 20;
-var EXT_MIME = {
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".mp3": "audio/mpeg",
-  ".wav": "audio/wav",
-  ".ogg": "audio/ogg",
-  ".m4a": "audio/mp4",
-  ".mp4": "video/mp4",
-  ".webm": "video/webm",
-  ".mov": "video/quicktime"
-};
-async function fetchSource(pathOrUrl, options, maxBytes) {
-  const extMime = EXT_MIME[extname2(pathOrUrl).toLowerCase()];
-  if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) {
-    const url = new URL(pathOrUrl);
-    const res = await fetchGuarded(url, options.allowPrivateHosts ?? false, {
-      timeoutMs: options.timeoutMs
-    });
-    if (!res.ok)
-      throw new Error(`HTTP ${res.status}`);
-    const headerMime = (res.headers.get("content-type") ?? "").split(";")[0]?.trim() ?? "";
-    const mimeType = headerMime || extMime || "application/octet-stream";
-    if (mimeType.startsWith("video/")) {
-      await res.body?.cancel();
-      return { video: true, mimeType, bytesRead: 0 };
-    }
-    const declared = Number(res.headers.get("content-length") ?? 0);
-    if (declared > maxBytes) {
-      await res.body?.cancel();
-      return { tooLarge: true, mimeType, bytesRead: 0 };
-    }
-    const buffer2 = await readCapped(res, maxBytes);
-    return buffer2 ? { buffer: buffer2, mimeType, bytesRead: buffer2.length } : { tooLarge: true, mimeType, bytesRead: maxBytes };
-  }
-  if (!options.baseDir) {
-    throw new Error("local file paths are disabled — set baseDir to allow them");
-  }
-  if (!extMime) {
-    throw new Error("refusing to read a non-media file");
-  }
-  const root = resolve2(options.baseDir);
-  const target = resolve2(root, pathOrUrl);
-  if (!isWithinDir(root, target)) {
-    throw new Error("path escapes the allowed directory");
-  }
-  const realTarget = await realPathWithinDir(root, target);
-  if (realTarget === null) {
-    throw new Error("path escapes the allowed directory");
-  }
-  const info = await stat(realTarget).catch(() => null);
-  if (!info?.isFile())
-    throw new Error("file not found");
-  if (info.size > maxBytes)
-    return { tooLarge: true, mimeType: extMime, bytesRead: 0 };
-  const buffer = await readFile(realTarget);
-  return { buffer, mimeType: extMime, bytesRead: buffer.length };
-}
-async function resolveMediaWithinBudget(pathOrUrl, options, maxBytes) {
-  if (maxBytes <= 0) {
-    return {
-      content: [
-        { type: "text", text: `[media] total inline budget exhausted — ${pathOrUrl}` }
-      ],
-      bytes: 0
-    };
-  }
-  const extMime = EXT_MIME[extname2(pathOrUrl).toLowerCase()];
-  if (extMime?.startsWith("video/")) {
-    return {
-      content: [{ type: "text", text: `[video] ${extMime} — ${pathOrUrl}` }],
-      bytes: 0
-    };
-  }
-  const result = await fetchSource(pathOrUrl, options, maxBytes);
-  if ("video" in result) {
-    return {
-      content: [{ type: "text", text: `[video] ${result.mimeType} — ${pathOrUrl}` }],
-      bytes: result.bytesRead
-    };
-  }
-  if ("tooLarge" in result) {
-    return {
-      content: [
-        { type: "text", text: `[${result.mimeType}] too large to inline — ${pathOrUrl}` }
-      ],
-      bytes: result.bytesRead
-    };
-  }
-  const { buffer, mimeType } = result;
-  const sizeKb = (buffer.length / 1024).toFixed(0);
-  if (mimeType.startsWith("image/")) {
-    return {
-      content: [
-        {
-          type: "image",
-          data: buffer.toString("base64"),
-          mimeType,
-          annotations: { audience: ["user", "assistant"], priority: 0.9 }
-        },
-        { type: "text", text: `[image] ${mimeType}, ${sizeKb}KB` }
-      ],
-      bytes: buffer.length
-    };
-  }
-  if (mimeType.startsWith("audio/")) {
-    return {
-      content: [
-        {
-          type: "audio",
-          data: buffer.toString("base64"),
-          mimeType,
-          annotations: { audience: ["user", "assistant"], priority: 0.9 }
-        },
-        { type: "text", text: `[audio] ${mimeType}, ${sizeKb}KB` }
-      ],
-      bytes: buffer.length
-    };
-  }
-  return {
-    content: [{ type: "text", text: `[${mimeType}] ${sizeKb}KB — ${pathOrUrl}` }],
-    bytes: buffer.length
-  };
-}
-async function resolveMedia(pathOrUrl, options = {}) {
-  return (await resolveMediaWithinBudget(pathOrUrl, options, MAX_INLINE_BYTES)).content;
-}
-var ViewFileInputSchema = z7.object({
-  paths: z7.union([z7.string(), z7.array(z7.string()).max(MAX_VIEW_FILES)]).describe("Media URL(s) or file path(s) to view")
-});
-function mountViewFile(server, options = {}) {
-  server.registerTool("view_file", {
-    description: "View media (image, audio, video) by URL or local path — returns it as content you can SEE / HEAR. Pass several paths to view multiple files at once. Use it on a generation `output` url to inspect the result.",
-    inputSchema: ViewFileInputSchema.shape,
-    annotations: { title: "View Media", readOnlyHint: true, idempotentHint: true }
-  }, async (args) => {
-    const list = Array.isArray(args.paths) ? args.paths : [args.paths];
-    const content = [];
-    let remainingBytes = MAX_INLINE_BYTES;
-    for (const pathOrUrl of list) {
-      try {
-        const resolved = await resolveMediaWithinBudget(pathOrUrl, options, remainingBytes);
-        remainingBytes -= resolved.bytes;
-        content.push(...resolved.content);
-      } catch (err) {
-        content.push({
-          type: "text",
-          text: `[${pathOrUrl}] Error: ${err instanceof Error ? err.message : String(err)}`
-        });
-      }
-    }
-    return { content };
-  });
-}
 export {
   wwwAuthenticateHeader,
   validateMcpSchemas,
@@ -2516,7 +2694,12 @@ export {
   flattenToolJsonSchema,
   findUntypedProperties,
   findNonPortableFormats,
+  defineWaitTool,
+  defineViewFileTool,
+  defineUploadTool,
   defineRuntimeTool,
+  defineDownloadTool,
+  defineCliCommand,
   createToolkit,
   createToolLogger,
   createToolInvoker,
@@ -2530,8 +2713,16 @@ export {
   coerceJsonArgs,
   buildToolManifest,
   buildMcpServer,
+  bindStdioProcessSignals,
+  ViewFileOutputSchema,
+  ViewFileInputSchema,
+  ViewFileErrorSchema,
+  UploadToolInputSchema,
   RESOURCE_MIME_TYPE,
   PROTECTED_RESOURCE_PATH,
   PORTABLE_JSON_SCHEMA_FORMATS,
-  EXT_APPS_BUNDLE_PLACEHOLDER
+  McpMediaContentSchema,
+  McpAnnotationsSchema,
+  EXT_APPS_BUNDLE_PLACEHOLDER,
+  DownloadResultSchema
 };