stitchkit 0.53.2 → 0.55.0

package/dist/{index-c78w2y09.js → index-0gv7k0ra.js}

@@ -1,23 +1,33 @@
 import {
-  isWithinDir,
+  isWithinDir
+} from "./index-sbdmyz75.js";
+import {
+  assertToolName,
+  assertUniqueToolName,
+  hasUsableChars,
+  toToolName
+} from "./index-k4dftwf7.js";
+import {
   jsonSchemaFields,
   toJsonSchema
-} from "./index-yxpe3phd.js";
+} from "./index-cby4ar3v.js";
 import {
-  AppError,
-  STITCH_ERROR_STATUS,
   formatZodError,
   getRequestContext,
-  isStitchErrorCode,
-  isUnsafeKey,
   normalizeError,
   runWithRequestContext,
-  safeJsonParse,
   validateDeclaredOutput
-} from "./index-173tvqcp.js";
+} from "./index-v4bbq3p4.js";
+import {
+  AppError,
+  STITCH_ERROR_STATUS,
+  isStitchErrorCode,
+  isUnsafeKey,
+  safeJsonParse
+} from "./index-h60df7rj.js";
 import {
   isRecord
-} from "./index-bmnhqtya.js";
+} from "./index-7eq9va6e.js";
 
 // src/tools/coerce.ts
 import { z } from "zod";
@@ -671,7 +681,12 @@ async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycl
     }
     try {
       const resolved = await extension.resolve({ ...rawArgs, ...parsed.data });
-      callContext = { ...context, ...resolved, source: context.source };
+      callContext = {
+        ...context,
+        ...resolved,
+        source: context.source,
+        ...context.mcp !== undefined && { mcp: context.mcp }
+      };
       hookContext = callContext;
       callArgs = Object.fromEntries(Object.entries(rawArgs).filter(([key]) => !extensionKeys.has(key)));
     } catch (err) {
@@ -764,71 +779,6 @@ async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycl
   }
 }
 
-// src/tools/names.ts
-var SINGULAR_EXCEPTIONS = new Set([
-  "analytics",
-  "status",
-  "stats",
-  "settings",
-  "media",
-  "progress",
-  "news"
-]);
-var TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
-function normalizeService(value) {
-  return value.replace(/[^a-zA-Z0-9_]/g, "_");
-}
-function normalizeMethod(value) {
-  return value.replace(/[^a-zA-Z0-9_-]/g, "_");
-}
-function singularize(name) {
-  if (SINGULAR_EXCEPTIONS.has(name))
-    return name;
-  if (name.endsWith("ies"))
-    return `${name.slice(0, -3)}y`;
-  if (name.endsWith("s") && !name.endsWith("ss"))
-    return name.slice(0, -1);
-  return name;
-}
-function singularizeTail(name) {
-  const cut = name.lastIndexOf("_");
-  if (cut === -1)
-    return singularize(name);
-  return `${name.slice(0, cut + 1)}${singularize(name.slice(cut + 1))}`;
-}
-function hasUsableChars(value) {
-  return /[a-zA-Z0-9]/.test(value);
-}
-function assertToolName(name, serviceName, key) {
-  const where = `service "${serviceName}", method "${key}"`;
-  if (!TOOL_NAME_RE.test(name)) {
-    const why = name.length > 64 ? `is ${name.length} characters (max 64) — set an explicit \`toolName\`` : "must match [a-zA-Z0-9_-]";
-    throw new Error(`Tool name "${name}" (${where}) ${why}`);
-  }
-}
-function toToolName(serviceName, methodName) {
-  const normalized = normalizeService(serviceName);
-  const singular = singularizeTail(normalized);
-  const method = normalizeMethod(methodName);
-  if (method === "list")
-    return `list_${normalized}`;
-  if (method === "get")
-    return `get_${singular}`;
-  if (method === "create")
-    return `create_${singular}`;
-  if (method === "update")
-    return `update_${singular}`;
-  if (method === "delete")
-    return `delete_${singular}`;
-  const snake = method.replace(/([A-Z])/g, "_$1").toLowerCase();
-  return `${snake}_${singular}`.replace(/^_/, "");
-}
-function assertUniqueToolName(name, taken, surface) {
-  if (taken) {
-    throw new Error(`Duplicate ${surface} "${name}" across mounted operations`);
-  }
-}
-
 // src/tools/presentation.ts
 import { z as z3 } from "zod";
 function withoutDialect(schema) {
@@ -1020,6 +970,100 @@ function formatToolError(result, toolName, errorHint) {
   return err;
 }
 
+// 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,
+      ...context.mcp !== undefined && { mcp: context.mcp }
+    };
+  }
+  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`);
+  }
+  if (!definition.transports)
+    return transport !== "CLI";
+  return 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/cli-args.ts
 import { z as z5 } from "zod";
 var NUMERIC_VALUE = /^-(\d+\.?\d*|\.\d+)$/;
@@ -1341,6 +1385,50 @@ function parseCliArgs(argv, schema, config = {}) {
   return { toolArgs, options };
 }
 
+// src/tools/cli-command.ts
+function defineCliCommand(definition) {
+  return definition;
+}
+function cliCommandPresentationSchema(definition) {
+  return buildToolPresentationSchema({
+    inputSchema: definition.input,
+    unrepresentable: "any"
+  });
+}
+async function executeCliCommand(definition, rawArgs, options, writers, coerceJson) {
+  let parsed;
+  try {
+    parsed = definition.input.safeParse(coerceJson ? coerceJsonArgs(rawArgs, definition.input) : rawArgs);
+  } catch (error) {
+    return toolResultFromError(error);
+  }
+  if (!parsed.success) {
+    return {
+      ok: false,
+      code: "VALIDATION_ERROR",
+      details: { message: `Invalid input: ${formatZodError(parsed.error)}` }
+    };
+  }
+  try {
+    const data = await definition.handler({
+      input: parsed.data,
+      options,
+      ...writers
+    });
+    const checked = validateDeclaredOutput(definition.output, data);
+    if (!checked.ok) {
+      return {
+        ok: false,
+        code: "INTERNAL_SERVER_ERROR",
+        details: { message: checked.message }
+      };
+    }
+    return { ok: true, data: checked.data };
+  } catch (error) {
+    return toolResultFromError(error);
+  }
+}
+
 // src/tools/cli-format.ts
 var DEFAULT_EXIT_CODES = {
   VALIDATION_ERROR: 1,
@@ -1351,19 +1439,21 @@ var DEFAULT_EXIT_CODES = {
   CONFLICT: 5,
   RATE_LIMITED: 6,
   TIMEOUT: 7,
+  WAIT_FAILED: 1,
   INTERNAL_SERVER_ERROR: 1
 };
 function emitResult(result, writers, opts) {
   if (result.ok) {
     if (result.data === undefined)
       return 0;
-    const text = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
-    writers.stdout(`${text}
+    const text2 = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
+    writers.stdout(`${text2}
 `);
     return 0;
   }
   const error = formatToolError(result, opts.toolName, opts.errorHint);
-  writers.stderr(`${JSON.stringify(error, null, 2)}
+  const text = opts.json ? JSON.stringify(error) : JSON.stringify(error, null, 2);
+  writers.stderr(`${text}
 `);
   const codes = opts.exitCodes ?? DEFAULT_EXIT_CODES;
   return codes[result.code] ?? 1;
@@ -1372,45 +1462,140 @@ function emitResult(result, writers, opts) {
 // src/tools/wait-core.ts
 var DEFAULT_BACKOFF = [2, 3, 5, 5, 8, 10];
 var DEFAULT_TIMEOUT = 600;
-var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+class WaitTimeoutError extends Error {
+  constructor() {
+    super("wait deadline elapsed before the first snapshot");
+    this.name = "WaitTimeoutError";
+  }
+}
+var defaultSleep = (ms, signal) => {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = (action) => {
+      if (settled)
+        return;
+      settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      action();
+    };
+    const timer = setTimeout(() => {
+      settle(resolve);
+    }, ms);
+    timer.unref?.();
+    const onAbort = () => {
+      clearTimeout(timer);
+      settle(() => reject(signal?.reason ?? new Error("aborted")));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted)
+      onAbort();
+  });
+};
 async function pollUntil(params) {
   const backoff = params.backoff?.length ? params.backoff : DEFAULT_BACKOFF;
   const lastBackoff = backoff[backoff.length - 1] ?? 5;
   const timeoutSec = params.timeoutSec ?? DEFAULT_TIMEOUT;
   const sleep = params.sleepFn ?? defaultSleep;
-  const startedAt = Date.now();
+  const now = params.nowFn ?? (() => performance.now());
+  const startedAt = now();
+  const deadline = startedAt + timeoutSec * 1000;
+  let last;
   for (let attempt = 0;; attempt++) {
-    const state = await params.poll();
+    params.signal?.throwIfAborted();
+    const remainingBeforePoll = Math.max(0, deadline - now());
+    if (remainingBeforePoll === 0 && last) {
+      return { state: last.state, timedOut: true };
+    }
+    const deadlineController = new AbortController;
+    const onCallerAbort = () => deadlineController.abort(params.signal?.reason);
+    params.signal?.addEventListener("abort", onCallerAbort, { once: true });
+    const deadlineTimer = setTimeout(() => deadlineController.abort(new WaitTimeoutError), remainingBeforePoll);
+    deadlineTimer.unref?.();
+    let state;
+    try {
+      state = await params.poll(deadlineController.signal);
+    } catch (error) {
+      if (params.signal?.aborted)
+        throw params.signal.reason ?? error;
+      if (deadlineController.signal.aborted && now() >= deadline) {
+        if (last)
+          return { state: last.state, timedOut: true };
+        throw new WaitTimeoutError;
+      }
+      throw error;
+    } finally {
+      clearTimeout(deadlineTimer);
+      params.signal?.removeEventListener("abort", onCallerAbort);
+    }
+    params.signal?.throwIfAborted();
+    last = { state };
     if (params.done(state))
       return { state, timedOut: false };
-    const elapsedSec = (Date.now() - startedAt) / 1000;
+    const elapsedMs = now() - startedAt;
+    const elapsedSec = elapsedMs / 1000;
     params.onTick?.(attempt + 1, elapsedSec);
     if (elapsedSec >= timeoutSec)
       return { state, timedOut: true };
     const waitSec = backoff[Math.min(attempt, backoff.length - 1)] ?? lastBackoff;
-    await sleep(waitSec * 1000);
+    await sleep(Math.min(waitSec * 1000, Math.max(0, deadline - now())), params.signal);
   }
 }
+function runWaitOperation(params) {
+  return pollUntil({
+    poll: (signal) => params.poll(params.input, signal),
+    done: params.done,
+    backoff: params.backoff,
+    timeoutSec: params.timeoutSec,
+    sleepFn: params.sleepFn,
+    onTick: params.onTick,
+    signal: params.signal,
+    nowFn: params.nowFn
+  });
+}
 
 // src/tools/cli-wait.ts
 var DEFAULT_TIMEOUT2 = 600;
+function waitFailure(tool, result) {
+  return {
+    ok: false,
+    code: "WAIT_FAILED",
+    details: {
+      message: `"${tool}" reached a terminal failed state`,
+      result
+    }
+  };
+}
 async function pollUntilDone(params) {
   const { initial, wait, call } = params;
   if (!initial.ok)
     return initial;
+  if (wait.failed?.(initial.data))
+    return waitFailure(wait.tool, initial.data);
   if (wait.done(initial.data))
     return initial;
   const pollArgs = wait.poll(initial.data);
   if (!pollArgs)
     return initial;
   const timeoutSec = params.timeoutSec ?? wait.timeout ?? DEFAULT_TIMEOUT2;
+  let failedState;
   const { state, timedOut } = await pollUntil({
     poll: () => call(wait.tool, pollArgs),
-    done: (result) => !result.ok || wait.done(result.data),
+    done: (result) => {
+      if (!result.ok)
+        return true;
+      if (wait.failed?.(result.data)) {
+        failedState = result;
+        return true;
+      }
+      return wait.done(result.data);
+    },
     backoff: wait.backoff,
     timeoutSec,
     sleepFn: params.sleepFn,
-    onTick: params.onTick
+    onTick: params.onTick,
+    signal: params.signal
   });
   if (timedOut) {
     return {
@@ -1419,6 +1604,8 @@ async function pollUntilDone(params) {
       details: { message: `Timed out after ${timeoutSec}s waiting for "${wait.tool}"` }
     };
   }
+  if (state === failedState && state.ok)
+    return waitFailure(wait.tool, state.data);
   return state;
 }
 
@@ -1733,9 +1920,56 @@ async function writeDownload(root, target, data) {
   await writeFile(target, data);
 }
 
+// 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
+      });
+    }
+  }
+  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/cli.ts
 var GLOBAL_OPTIONS = [
-  ["--json", "Emit raw JSON on stdout (for piping / scripts)"],
+  ["--json", "Emit compact success/error JSON records (for scripts)"],
   ["--wait", "Block-poll an async result to a terminal state"],
   ["--wait-timeout <s>", "Override the --wait timeout in seconds"],
   ["--output-dir <dir>", "Download result media into a directory"],
@@ -1810,7 +2044,7 @@ function collectPassthrough(toolArgs, field, knownKeys) {
   const base = passthroughBase(toolArgs[field]);
   toolArgs[field] = base ? { ...base, ...bag } : bag;
 }
-function renderTopHelp(name, version, tools) {
+function renderTopHelp(name, version, commands) {
   const lines = [
     `${name} ${version}`,
     "",
@@ -1818,9 +2052,9 @@ function renderTopHelp(name, version, tools) {
     "",
     "Commands:"
   ];
-  const width = Math.max(0, ...[...tools.keys()].map((k) => k.length));
-  for (const [command, tool] of tools) {
-    lines.push(`  ${padRight(command, width)}  ${summarize(tool.method.desc)}`);
+  const width = Math.max(0, ...[...commands.keys()].map((key) => key.length));
+  for (const [command, descriptor] of commands) {
+    lines.push(`  ${padRight(command, width)}  ${summarize(descriptor.description)}`);
   }
   lines.push("", "Global options:");
   const optWidth = Math.max(...GLOBAL_OPTIONS.map(([flag]) => flag.length));
@@ -1831,16 +2065,42 @@ function renderTopHelp(name, version, tools) {
 `)}
 `;
 }
-function renderCommandHelp(name, command, tool) {
-  const lines = [tool.method.desc, "", `Usage: ${name} ${command} [args] [--flags]`, ""];
-  const fields = jsonSchemaFields(tool.presentationSchema);
+function renderCommandHelp(name, command, descriptor) {
+  const fields = jsonSchemaFields(descriptor.presentationSchema);
+  const fieldsByName = new Map(fields.map((field) => [field.name, field]));
+  const positionals = [];
+  for (const [fieldName, info] of describeSchemaFields(descriptor.argumentSchema)) {
+    if (info.kind === "boolean")
+      continue;
+    const field = fieldsByName.get(fieldName);
+    if (field)
+      positionals.push(field);
+  }
+  const positionalSyntax = new Map(positionals.map((field) => [
+    field.name,
+    field.required ? `<${field.name}>` : `[${field.name}]`
+  ]));
+  const usage = [
+    `Usage: ${name} ${command}`,
+    ...positionals.map((field) => positionalSyntax.get(field.name) ?? field.name),
+    "[--flags]"
+  ].join(" ");
+  const lines = [descriptor.description, "", usage, ""];
   if (fields.length > 0) {
     lines.push("Arguments:");
-    const width = Math.max(...fields.map((f) => f.name.length));
+    const labels = new Map(fields.map((field) => {
+      const positional = positionalSyntax.get(field.name);
+      return [
+        field.name,
+        positional ? `${positional} | --${field.name}` : `--${field.name}`
+      ];
+    }));
+    const width = Math.max(...fields.map((field) => labels.get(field.name)?.length ?? 0));
     for (const f of fields) {
       const req = f.required ? " (required)" : "";
       const desc = f.description ? ` — ${f.description}` : "";
-      lines.push(`  --${padRight(f.name, width)}  <${typeLabel(f.schema)}>${req}${desc}`);
+      const label = labels.get(f.name) ?? `--${f.name}`;
+      lines.push(`  ${padRight(label, width)}  <${typeLabel(f.schema)}>${req}${desc}`);
     }
     lines.push("");
   }
@@ -1848,6 +2108,55 @@ function renderCommandHelp(name, command, tool) {
 `)}
 `;
 }
+function managedDescriptor(tool) {
+  return {
+    description: tool.method.desc,
+    argumentSchema: tool.argumentSchema,
+    presentationSchema: tool.presentationSchema
+  };
+}
+function nativeDescriptor(definition) {
+  return {
+    description: definition.description,
+    argumentSchema: definition.input,
+    presentationSchema: cliCommandPresentationSchema(definition)
+  };
+}
+function assertCommandShape(name, descriptor, exists) {
+  assertUniqueToolName(name, exists, "CLI command");
+  if (name === "help" || name === "version") {
+    throw new Error(`[stitchkit] CLI command "${name}" is reserved`);
+  }
+  const conflicting = jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name).filter((field) => RESERVED_CLI_OPTIONS.has(field));
+  if (conflicting.length > 0) {
+    throw new Error(`[stitchkit] CLI command "${name}" declares reserved option field(s): ${conflicting.join(", ")}`);
+  }
+}
+async function prepareInvocation(command, commandArgv, descriptor, config, readStdin) {
+  let parsed;
+  try {
+    parsed = parseCliArgs(commandArgv, descriptor.argumentSchema, {
+      allowUnknown: config.passthrough?.[command] !== undefined,
+      knownFields: jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name)
+    });
+  } catch (error) {
+    if (!(error instanceof CliArgumentError))
+      throw error;
+    return { ok: false, message: error.message };
+  }
+  const { toolArgs, options } = parsed;
+  const firstUnset = jsonSchemaFields(descriptor.presentationSchema).find((field) => field.required && !(field.name in toolArgs) && field.schema.type !== "boolean");
+  if (firstUnset) {
+    const piped = await readStdin();
+    if (piped !== null)
+      toolArgs[firstUnset.name] = piped;
+  }
+  const passthroughField = config.passthrough?.[command];
+  if (passthroughField) {
+    collectPassthrough(toolArgs, passthroughField, objectShapeKeys(descriptor.argumentSchema));
+  }
+  return { ok: true, toolArgs, options };
+}
 var DEFAULT_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;
 async function downloadResults(files, dir, stderr, quiet, allowPrivate, maxBytes, timeoutMs) {
   const root = resolve(dir);
@@ -1886,66 +2195,121 @@ async function createCli(config) {
   const exit = config.exit ?? ((code) => void process.exit(code));
   const argv = config.argv ?? process.argv.slice(2);
   const readStdin = config.stdin ?? readPipedStdin;
-  const auth = config.auth === undefined ? undefined : await config.auth;
-  const services = typeof config.services === "function" ? config.services(auth) : config.services;
-  const context = config.context?.(auth);
-  const tools = new Map;
-  for (const service of services) {
-    for (const mountable of collectTools(service, "CLI")) {
-      assertUniqueToolName(mountable.name, tools.has(mountable.name), "CLI command");
-      if (mountable.name === "help" || mountable.name === "version") {
-        throw new Error(`[stitchkit] CLI command "${mountable.name}" is reserved`);
-      }
-      const conflicting = jsonSchemaFields(mountable.presentationSchema).map((field) => field.name).filter((name) => RESERVED_CLI_OPTIONS.has(name));
-      if (conflicting.length > 0) {
-        throw new Error(`[stitchkit] CLI command "${mountable.name}" declares reserved option field(s): ${conflicting.join(", ")}`);
-      }
-      tools.set(mountable.name, mountable);
-    }
+  if (config.auth !== undefined && config.resolveAuth !== undefined) {
+    throw new Error("[stitchkit] createCli: use either auth or resolveAuth, not both");
   }
-  const runTool = createToolRunner({
-    source: "cli",
-    context,
-    hooks: config.hooks,
-    lifecycle: config.lifecycle,
-    errorHint: config.errorHint,
-    coerceJsonArgs: config.coerceJsonArgs
-  });
-  const [command, ...commandArgv] = argv;
-  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-    stdout(renderTopHelp(config.name, config.version, tools));
-    return exit(0);
+  const nativeCommands = new Map;
+  const nativeHelp = new Map;
+  for (const definition of config.commands ?? []) {
+    const descriptor2 = nativeDescriptor(definition);
+    assertCommandShape(definition.name, descriptor2, nativeCommands.has(definition.name));
+    nativeCommands.set(definition.name, definition);
+    nativeHelp.set(definition.name, descriptor2);
   }
+  const [command, ...commandArgv] = argv;
   if (command === "--version" || command === "version") {
     stdout(`${config.name} ${config.version}
 `);
     return exit(0);
   }
-  const tool = tools.get(command);
+  const beforeSeparator = commandArgv.indexOf("--") === -1 ? commandArgv : commandArgv.slice(0, commandArgv.indexOf("--"));
+  const helpRequested = beforeSeparator.includes("--help") || beforeSeparator.includes("-h");
+  const native = command === undefined ? undefined : nativeCommands.get(command);
+  if (native && command !== undefined) {
+    const descriptor2 = nativeHelp.get(command);
+    if (!descriptor2)
+      throw new Error("[stitchkit] native CLI descriptor invariant failed");
+    if (helpRequested) {
+      stdout(renderCommandHelp(config.name, command, descriptor2));
+      return exit(0);
+    }
+    const prepared2 = await prepareInvocation(command, commandArgv, descriptor2, config, readStdin);
+    if (!prepared2.ok) {
+      stderr(`${prepared2.message}
+`);
+      return exit(2);
+    }
+    const { toolArgs: toolArgs2, options: options2 } = prepared2;
+    if (options2.help) {
+      stdout(renderCommandHelp(config.name, command, descriptor2));
+      return exit(0);
+    }
+    if (options2.wait) {
+      stderr(`--wait is not configured for native command "${command}"
+`);
+      return exit(2);
+    }
+    if (options2.waitTimeout !== undefined) {
+      stderr(`--wait-timeout requires --wait
+`);
+      return exit(2);
+    }
+    if (options2.outputDir !== undefined) {
+      stderr(`--output-dir is not configured for native commands
+`);
+      return exit(2);
+    }
+    if (options2.dryRun) {
+      stdout(`${JSON.stringify({ command, args: toolArgs2 }, null, 2)}
+`);
+      return exit(0);
+    }
+    const result2 = await executeCliCommand(native, toolArgs2, options2, { stdout, stderr }, config.coerceJsonArgs ?? true);
+    const exitCode2 = emitResult(result2, { stdout, stderr }, {
+      json: options2.json,
+      toolName: command,
+      errorHint: config.errorHint,
+      exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
+    });
+    return exit(exitCode2);
+  }
+  let authPromise;
+  const resolveIdentity = () => {
+    authPromise ??= Promise.resolve(config.resolveAuth ? config.resolveAuth() : config.auth);
+    return authPromise;
+  };
+  const dynamicSurface = typeof config.services === "function" || typeof config.runtimeTools === "function";
+  const buildManagedSurface = async (forExecution) => {
+    const auth = dynamicSurface || forExecution ? await resolveIdentity() : undefined;
+    const services = typeof config.services === "function" ? config.services(auth) : config.services ?? [];
+    const runtimeTools = typeof config.runtimeTools === "function" ? config.runtimeTools(auth) : config.runtimeTools ?? [];
+    const tools = new Map;
+    const help = new Map(nativeHelp);
+    for (const { mountable } of collectToolSurface({
+      surface: { services, runtimeTools },
+      transport: "CLI"
+    })) {
+      const descriptor2 = managedDescriptor(mountable);
+      assertCommandShape(mountable.name, descriptor2, help.has(mountable.name));
+      tools.set(mountable.name, mountable);
+      help.set(mountable.name, descriptor2);
+    }
+    return { auth, help, tools };
+  };
+  const topLevelHelp = command === undefined || command === "help" || command === "--help" || command === "-h";
+  const managed = await buildManagedSurface(!topLevelHelp && !helpRequested);
+  if (topLevelHelp) {
+    stdout(renderTopHelp(config.name, config.version, managed.help));
+    return exit(0);
+  }
+  const tool = managed.tools.get(command);
   if (!tool) {
     stderr(`Unknown command "${command}". Run "${config.name} --help" for the command list.
 `);
     return exit(1);
   }
-  const beforeSeparator = commandArgv.indexOf("--") === -1 ? commandArgv : commandArgv.slice(0, commandArgv.indexOf("--"));
-  if (beforeSeparator.includes("--help") || beforeSeparator.includes("-h")) {
-    stdout(renderCommandHelp(config.name, command, tool));
+  const descriptor = managedDescriptor(tool);
+  if (helpRequested) {
+    stdout(renderCommandHelp(config.name, command, descriptor));
     return exit(0);
   }
-  let parsed;
-  try {
-    parsed = parseCliArgs(commandArgv, tool.argumentSchema, {
-      allowUnknown: config.passthrough?.[command] !== undefined,
-      knownFields: jsonSchemaFields(tool.presentationSchema).map((field) => field.name)
-    });
-  } catch (error) {
-    if (!(error instanceof CliArgumentError))
-      throw error;
-    stderr(`${error.message}
+  const prepared = await prepareInvocation(command, commandArgv, descriptor, config, readStdin);
+  if (!prepared.ok) {
+    stderr(`${prepared.message}
 `);
     return exit(2);
   }
-  const { toolArgs, options } = parsed;
+  const { toolArgs, options } = prepared;
   if (options.wait && !config.wait?.[command]) {
     stderr(`--wait is not configured for command "${command}"
 `);
@@ -1962,25 +2326,22 @@ async function createCli(config) {
     return exit(2);
   }
   if (options.help) {
-    stdout(renderCommandHelp(config.name, command, tool));
+    stdout(renderCommandHelp(config.name, command, descriptor));
     return exit(0);
   }
-  const fields = jsonSchemaFields(safeInputSchema(tool));
-  const firstUnset = fields.find((f) => f.required && !(f.name in toolArgs) && f.schema.type !== "boolean");
-  if (firstUnset) {
-    const piped = await readStdin();
-    if (piped !== null)
-      toolArgs[firstUnset.name] = piped;
-  }
-  const passthroughField = config.passthrough?.[command];
-  if (passthroughField) {
-    collectPassthrough(toolArgs, passthroughField, objectShapeKeys(tool.argumentSchema));
-  }
   if (options.dryRun) {
     stdout(`${JSON.stringify({ command, args: toolArgs }, null, 2)}
 `);
     return exit(0);
   }
+  const runTool = createToolRunner({
+    source: "cli",
+    context: { ...config.context?.(managed.auth), signal: config.signal },
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    errorHint: config.errorHint,
+    coerceJsonArgs: config.coerceJsonArgs
+  });
   let result;
   try {
     result = await runTool(tool, toolArgs);
@@ -1993,7 +2354,7 @@ async function createCli(config) {
       initial: result,
       wait: waitConfig,
       call: async (toolName, args) => {
-        const pollTool = tools.get(toolName);
+        const pollTool = managed.tools.get(toolName);
         if (!pollTool) {
           return {
             ok: false,
@@ -2005,7 +2366,8 @@ async function createCli(config) {
       },
       timeoutSec: options.waitTimeout,
       onTick: options.quiet ? undefined : (attempt) => stderr(`waiting… (poll ${attempt})
-`)
+`),
+      signal: config.signal
     });
   }
   let downloadsOk = true;
@@ -2020,8 +2382,5 @@ async function createCli(config) {
   });
   return exit(downloadsOk ? exitCode : 1);
 }
-function safeInputSchema(tool) {
-  return tool.presentationSchema;
-}
 
-export { coerceJsonArgs, toolResultFromError, toolErrorFromResult, executeToolMethod, assertToolName, assertUniqueToolName, flattenToolJsonSchema, buildToolPresentationSchema, isObjectPresentationSchema, presentationMetadata, collectTools, createToolRunner, formatToolError, fetchGuarded, fetchPinnedDocument, readCapped, writeDownload, parseCliArgs, DEFAULT_EXIT_CODES, emitResult, pollUntil, pollUntilDone, createCli };
+export { coerceJsonArgs, toolResultFromError, toolErrorFromResult, executeToolMethod, flattenToolJsonSchema, buildToolPresentationSchema, isObjectPresentationSchema, presentationMetadata, collectTools, createToolRunner, formatToolError, defineRuntimeTool, createRuntimeToolFactory, collectToolSurface, WaitTimeoutError, runWaitOperation, fetchGuarded, fetchPinnedDocument, readCapped, parseCliArgs, defineCliCommand, DEFAULT_EXIT_CODES, emitResult, pollUntilDone, createCli };