stitchkit 0.54.0 → 0.56.0

package/dist/tools.js

@@ -1,7 +1,7 @@
 import {
   signJwt,
   verifyPkce
-} from "./index-yez419px.js";
+} from "./index-xy8fmh6w.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   DEFAULT_PROCESS_SIGNALS,
@@ -9,11 +9,9 @@ import {
   defaultSignalSource,
   guardSignalCallback,
   reportSignalError
-} from "./index-b15rtha1.js";
+} from "./index-sm2tjx06.js";
 import {
-  assertToolName,
-  assertUniqueToolName,
-  buildToolPresentationSchema,
+  WaitTimeoutError,
   coerceJsonArgs,
   collectToolSurface,
   collectTools,
@@ -25,40 +23,51 @@ import {
   executeToolMethod,
   fetchGuarded,
   fetchPinnedDocument,
-  flattenToolJsonSchema,
   formatToolError,
-  isObjectPresentationSchema,
-  presentationMetadata,
   readCapped,
   runWaitOperation,
   toolErrorFromResult,
-  toolResultFromError,
-  writeDownload
-} from "./index-7vb44hy8.js";
+  toolResultFromError
+} from "./index-escqg10p.js";
 import {
-  isWithinDir,
-  realPathWithinDir,
-  toJsonSchema
-} from "./index-yxpe3phd.js";
+  ManagedFileError
+} from "./index-bfcpjw20.js";
+import"./index-sbdmyz75.js";
 import {
-  ApiError,
-  createClient
-} from "./index-e1es808r.js";
-import"./index-48ffdxgk.js";
+  PORTABLE_JSON_SCHEMA_FORMATS,
+  assertToolName,
+  assertUniqueToolName,
+  findNonPortableFormats,
+  findUntypedProperties,
+  flattenToolJsonSchema,
+  prepareProjectedMcpTools,
+  presentationMetadata,
+  validateMcpRoundPolicy
+} from "./index-6y759j86.js";
+import"./index-cby4ar3v.js";
 import {
   redact
-} from "./index-gvha32jh.js";
+} from "./index-jcc611vh.js";
 import {
-  AppError,
   getRequestContext,
   getTraceId,
-  mergeMeta,
+  normalizeError,
   runWithRequestContext
-} from "./index-173tvqcp.js";
+} from "./index-j3dem06f.js";
+import {
+  AppError,
+  STITCH_ERROR_STATUS,
+  defineContract
+} from "./index-5r13htq1.js";
+import {
+  ManagedFilePathSchema,
+  ManagedFileRefSchema
+} from "./index-6k1937bx.js";
 import {
   isRecord,
   resolvePropagationContext
-} from "./index-bmnhqtya.js";
+} from "./index-7eq9va6e.js";
+import"./index-1bx83sw4.js";
 
 // src/tools/agent.ts
 import { jsonSchema, tool } from "ai";
@@ -85,10 +94,10 @@ function mountAgent(services, config = {}) {
     const inputSchema = jsonSchema(mountable.presentationSchema, {
       validate: async (value) => isRecord(value) ? { success: true, value } : { success: false, error: new Error("Tool arguments must be an object") }
     });
-    const execute = async (rawArgs) => {
+    const execute = async (rawArgs, options) => {
       const args = isRecord(rawArgs) ? rawArgs : {};
       try {
-        const result = await runTool(mountable, args);
+        const result = await runTool(mountable, args, { signal: options.abortSignal });
         if (result.ok)
           return result.data;
         return formatToolError(result, mountable.name, config.errorHint);
@@ -128,9 +137,408 @@ function mountAgent(services, config = {}) {
   }
   return tools;
 }
-// src/tools/download-core.ts
-import { basename, extname, resolve } from "node:path";
+// src/tools/async-operation.ts
 import { z } from "zod";
+
+// src/tools/native-definition.ts
+function managedNativeIdentity(identity, method) {
+  return { ...identity, method };
+}
+
+// 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) => {
+      let result;
+      try {
+        result = await runWaitOperation({
+          input: context.input,
+          poll: async (input, signal) => config.state.parse(await config.poll(input, { ...context, signal })),
+          done: config.done,
+          backoff: config.backoff,
+          timeoutSec: config.timeoutFromInput?.(context.input) ?? config.defaultTimeout,
+          signal: context.signal
+        });
+      } catch (error) {
+        if (error instanceof WaitTimeoutError) {
+          throw new AppError("WAIT_TIMEOUT", "Wait timed out before the first snapshot", 408);
+        }
+        throw error;
+      }
+      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/async-operation.ts
+var AsyncOperationCancelResultSchema = z.discriminatedUnion("outcome", [
+  z.object({ outcome: z.literal("accepted") }),
+  z.object({ outcome: z.literal("already_terminal") }),
+  z.object({ outcome: z.literal("rejected"), reason: z.string().min(1) })
+]);
+function createAsyncOperationSnapshotSchema(config) {
+  const progress = config.progress ? { progress: config.progress.optional() } : {};
+  return z.discriminatedUnion("phase", [
+    z.object({ phase: z.literal("pending"), ...progress }),
+    z.object({ phase: z.literal("running"), ...progress }),
+    z.object({ phase: z.literal("succeeded"), ...progress }),
+    z.object({ phase: z.literal("failed"), failure: config.failure, ...progress }),
+    z.object({ phase: z.literal("cancelled"), ...progress })
+  ]);
+}
+function terminal(snapshot) {
+  if (typeof snapshot !== "object" || snapshot === null || !("phase" in snapshot)) {
+    return false;
+  }
+  return snapshot.phase === "succeeded" || snapshot.phase === "failed" || snapshot.phase === "cancelled";
+}
+function succeeded(snapshot) {
+  return typeof snapshot === "object" && snapshot !== null && "phase" in snapshot && snapshot.phase === "succeeded";
+}
+function defineAsyncOperation(config) {
+  const capabilityName = (capability) => config.names?.[capability] ?? `${config.name}_${capability}`;
+  const description = (capability) => config.descriptions?.[capability] ?? `${config.description}: ${capability}`;
+  const identity = (capability, method) => ({
+    serviceName: config.identity.serviceName,
+    action: `${config.identity.action}.${capability}`,
+    scope: config.scopes?.[capability] ?? config.identity.scope,
+    meta: config.identity.meta,
+    method
+  });
+  const common = (capability) => ({
+    name: capabilityName(capability),
+    description: description(capability),
+    transports: config.transports?.[capability],
+    annotations: config.annotations?.[capability] ?? (capability === "start" || capability === "cancel" ? { destructiveHint: true } : undefined)
+  });
+  const inspect = async (capability, context) => {
+    await config.authorize(context.input, capability, context);
+    const state = config.state.parse(await config.inspect(context.input, context));
+    const snapshot = config.snapshot.parse(await config.classify(state, context));
+    return { state, snapshot };
+  };
+  const start = defineRuntimeTool({
+    ...common("start"),
+    identity: identity("start", "POST"),
+    input: config.startInput,
+    output: config.id,
+    handler: (context) => config.start(context.input, context)
+  });
+  const status = defineRuntimeTool({
+    ...common("status"),
+    identity: identity("status", "GET"),
+    input: config.id,
+    output: config.snapshot,
+    handler: async (context) => (await inspect("status", context)).snapshot
+  });
+  const wait = defineWaitTool({
+    ...common("wait"),
+    identity: identity("wait", "GET"),
+    input: config.id,
+    state: config.snapshot,
+    poll: async (_id, context) => (await inspect("wait", context)).snapshot,
+    done: terminal,
+    backoff: config.backoff,
+    defaultTimeout: config.defaultTimeout,
+    timeoutFromInput: config.timeoutFromId
+  });
+  const definitions = { start, status, wait };
+  const names = new Set;
+  if (config.cancel) {
+    const capability = config.cancel;
+    definitions.cancel = defineRuntimeTool({
+      ...common("cancel"),
+      identity: identity("cancel", "DELETE"),
+      input: config.id,
+      output: AsyncOperationCancelResultSchema,
+      handler: async (context) => {
+        const inspected = await inspect("cancel", context);
+        return capability.handler(inspected.state, context);
+      }
+    });
+  }
+  if (config.result) {
+    const capability = config.result;
+    definitions.result = defineRuntimeTool({
+      ...common("result"),
+      identity: identity("result", "GET"),
+      input: config.id,
+      output: capability.output,
+      handler: async (context) => {
+        const inspected = await inspect("result", context);
+        if (!succeeded(inspected.snapshot)) {
+          throw new AppError("OPERATION_NOT_SUCCEEDED", "Operation result is not available", 409);
+        }
+        return capability.handler(inspected.state, context);
+      }
+    });
+  }
+  if (config.artifacts) {
+    const capability = config.artifacts;
+    definitions.artifacts = defineRuntimeTool({
+      ...common("artifacts"),
+      identity: identity("artifacts", "GET"),
+      input: config.id,
+      output: capability.output,
+      handler: async (context) => {
+        const inspected = await inspect("artifacts", context);
+        if (!succeeded(inspected.snapshot)) {
+          throw new AppError("OPERATION_NOT_SUCCEEDED", "Operation artifacts are not available", 409);
+        }
+        return capability.handler(inspected.state, context);
+      }
+    });
+  }
+  for (const definition of Object.values(definitions)) {
+    assertUniqueToolName(definition.name, names.has(definition.name), "in-process tool name");
+    names.add(definition.name);
+  }
+  return {
+    ...definitions,
+    runtimeTools: Object.values(definitions),
+    schemas: {
+      id: config.id,
+      snapshot: config.snapshot,
+      cancelResult: AsyncOperationCancelResultSchema
+    }
+  };
+}
+function adapterResult(capability, target, schema, value) {
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) {
+    throw new Error(`Async operation adapter for capability "${capability}" returned invalid ${target}`, { cause: parsed.error });
+  }
+  return parsed.data;
+}
+var NON_WIRE_STABLE_ZOD_TYPES = new Set([
+  "catch",
+  "default",
+  "lazy",
+  "pipe",
+  "prefault",
+  "readonly",
+  "success",
+  "transform"
+]);
+function hasOverwriteCheck(value) {
+  return isRecord(value) && isRecord(value._zod) && isRecord(value._zod.def) && value._zod.def.check === "overwrite";
+}
+function assertWireStableIdSchema(schema, boundary) {
+  const visited = new Set;
+  const pending = [schema];
+  while (pending.length > 0) {
+    const value = pending.pop();
+    if (typeof value !== "object" || value === null || visited.has(value))
+      continue;
+    visited.add(value);
+    if (value instanceof z.ZodType) {
+      const definition = value._zod.def;
+      if (NON_WIRE_STABLE_ZOD_TYPES.has(definition.type) || "coerce" in definition && definition.coerce === true || "checks" in definition && Array.isArray(definition.checks) && definition.checks.some(hasOverwriteCheck)) {
+        throw new Error(`${boundary} must use a wire-stable ID schema without transforms, coercion, defaults or overwrites; use binding: "adapted" with explicit ID adapters`);
+      }
+      pending.push(...Object.values(definition));
+      continue;
+    }
+    if (Array.isArray(value)) {
+      pending.push(...value);
+      continue;
+    }
+    if (isRecord(value))
+      pending.push(...Object.values(value));
+  }
+}
+function defineAsyncOperationContract(config) {
+  assertWireStableIdSchema(config.id, "Async operation contract");
+  const hasStartOutput = config.startOutput !== undefined;
+  const hasIdFromStart = config.idFromStart !== undefined;
+  if (hasStartOutput !== hasIdFromStart) {
+    throw new Error("Async operation contract startOutput and idFromStart must be configured together");
+  }
+  const description = (capability) => config.descriptions?.[capability] ?? `${config.description}: ${capability}`;
+  const endpoint = (capability, method, path, input, output) => {
+    const scope = config.scopes?.[capability];
+    return {
+      method,
+      path,
+      desc: description(capability),
+      input,
+      output,
+      ...scope !== undefined && { scope }
+    };
+  };
+  const startOutput = config.startOutput ?? config.id;
+  const endpoints = {
+    start: endpoint("start", "POST", "/", config.startInput, startOutput),
+    status: endpoint("status", "POST", "/status", config.id, config.snapshot),
+    wait: endpoint("wait", "POST", "/wait", config.id, config.snapshot)
+  };
+  const capabilities = {
+    start: "start",
+    status: "status",
+    wait: "wait"
+  };
+  const schemas = {
+    startInput: config.startInput,
+    startOutput,
+    id: config.id,
+    snapshot: config.snapshot,
+    cancelResult: AsyncOperationCancelResultSchema
+  };
+  const inputFor = {
+    status: (id) => adapterResult("status", "input", config.id, id),
+    wait: (id) => adapterResult("wait", "input", config.id, id)
+  };
+  if (config.cancel) {
+    endpoints.cancel = endpoint("cancel", "POST", "/cancel", config.id, AsyncOperationCancelResultSchema);
+    capabilities.cancel = "cancel";
+    schemas.cancel = AsyncOperationCancelResultSchema;
+    inputFor.cancel = (id) => adapterResult("cancel", "input", config.id, id);
+  }
+  if (config.result) {
+    endpoints.result = endpoint("result", "POST", "/result", config.id, config.result);
+    capabilities.result = "result";
+    schemas.result = config.result;
+    inputFor.result = (id) => adapterResult("result", "input", config.id, id);
+  }
+  if (config.artifacts) {
+    endpoints.artifacts = endpoint("artifacts", "POST", "/artifacts", config.id, config.artifacts);
+    capabilities.artifacts = "artifacts";
+    schemas.artifacts = config.artifacts;
+    inputFor.artifacts = (id) => adapterResult("artifacts", "input", config.id, id);
+  }
+  const contract = config.scope ? defineContract({ prefix: config.prefix, scope: config.scope }, endpoints) : defineContract({ prefix: config.prefix }, endpoints);
+  const applicationStartOutput = config.startOutput;
+  const applicationIdFromStart = config.idFromStart;
+  const idFromStart = applicationStartOutput && applicationIdFromStart ? (output) => adapterResult("start", "id", config.id, applicationIdFromStart(output)) : (output) => adapterResult("start", "id", config.id, output);
+  return {
+    contract,
+    capabilities,
+    schemas,
+    adapters: { idFromStart, inputFor }
+  };
+}
+function bindContractAsyncOperation(config) {
+  const endpoint = (key) => {
+    const found = config.contract.endpoints[key];
+    if (!found)
+      throw new Error(`Contract async operation method "${key}" not found`);
+    return found;
+  };
+  const start = endpoint(config.capabilities.start);
+  const status = endpoint(config.capabilities.status);
+  const wait = endpoint(config.capabilities.wait);
+  if (!start.output || !status.output || !wait.output) {
+    throw new Error("Contract async operation requires outputs for start, status and wait");
+  }
+  const startOutput = start.output;
+  const statusOutput = status.output;
+  if (wait.output !== statusOutput) {
+    throw new Error('Contract async operation capability "wait" output must reuse the same schema instance as the status output');
+  }
+  const optionalCapabilities = [
+    "cancel",
+    "result",
+    "artifacts"
+  ];
+  if (config.binding !== "adapted") {
+    assertWireStableIdSchema(startOutput, "Direct contract async operation");
+    if (status.input !== startOutput || wait.input !== startOutput) {
+      const capability = status.input !== startOutput ? "status" : "wait";
+      throw new Error(`Contract async operation capability "${capability}" input must reuse the same schema instance as the start output`);
+    }
+    const inputFor2 = {
+      status: (id) => adapterResult("status", "input", startOutput, id),
+      wait: (id) => adapterResult("wait", "input", startOutput, id)
+    };
+    for (const capability of optionalCapabilities) {
+      const key = config.capabilities[capability];
+      if (!key)
+        continue;
+      if (endpoint(key).input !== startOutput) {
+        throw new Error(`Contract async operation capability "${capability}" input must reuse the same schema instance as the start output`);
+      }
+      inputFor2[capability] = (id) => adapterResult(capability, "input", startOutput, id);
+    }
+    return {
+      contract: config.contract,
+      handlers: config.handlers,
+      capabilities: config.capabilities,
+      schemas: { id: startOutput, snapshot: statusOutput },
+      adapters: {
+        idFromStart: (output) => adapterResult("start", "id", startOutput, output),
+        inputFor: inputFor2
+      }
+    };
+  }
+  const adapters = config.adapters;
+  const idSchema = config.id;
+  const adaptedInput = (capability, key, builder) => {
+    const input = endpoint(key).input;
+    if (!input) {
+      throw new Error(`Contract async operation capability "${capability}" requires an input schema`);
+    }
+    return (id) => adapterResult(capability, "input", input, builder(id));
+  };
+  const inputFor = {
+    status: adaptedInput("status", config.capabilities.status, adapters.inputFor.status),
+    wait: adaptedInput("wait", config.capabilities.wait, adapters.inputFor.wait)
+  };
+  const optionalInput = (capability, key, builder) => {
+    if (!key)
+      return;
+    if (!builder) {
+      throw new Error(`Contract async operation capability "${capability}" requires an input adapter`);
+    }
+    inputFor[capability] = adaptedInput(capability, key, builder);
+  };
+  optionalInput("cancel", config.capabilities.cancel, "cancel" in adapters.inputFor ? adapters.inputFor.cancel : undefined);
+  optionalInput("result", config.capabilities.result, "result" in adapters.inputFor ? adapters.inputFor.result : undefined);
+  optionalInput("artifacts", config.capabilities.artifacts, "artifacts" in adapters.inputFor ? adapters.inputFor.artifacts : undefined);
+  if (!idSchema) {
+    throw new Error("Contract adapted async operation requires an id schema");
+  }
+  return {
+    contract: config.contract,
+    handlers: config.handlers,
+    capabilities: config.capabilities,
+    schemas: { id: idSchema, snapshot: statusOutput },
+    adapters: {
+      idFromStart: (output) => adapterResult("start", "id", idSchema, adapters.idFromStart(output)),
+      inputFor
+    }
+  };
+}
+// src/tools/download-core.ts
+import { basename, extname } from "node:path";
 var DEFAULT_MAX_BYTES = 100 * 1024 * 1024;
 var MIME_EXT = {
   "image/png": ".png",
@@ -143,11 +551,6 @@ var MIME_EXT = {
   "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;
@@ -192,19 +595,42 @@ async function runDownloadOperation(config) {
     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 };
+  const path = config.path ?? `${baseNameFor(config.url)}${extensionFor(config.url, mimeType)}`;
+  return config.files.write(path, res.body ?? new Uint8Array, {
+    maxBytes: max,
+    mediaType: mimeType,
+    signal: config.signal
+  });
 }
 
-// src/tools/native-definition.ts
-function managedNativeIdentity(identity, method) {
-  return { ...identity, method };
+// src/tools/managed-file-error.ts
+var SAFE_MANAGED_FILE_MESSAGES = {
+  FILE_INVALID_PATH: "Invalid managed-file path",
+  FILE_OUTSIDE_ROOT: "Managed-file path escapes its boundary",
+  FILE_NOT_FOUND: "Managed file not found",
+  FILE_NOT_REGULAR: "Managed path is not a regular file",
+  FILE_INSPECTION_REJECTED: "Managed file rejected by inspection",
+  FILE_TOO_LARGE: "Managed file exceeds the configured size limit",
+  FILE_EXISTS: "Managed file already exists"
+};
+function managedFileAppError(error) {
+  if (!(error instanceof ManagedFileError))
+    return null;
+  switch (error.code) {
+    case "FILE_INVALID_PATH":
+    case "FILE_OUTSIDE_ROOT":
+    case "FILE_NOT_FOUND":
+    case "FILE_NOT_REGULAR":
+    case "FILE_INSPECTION_REJECTED":
+    case "FILE_TOO_LARGE":
+    case "FILE_EXISTS":
+      return new AppError(error.code, SAFE_MANAGED_FILE_MESSAGES[error.code], STITCH_ERROR_STATUS[error.code]);
+    case "FILE_IO_ERROR":
+      return null;
+  }
+}
+function normalizeFileToolError(error) {
+  return managedFileAppError(error) ?? normalizeError(error);
 }
 
 // src/tools/define-download-tool.ts
@@ -214,7 +640,7 @@ function defineDownloadTool(config) {
     description: config.description,
     identity: managedNativeIdentity(config.identity, "POST"),
     input: config.input,
-    output: DownloadResultSchema,
+    output: ManagedFileRefSchema,
     transports: config.transports,
     annotations: config.annotations,
     present: config.present,
@@ -226,7 +652,8 @@ function defineDownloadTool(config) {
       try {
         return await runDownloadOperation({
           url,
-          dir: config.dirFromInput?.(context.input) ?? config.defaultDir,
+          files: config.files,
+          path: config.pathFromInput?.(context.input),
           allowPrivateHosts: config.allowPrivateHosts,
           maxBytes: config.maxBytes,
           timeoutMs: config.timeoutMs,
@@ -236,6 +663,9 @@ function defineDownloadTool(config) {
         if (error instanceof DownloadOperationError) {
           throw new AppError(error.code, `Download failed: ${error.message}`, error.status);
         }
+        const managedError = managedFileAppError(error);
+        if (managedError)
+          throw managedError;
         throw error;
       }
     }
@@ -245,14 +675,14 @@ function defineDownloadTool(config) {
 import { z as z2 } from "zod";
 
 // src/tools/upload-core.ts
-function runUploadOperation(path, upload, signal) {
+function runUploadOperation(files, path, upload, signal) {
   signal?.throwIfAborted();
-  return upload(path, signal);
+  return files.read(path, { signal }).then((source) => upload(source, 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")
+  path: ManagedFilePathSchema.describe("Path relative to the configured file boundary")
 });
 function defineUploadTool(config) {
   return defineRuntimeTool({
@@ -264,12 +694,20 @@ function defineUploadTool(config) {
     transports: config.transports,
     annotations: config.annotations,
     present: config.present,
-    handler: async (context) => runUploadOperation(context.input.path, (path) => config.upload(path, context), context.signal)
+    handler: async (context) => {
+      try {
+        return await runUploadOperation(config.files, context.input.path, (source) => config.upload(source, context), context.signal);
+      } catch (error) {
+        const managedError = managedFileAppError(error);
+        if (managedError)
+          throw managedError;
+        throw error;
+      }
+    }
   });
 }
 // src/tools/view-file.ts
-import { readFile, stat } from "node:fs/promises";
-import { extname as extname2, resolve as resolve2 } from "node:path";
+import { extname as extname2 } from "node:path";
 import { z as z3 } from "zod";
 var MAX_INLINE_BYTES = 20 * 1024 * 1024;
 var MAX_VIEW_FILES = 20;
@@ -323,7 +761,7 @@ async function fetchSource(pathOrUrl, options, maxBytes) {
       signal: options.signal
     });
     if (!res.ok)
-      throw new Error(`HTTP ${res.status}`);
+      throw new AppError("VIEW_HTTP_ERROR", `HTTP ${res.status}`, 502);
     const headerMime = (res.headers.get("content-type") ?? "").split(";")[0]?.trim() ?? "";
     const mimeType = headerMime || extMime || "application/octet-stream";
     if (mimeType.startsWith("video/")) {
@@ -335,32 +773,33 @@ async function fetchSource(pathOrUrl, options, 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 };
+    const buffer = await readCapped(res, maxBytes);
+    return buffer ? { buffer, mimeType, bytesRead: buffer.length } : { tooLarge: true, mimeType, bytesRead: maxBytes };
   }
-  if (!options.baseDir) {
-    throw new Error("local file paths are disabled — set baseDir to allow them");
+  if (!options.files) {
+    throw new AppError("FILE_INVALID_PATH", "local file paths are disabled — set files to allow them", 400);
   }
   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");
+    throw new AppError("FILE_INSPECTION_REJECTED", "refusing to read a non-media file", 422);
   }
-  const realTarget = await realPathWithinDir(root, target);
-  if (realTarget === null) {
-    throw new Error("path escapes the allowed directory");
+  try {
+    const source = await options.files.read(pathOrUrl, {
+      maxBytes,
+      signal: options.signal
+    });
+    const buffer = Buffer.from(source.bytes);
+    return {
+      buffer,
+      mimeType: source.ref.mediaType ?? extMime,
+      bytesRead: buffer.length
+    };
+  } catch (error) {
+    if (error instanceof ManagedFileError && error.code === "FILE_TOO_LARGE") {
+      return { tooLarge: true, mimeType: extMime, bytesRead: maxBytes };
+    }
+    throw error;
   }
-  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) {
@@ -448,7 +887,7 @@ async function runViewFileOperation(paths, options = {}, signal) {
     } catch (error) {
       if (signal?.aborted)
         throw signal.reason ?? error;
-      const message = error instanceof Error ? error.message : String(error);
+      const message = normalizeFileToolError(error).message;
       errors.push({ path: pathOrUrl, message });
       content.push({ type: "text", text: `[${pathOrUrl}] Error: ${message}` });
     }
@@ -497,57 +936,12 @@ function defineViewFileTool(config) {
     },
     present: { ...defaults, ...config.present },
     handler: (context) => runViewFileOperation(context.input.paths, {
-      baseDir: config.baseDir,
+      files: config.files,
       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];
@@ -595,6 +989,24 @@ function createToolInvoker(services, config) {
     }
   });
 }
+// src/tools/lifecycle.ts
+function composeToolLifecycle(...hooks) {
+  return {
+    beforeHandle: async (ctx, endpoint) => {
+      for (const hook of hooks)
+        await hook?.beforeHandle?.(ctx, endpoint);
+    },
+    afterHandle: async (ctx, result, endpoint) => {
+      let current = result;
+      for (const hook of hooks) {
+        const transformed = await hook?.afterHandle?.(ctx, current, endpoint);
+        if (transformed !== undefined)
+          current = transformed;
+      }
+      return current;
+    }
+  };
+}
 // src/tools/list-names.ts
 var TOOL_TRANSPORTS = ["MCP", "AGENT", "CLI"];
 function listToolNames(surface) {
@@ -667,6 +1079,95 @@ function inlineMcpAppBundle(html) {
   return html.replace(EXT_APPS_BUNDLE_PLACEHOLDER, () => bundle);
 }
 
+// src/tools/mcp-prepare.ts
+function textBlock(text) {
+  return [{ type: "text", text }];
+}
+function formatMcpResult(result, mode, toolName, errorHint) {
+  if (result.ok) {
+    if (mode === "none")
+      return { content: [] };
+    let serialized;
+    try {
+      serialized = JSON.stringify(result.data, null, 2);
+    } catch {
+      serialized = undefined;
+    }
+    if (serialized === undefined) {
+      const safe = redact(result.data, { sensitiveKeys: /(?!)/ });
+      return { content: textBlock(JSON.stringify(safe, null, 2)), structuredContent: safe };
+    }
+    return { content: textBlock(serialized), structuredContent: result.data };
+  }
+  return {
+    content: textBlock(JSON.stringify(formatToolError(result, toolName, errorHint), null, 2)),
+    isError: true
+  };
+}
+function prepareMcpSurface(services, config = {}) {
+  const serviceList = Array.isArray(services) ? services : [services];
+  const tools = serviceList.flatMap((service) => collectTools(service, "MCP", config));
+  return prepareMcpTools(tools, config);
+}
+function prepareMcpTools(tools, config = {}) {
+  const prepared = prepareProjectedMcpTools(tools.map((mountable) => ({
+    tool: mountable,
+    name: mountable.name,
+    ...mountable.method.paramsSchema !== undefined && {
+      paramsSchema: mountable.method.paramsSchema
+    },
+    ...mountable.method.inputSchema !== undefined && {
+      inputSchema: mountable.method.inputSchema
+    },
+    ...mountable.method.outputSchema !== undefined && {
+      outputSchema: mountable.method.outputSchema
+    },
+    shouldExtend: mountable.shouldExtend,
+    ...mountable.method.mcp !== undefined && { mcp: mountable.method.mcp }
+  })), config).map((entry) => {
+    Object.freeze(entry.tool);
+    return Object.freeze({
+      mountable: entry.tool,
+      inputSchema: entry.inputSchema,
+      ...entry.outputSchema !== undefined && { outputSchema: entry.outputSchema },
+      outputMode: entry.outputSchema === undefined ? "none" : "direct"
+    });
+  });
+  return Object.freeze(prepared);
+}
+function prepareMcpServerSurface(surface, config = {}) {
+  const contractMountables = [];
+  const definitions = [];
+  const runtimeMountables = [];
+  for (const entry of collectToolSurface({
+    surface,
+    transport: "MCP",
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput
+  })) {
+    if (entry.kind === "contract") {
+      contractMountables.push(entry.mountable);
+    } else {
+      definitions.push(entry.definition);
+      runtimeMountables.push(entry.mountable);
+    }
+  }
+  const contractTools = prepareMcpTools(contractMountables, config);
+  const runtimeDescriptors = prepareMcpTools(runtimeMountables, {
+    schemaValidation: config.schemaValidation,
+    logger: config.logger,
+    multiRound: config.multiRound
+  });
+  const descriptorsByName = new Map(runtimeDescriptors.map((descriptor) => [descriptor.mountable.name, descriptor]));
+  const runtimeTools = [];
+  for (const definition of definitions) {
+    const descriptor = descriptorsByName.get(definition.name);
+    if (descriptor)
+      runtimeTools.push(Object.freeze({ definition, descriptor }));
+  }
+  return Object.freeze({ contractTools, runtimeTools: Object.freeze(runtimeTools) });
+}
+
 // src/tools/mcp-round.ts
 import {
   acceptedContent,
@@ -746,29 +1247,7 @@ async function runRoundFailure(tool2, rawArgs, runTool, context, code, message)
         throw new AppError(code, message, 400);
       }
     }
-  }, rawArgs, context);
-}
-function validateMcpRoundPolicy(tool2, policy, runtime) {
-  if (!runtime?.stateConfigured) {
-    throw new Error(`[stitchkit] MCP tool "${tool2.name}" declares inputRequired but no multiRound.state key is configured`);
-  }
-  const { maxRounds } = runtime;
-  if (!Number.isInteger(maxRounds) || maxRounds < 1) {
-    throw new Error("[stitchkit] multiRound.serving.maxRounds must be a positive integer");
-  }
-  if (policy.inputRequired.length === 0) {
-    throw new Error(`[stitchkit] MCP tool "${tool2.name}" must declare at least one input round`);
-  }
-  if (policy.inputRequired.length > maxRounds) {
-    throw new Error(`[stitchkit] MCP tool "${tool2.name}" declares ${policy.inputRequired.length} input rounds, exceeding maxRounds ${maxRounds}`);
-  }
-  const keys = new Set;
-  for (const request of policy.inputRequired) {
-    if (keys.has(request.key)) {
-      throw new Error(`[stitchkit] MCP tool "${tool2.name}" declares duplicate input key "${request.key}"`);
-    }
-    keys.add(request.key);
-  }
+  }, rawArgs, context);
 }
 async function failedResolution(options) {
   const result = await runRoundFailure(options.tool, options.rawArgs, options.runTool, options.context, options.code, options.message);
@@ -902,329 +1381,6 @@ async function resolveMcpRound(options) {
   };
 }
 
-// src/tools/portable-formats.ts
-var PORTABLE_JSON_SCHEMA_FORMATS = new Set([
-  "date",
-  "time",
-  "date-time",
-  "duration",
-  "uri",
-  "uri-reference",
-  "uri-template",
-  "email",
-  "hostname",
-  "ipv4",
-  "ipv6",
-  "regex",
-  "uuid",
-  "json-pointer",
-  "relative-json-pointer"
-]);
-function propertyPath(prefix, property) {
-  return prefix ? `${prefix}.${property}` : property;
-}
-function keywordPath(prefix, keyword) {
-  if (prefix && keyword.startsWith("["))
-    return `${prefix}${keyword}`;
-  return prefix ? `${prefix}.${keyword}` : keyword;
-}
-function findNonPortableFormats(schema, allowFormats = []) {
-  const allowed = new Set([...PORTABLE_JSON_SCHEMA_FORMATS, ...allowFormats]);
-  const found = [];
-  const pending = [{ value: schema, path: "" }];
-  while (pending.length > 0) {
-    const current = pending.pop();
-    if (!current || !isRecord(current.value))
-      continue;
-    const format = current.value.format;
-    if (typeof format === "string" && !allowed.has(format)) {
-      found.push({ path: current.path || "(root)", format });
-    }
-    const properties = current.value.properties;
-    if (isRecord(properties)) {
-      for (const [key, value] of Object.entries(properties)) {
-        pending.push({ value, path: propertyPath(current.path, key) });
-      }
-    }
-    for (const mapKey of ["$defs", "definitions", "patternProperties", "dependentSchemas"]) {
-      const entries = current.value[mapKey];
-      if (!isRecord(entries))
-        continue;
-      for (const [key, value] of Object.entries(entries)) {
-        pending.push({ value, path: keywordPath(current.path, `${mapKey}.${key}`) });
-      }
-    }
-    const directChildren = [
-      ["items", "[]"],
-      ["contains", "contains"],
-      ["additionalProperties", "*"],
-      ["unevaluatedProperties", "*"],
-      ["propertyNames", "propertyNames"],
-      ["not", "not"],
-      ["if", "if"],
-      ["then", "then"],
-      ["else", "else"]
-    ];
-    for (const [keyword, segment] of directChildren) {
-      const child = current.value[keyword];
-      if (isRecord(child)) {
-        pending.push({ value: child, path: keywordPath(current.path, segment) });
-      }
-      if (Array.isArray(child)) {
-        child.forEach((value, index) => {
-          pending.push({ value, path: keywordPath(current.path, `${segment}[${index}]`) });
-        });
-      }
-    }
-    for (const keyword of ["prefixItems", "allOf", "anyOf", "oneOf"]) {
-      const branches = current.value[keyword];
-      if (!Array.isArray(branches))
-        continue;
-      branches.forEach((value, index) => {
-        pending.push({ value, path: keywordPath(current.path, `${keyword}[${index}]`) });
-      });
-    }
-  }
-  return found.sort((left, right) => left.path.localeCompare(right.path) || left.format.localeCompare(right.format));
-}
-
-// src/tools/untyped-properties.ts
-var TYPE_KEYWORDS = ["type", "enum", "const", "anyOf", "oneOf", "allOf", "$ref", "not"];
-function saysWhatItIs(schema) {
-  return TYPE_KEYWORDS.some((keyword) => schema[keyword] !== undefined);
-}
-function findUntypedProperties(schema, prefix = "") {
-  if (!isRecord(schema))
-    return [];
-  const found = [];
-  const properties = schema.properties;
-  if (isRecord(properties)) {
-    for (const [key, value] of Object.entries(properties)) {
-      const path = prefix ? `${prefix}.${key}` : key;
-      if (isRecord(value)) {
-        if (!saysWhatItIs(value)) {
-          const description = value.description;
-          found.push({
-            path,
-            ...typeof description === "string" && { description }
-          });
-        }
-        found.push(...findUntypedProperties(value, path));
-      }
-    }
-  }
-  for (const key of ["items", "additionalProperties"]) {
-    const child = schema[key];
-    if (isRecord(child))
-      found.push(...findUntypedProperties(child, prefix));
-    if (Array.isArray(child)) {
-      for (const entry of child) {
-        if (isRecord(entry))
-          found.push(...findUntypedProperties(entry, prefix));
-      }
-    }
-  }
-  for (const key of ["prefixItems"]) {
-    const child = schema[key];
-    if (Array.isArray(child)) {
-      for (const entry of child) {
-        if (isRecord(entry))
-          found.push(...findUntypedProperties(entry, prefix));
-      }
-    }
-  }
-  const patterned = schema.patternProperties;
-  if (isRecord(patterned)) {
-    for (const value of Object.values(patterned)) {
-      if (isRecord(value))
-        found.push(...findUntypedProperties(value, prefix));
-    }
-  }
-  for (const key of ["$defs", "definitions"]) {
-    const container = schema[key];
-    if (!isRecord(container))
-      continue;
-    for (const definition of Object.values(container)) {
-      if (isRecord(definition))
-        found.push(...findUntypedProperties(definition, prefix));
-    }
-  }
-  for (const key of ["allOf", "anyOf", "oneOf"]) {
-    const branches = schema[key];
-    if (Array.isArray(branches)) {
-      for (const branch of branches)
-        found.push(...findUntypedProperties(branch, prefix));
-    }
-  }
-  return found;
-}
-
-// src/tools/mcp-prepare.ts
-function textBlock(text) {
-  return [{ type: "text", text }];
-}
-function formatMcpResult(result, mode, toolName, errorHint) {
-  if (result.ok) {
-    if (mode === "none")
-      return { content: [] };
-    let serialized;
-    try {
-      serialized = JSON.stringify(result.data, null, 2);
-    } catch {
-      serialized = undefined;
-    }
-    if (serialized === undefined) {
-      const safe = redact(result.data, { sensitiveKeys: /(?!)/ });
-      return { content: textBlock(JSON.stringify(safe, null, 2)), structuredContent: safe };
-    }
-    return { content: textBlock(serialized), structuredContent: result.data };
-  }
-  return {
-    content: textBlock(JSON.stringify(formatToolError(result, toolName, errorHint), null, 2)),
-    isError: true
-  };
-}
-function probeSchema(schema, io) {
-  try {
-    toJsonSchema(schema, io);
-    return null;
-  } catch (err) {
-    return err instanceof Error ? err.message : String(err);
-  }
-}
-function resolveOutputSchema(outputSchema) {
-  if (!outputSchema)
-    return null;
-  return { schema: outputSchema, mode: "direct" };
-}
-function reportIncompatible(message, policy, logger, failures) {
-  if (policy === "throw") {
-    failures.push(message);
-  } else if (policy === "warn") {
-    if (logger)
-      logger.warn(`[stitchkit] ${message}`);
-    else
-      console.warn(`[stitchkit] ${message}`);
-  }
-}
-function throwIfFailures(failures) {
-  if (failures.length > 0) {
-    throw new Error(`[stitchkit] ${failures.length} problem(s) with MCP tool schemas:
- - ${failures.join(`
- - `)}`);
-  }
-}
-function prepareMcpTool(mountable, config, validation, logger, failures, seen) {
-  const policy = validation.policy ?? "throw";
-  assertUniqueToolName(mountable.name, seen.has(mountable.name), "MCP tool name");
-  seen.add(mountable.name);
-  if (mountable.method.mcp) {
-    validateMcpRoundPolicy(mountable, mountable.method.mcp, config.multiRound);
-  }
-  let inputJsonSchema;
-  try {
-    inputJsonSchema = buildToolPresentationSchema({
-      paramsSchema: mountable.method.paramsSchema,
-      inputSchema: mountable.method.inputSchema,
-      extendSchema: mountable.shouldExtend && config.extend ? config.extend.schema : undefined,
-      flattenUnionInput: config.flattenUnionInput,
-      unrepresentable: "throw"
-    });
-  } catch (err) {
-    reportIncompatible(`MCP tool "${mountable.name}" — input schema is not JSON Schema-compatible: ${err instanceof Error ? err.message : String(err)}`, policy, logger, failures);
-    return null;
-  }
-  if (!isObjectPresentationSchema(inputJsonSchema)) {
-    reportIncompatible(`MCP tool "${mountable.name}" — input must be an object schema; a union, discriminated union or scalar cannot be an MCP tool input (flatten it in the contract, or drop MCP from \`expose\`)`, policy, logger, failures);
-    return null;
-  }
-  if (validation.requireTypedProperties) {
-    const allowed = new Set(validation.allowUntyped ?? []);
-    for (const untyped of findUntypedProperties(inputJsonSchema)) {
-      const path = `${mountable.name}.${untyped.path}`;
-      if (allowed.has(path))
-        continue;
-      const clue = untyped.description ? ` (only a description: "${untyped.description}")` : "";
-      reportIncompatible(`MCP tool "${mountable.name}" — input property "${untyped.path}" carries no type, enum or $ref${clue}. ` + "A model is given no way to know what to send. Use `z.json()` for an arbitrary JSON value; use `allowUntyped` only when the presentation value is genuinely not representable as JSON Schema.", policy === "skip" ? "warn" : policy, logger, failures);
-    }
-  }
-  if (validation.requirePortableFormats) {
-    for (const finding of findNonPortableFormats(inputJsonSchema, validation.allowFormats)) {
-      reportIncompatible(`MCP tool "${mountable.name}" — input property "${finding.path}" uses non-portable JSON Schema format "${finding.format}". ` + "Use a portable pattern/schema, or list the format in `allowFormats` only when every MCP client supports it.", policy === "skip" ? "warn" : policy, logger, failures);
-    }
-  }
-  const resolved = resolveOutputSchema(mountable.method.outputSchema);
-  if (!resolved)
-    return { mountable, inputSchema: inputJsonSchema, outputMode: "none" };
-  const outputError = probeSchema(resolved.schema, "output");
-  if (outputError) {
-    reportIncompatible(`MCP tool "${mountable.name}" — output schema is not JSON Schema-compatible: ${outputError}`, policy, logger, failures);
-    return { mountable, inputSchema: inputJsonSchema, outputMode: "none" };
-  }
-  if (validation.requirePortableFormats) {
-    for (const finding of findNonPortableFormats(toJsonSchema(resolved.schema, "output"), validation.allowFormats)) {
-      reportIncompatible(`MCP tool "${mountable.name}" — output property "${finding.path}" uses non-portable JSON Schema format "${finding.format}". ` + "Use a portable pattern/schema, or list the format in `allowFormats` only when every MCP client supports it.", policy === "skip" ? "warn" : policy, logger, failures);
-    }
-  }
-  return {
-    mountable,
-    inputSchema: inputJsonSchema,
-    outputSchema: resolved.schema,
-    outputMode: resolved.mode
-  };
-}
-function prepareMcpSurface(services, config = {}) {
-  const serviceList = Array.isArray(services) ? services : [services];
-  const tools = serviceList.flatMap((service) => collectTools(service, "MCP", config));
-  return prepareMcpTools(tools, config);
-}
-function prepareMcpTools(tools, config = {}) {
-  const seen = new Set;
-  const failures = [];
-  const prepared = [];
-  for (const mountable of tools) {
-    const tool2 = prepareMcpTool(mountable, config, config.schemaValidation ?? {}, config.logger, failures, seen);
-    if (tool2) {
-      Object.freeze(tool2.mountable);
-      prepared.push(Object.freeze(tool2));
-    }
-  }
-  throwIfFailures(failures);
-  return Object.freeze(prepared);
-}
-function prepareMcpServerSurface(surface, config = {}) {
-  const contractMountables = [];
-  const definitions = [];
-  const runtimeMountables = [];
-  for (const entry of collectToolSurface({
-    surface,
-    transport: "MCP",
-    extend: config.extend,
-    flattenUnionInput: config.flattenUnionInput
-  })) {
-    if (entry.kind === "contract") {
-      contractMountables.push(entry.mountable);
-    } else {
-      definitions.push(entry.definition);
-      runtimeMountables.push(entry.mountable);
-    }
-  }
-  const contractTools = prepareMcpTools(contractMountables, config);
-  const runtimeDescriptors = prepareMcpTools(runtimeMountables, {
-    schemaValidation: config.schemaValidation,
-    logger: config.logger,
-    multiRound: config.multiRound
-  });
-  const descriptorsByName = new Map(runtimeDescriptors.map((descriptor) => [descriptor.mountable.name, descriptor]));
-  const runtimeTools = [];
-  for (const definition of definitions) {
-    const descriptor = descriptorsByName.get(definition.name);
-    if (descriptor)
-      runtimeTools.push(Object.freeze({ definition, descriptor }));
-  }
-  return Object.freeze({ contractTools, runtimeTools: Object.freeze(runtimeTools) });
-}
-
 // src/tools/mcp-trace.ts
 import {
   BAGGAGE_META_KEY,
@@ -1610,8 +1766,8 @@ function createMcpHandler(config) {
   const authByCarrier = new WeakMap;
   let closed = false;
   let resolveClosed;
-  const closedSignal = new Promise((resolve3) => {
-    resolveClosed = resolve3;
+  const closedSignal = new Promise((resolve) => {
+    resolveClosed = resolve;
   });
   const sdkHandler = createSdkMcpHandler(({ authInfo }) => {
     const resolved = authInfo ? authByCarrier.get(authInfo) : undefined;
@@ -1714,8 +1870,8 @@ function bindStdioProcessSignals(handle, options = {}) {
   let rejectChain = () => {
     return;
   };
-  const promise = new Promise((resolve3, reject) => {
-    resolveChain = resolve3;
+  const promise = new Promise((resolve, reject) => {
+    resolveChain = resolve;
     rejectChain = reject;
   });
   promise.catch(() => {
@@ -1811,44 +1967,51 @@ function mountDownload(server, config) {
         return textResult("Nothing to download.", true);
       const result = await runDownloadOperation({
         url,
-        dir: config.dirFromArgs?.(args) ?? config.defaultDir,
+        files: config.files,
+        path: config.pathFromArgs?.(args),
         allowPrivateHosts: config.allowPrivateHosts,
         maxBytes: config.maxBytes,
         timeoutMs: config.timeoutMs
       });
       return textResult(JSON.stringify(result, null, 2));
-    } catch (err) {
-      return textResult(`Download failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    } catch (error) {
+      if (error instanceof DownloadOperationError) {
+        return textResult(`Download failed [${error.code}]: ${error.message}`, true);
+      }
+      const normalized = normalizeFileToolError(error);
+      return textResult(`Download failed [${normalized.code}]: ${normalized.message}`, true);
     }
   });
 }
 // src/tools/mount-upload.ts
-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: z7.string().describe("Path to a local file on this machine") }
+    inputSchema: {
+      path: ManagedFilePathSchema.describe("Path relative to the configured file boundary")
+    }
   }, 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 runUploadOperation(path, config.upload);
+      const uploaded = await runUploadOperation(config.files, 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);
+    } catch (error) {
+      const normalized = normalizeFileToolError(error);
+      return textResult(`Upload failed [${normalized.code}]: ${normalized.message}`, true);
     }
   });
 }
 // src/tools/mount-wait.ts
-import { z as z8 } from "zod";
+import { z as z7 } from "zod";
 function mountWait(server, config) {
   const name = config.name ?? "wait";
   assertToolName(name, "<native>", "wait");
-  server.registerTool(name, { description: config.description, inputSchema: z8.object(config.inputSchema) }, async (rawArgs) => {
+  server.registerTool(name, { description: config.description, inputSchema: z7.object(config.inputSchema) }, async (rawArgs) => {
     const args = isRecord(rawArgs) ? rawArgs : {};
     try {
       const { state, timedOut } = await runWaitOperation({
@@ -1867,19 +2030,19 @@ function mountWait(server, config) {
 }
 // src/tools/oauth-provider.ts
 import { randomUUID } from "node:crypto";
-import { z as z9 } from "zod";
+import { z as z8 } from "zod";
 function isPlainDisplayCharacter(character) {
   const codePoint = character.codePointAt(0);
   return codePoint !== undefined && codePoint >= 32 && codePoint !== 127 && character !== "<" && character !== ">";
 }
-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), {
+var CimdClientMetadataSchema = z8.object({
+  client_id: z8.url(),
+  redirect_uris: z8.array(z8.url()).min(1),
+  client_name: z8.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: z9.literal("none"),
-  application_type: z9.enum(["native", "web"]).optional()
+  token_endpoint_auth_method: z8.literal("none"),
+  application_type: z8.enum(["native", "web"]).optional()
 });
 function createSecureClientMetadataFetcher(policy = {}) {
   assertPositiveInteger("cimd.maxBytes", policy.maxBytes ?? DEFAULT_CIMD_MAX_BYTES);
@@ -2512,67 +2675,6 @@ function mountOAuthProvider(config) {
   };
   return dcrEnabled ? [metadataRoute, registerRoute, authorizeRoute, tokenRoute] : [metadataRoute, authorizeRoute, tokenRoute];
 }
-// src/tools/remote.ts
-var HTTP_ONLY = Object.freeze(["HTTP"]);
-function toArgs(ctx) {
-  const { params, input } = ctx;
-  return {
-    ...isRecord(params) ? params : {},
-    ...isRecord(input) ? input : {}
-  };
-}
-function implementRemote(contract, http, options) {
-  const client = createClient(contract, http);
-  const groupScope = contract.meta.scope ?? "public";
-  const methods = {};
-  for (const [key, endpoint] of Object.entries(contract.endpoints)) {
-    methods[key] = {
-      method: endpoint.method,
-      path: endpoint.path,
-      desc: endpoint.desc,
-      serviceName: contract.meta.prefix,
-      key,
-      toolName: "toolName" in endpoint ? endpoint.toolName : undefined,
-      expose: endpoint.rawResponse || endpoint.rawBody || endpoint.responseMeta ? HTTP_ONLY : endpoint.expose,
-      ui: "ui" in endpoint ? endpoint.ui : undefined,
-      annotations: "annotations" in endpoint ? endpoint.annotations : undefined,
-      meta: mergeMeta(contract.meta.meta, endpoint.meta),
-      scope: endpoint.scope ?? groupScope,
-      paramsSchema: endpoint.params,
-      inputSchema: endpoint.input,
-      outputSchema: endpoint.output,
-      multipart: endpoint.multipart,
-      maxJsonBodyBytes: endpoint.maxJsonBodyBytes,
-      idempotent: endpoint.idempotent,
-      rawResponse: endpoint.rawResponse,
-      rawBody: endpoint.rawBody,
-      responseMeta: endpoint.responseMeta,
-      contentType: "contentType" in endpoint ? endpoint.contentType : undefined,
-      handler: async (ctx) => {
-        const call = client[key];
-        if (!call) {
-          throw new Error(`implementRemote: endpoint "${key}" is not exposed over HTTP`);
-        }
-        const args = toArgs(ctx);
-        try {
-          const finalArgs = options?.transformArgs ? await options.transformArgs(key, args) : args;
-          return await call(finalArgs);
-        } catch (err) {
-          if (ApiError.is(err)) {
-            throw new AppError(err.code, err.message, err.status, isRecord(err.details) ? err.details : undefined, err.hint, err.traceId);
-          }
-          throw err;
-        }
-      }
-    };
-  }
-  return {
-    name: contract.meta.prefix,
-    prefix: contract.meta.prefix,
-    scope: groupScope,
-    methods
-  };
-}
 // src/tools/tool-logger.ts
 function createToolLogger(config = {}) {
   const log = config.log ?? ((line) => console.error(line));
@@ -2673,56 +2775,60 @@ function summarizeTransports(surface) {
   };
 }
 export {
-  wwwAuthenticateHeader,
-  validateMcpSchemas,
-  summarizeTransports,
-  resolveMedia,
-  protectedResourceMetadataUrl,
-  oauthProtectedResourceRoute,
-  mountWait,
-  mountViewFile,
-  mountUpload,
-  mountOAuthProvider,
-  mountMcpResource,
-  mountMcp,
-  mountDownload,
-  mountAgent,
-  listToolNames,
-  listContractToolNames,
-  inlineMcpAppBundle,
-  implementRemote,
-  flattenToolJsonSchema,
-  findUntypedProperties,
-  findNonPortableFormats,
-  defineWaitTool,
-  defineViewFileTool,
-  defineUploadTool,
-  defineRuntimeTool,
-  defineDownloadTool,
-  defineCliCommand,
-  createToolkit,
-  createToolLogger,
-  createToolInvoker,
-  createStdioMcpServer,
-  createSecureClientMetadataFetcher,
-  createRuntimeToolFactory,
-  createMcpHttpRoute,
-  createMcpHandler,
-  createCli,
-  collectTools,
-  coerceJsonArgs,
-  buildToolManifest,
-  buildMcpServer,
-  bindStdioProcessSignals,
-  ViewFileOutputSchema,
-  ViewFileInputSchema,
-  ViewFileErrorSchema,
-  UploadToolInputSchema,
-  RESOURCE_MIME_TYPE,
-  PROTECTED_RESOURCE_PATH,
-  PORTABLE_JSON_SCHEMA_FORMATS,
-  McpMediaContentSchema,
-  McpAnnotationsSchema,
+  AsyncOperationCancelResultSchema,
   EXT_APPS_BUNDLE_PLACEHOLDER,
-  DownloadResultSchema
+  McpAnnotationsSchema,
+  McpMediaContentSchema,
+  PORTABLE_JSON_SCHEMA_FORMATS,
+  PROTECTED_RESOURCE_PATH,
+  RESOURCE_MIME_TYPE,
+  UploadToolInputSchema,
+  ViewFileErrorSchema,
+  ViewFileInputSchema,
+  ViewFileOutputSchema,
+  bindContractAsyncOperation,
+  bindStdioProcessSignals,
+  buildMcpServer,
+  buildToolManifest,
+  coerceJsonArgs,
+  collectTools,
+  composeToolLifecycle,
+  createAsyncOperationSnapshotSchema,
+  createCli,
+  createMcpHandler,
+  createMcpHttpRoute,
+  createRuntimeToolFactory,
+  createSecureClientMetadataFetcher,
+  createStdioMcpServer,
+  createToolInvoker,
+  createToolLogger,
+  createToolkit,
+  defineAsyncOperation,
+  defineAsyncOperationContract,
+  defineCliCommand,
+  defineDownloadTool,
+  defineRuntimeTool,
+  defineUploadTool,
+  defineViewFileTool,
+  defineWaitTool,
+  findNonPortableFormats,
+  findUntypedProperties,
+  flattenToolJsonSchema,
+  inlineMcpAppBundle,
+  listContractToolNames,
+  listToolNames,
+  mountAgent,
+  mountDownload,
+  mountMcp,
+  mountMcpResource,
+  mountOAuthProvider,
+  mountUpload,
+  mountViewFile,
+  mountWait,
+  oauthProtectedResourceRoute,
+  protectedResourceMetadataUrl,
+  resolveMedia,
+  summarizeTransports,
+  validateMcpSchemas,
+  wwwAuthenticateHeader
 };