stitchkit 0.93.0 → 0.94.1

package/dist/index-3bmnp41g.js

@@ -1,2169 +0,0 @@
-import {
-  isWithinDir
-} from "./index-sbdmyz75.js";
-import {
-  collectToolSurface
-} from "./index-2c2bjw3s.js";
-import {
-  createToolRunner,
-  formatToolError
-} from "./index-mzvgxp0n.js";
-import {
-  toolErrorFromResult,
-  toolResultFromError
-} from "./index-yn8remb1.js";
-import {
-  formatZodError,
-  validateDeclaredOutput
-} from "./index-e0znv5gn.js";
-import {
-  coerceJsonArgs
-} from "./index-7zbps32p.js";
-import {
-  assertUniqueToolName,
-  buildToolPresentationSchema,
-  objectShapeKeys
-} from "./index-h9etkkyk.js";
-import {
-  jsonSchemaFields
-} from "./index-cby4ar3v.js";
-import {
-  isUnsafeKey,
-  safeJsonParse
-} from "./index-kzfs85xp.js";
-import {
-  isRecord
-} from "./index-77fekveh.js";
-
-// src/tools/cli-args.ts
-import { z } from "zod";
-var NUMERIC_VALUE = /^-(\d+\.?\d*|\.\d+)$/;
-var BOOL_OPTIONS = new Set(["json", "wait", "quiet", "dry-run", "help", "ascending"]);
-var VIEW_OPTIONS = new Set(["count-by", "sum", "by", "top", "table", "sort"]);
-var VALUE_OPTIONS = new Set(["wait-timeout", "output-dir", ...VIEW_OPTIONS]);
-var RESERVED_CLI_OPTIONS = new Set([...BOOL_OPTIONS, ...VALUE_OPTIONS]);
-function classifyLongOptionToken(token) {
-  if (!token.startsWith("--") || token === "--")
-    return;
-  const equals = token.indexOf("=");
-  const name = equals >= 0 ? token.slice(2, equals) : token.slice(2);
-  return {
-    name,
-    value: equals >= 0 ? token.slice(equals + 1) : undefined,
-    inline: equals >= 0,
-    globalKind: BOOL_OPTIONS.has(name) ? "boolean" : VALUE_OPTIONS.has(name) ? "value" : undefined
-  };
-}
-var HELP_TOKENS = new Set(["--help", "-h", "help"]);
-function helpFilterFrom(token, rest) {
-  if (token?.startsWith("--help=")) {
-    const value = token.slice("--help=".length).trim();
-    if (value.length === 0 || isReservedBoolWord(value))
-      return;
-    return value;
-  }
-  if (token === undefined || !HELP_TOKENS.has(token))
-    return;
-  const next = rest[0];
-  return next !== undefined && !next.startsWith("-") ? next : undefined;
-}
-function routeCliArgv(argv, defaultCommand) {
-  if (defaultCommand === undefined) {
-    const [command, ...commandArgv] = argv;
-    const helpFilter = helpFilterFrom(command, commandArgv);
-    return {
-      command,
-      commandArgv,
-      topLevelHelp: false,
-      version: false,
-      ...helpFilter !== undefined && { helpFilter }
-    };
-  }
-  const globals = [];
-  let index = 0;
-  while (index < argv.length) {
-    const token = argv[index];
-    if (token === undefined)
-      break;
-    if (token === "--") {
-      return {
-        commandArgv: [],
-        topLevelHelp: false,
-        version: false,
-        error: 'A command is required before "--"'
-      };
-    }
-    const inlineHelpFilter = token.startsWith("--help=") && !isReservedBoolWord(token.slice("--help=".length));
-    if (token === "--help" || token === "-h" || inlineHelpFilter) {
-      const helpFilter = helpFilterFrom(token, argv.slice(index + 1));
-      return {
-        commandArgv: [],
-        topLevelHelp: true,
-        version: false,
-        ...helpFilter !== undefined && { helpFilter }
-      };
-    }
-    if (token === "--version" || token === "version") {
-      return { commandArgv: [], topLevelHelp: false, version: true };
-    }
-    if (!token.startsWith("-") || token === "-") {
-      return {
-        command: token,
-        commandArgv: [...globals, ...argv.slice(index + 1)],
-        topLevelHelp: false,
-        version: false
-      };
-    }
-    if (!token.startsWith("--")) {
-      return {
-        command: defaultCommand,
-        commandArgv: [...globals, ...argv.slice(index)],
-        topLevelHelp: false,
-        version: false
-      };
-    }
-    const option = classifyLongOptionToken(token);
-    if (!option) {
-      return {
-        command: defaultCommand,
-        commandArgv: [...globals, ...argv.slice(index)],
-        topLevelHelp: false,
-        version: false
-      };
-    }
-    if (option.globalKind === "boolean") {
-      globals.push(token);
-      index += 1;
-      continue;
-    }
-    if (option.globalKind === "value") {
-      globals.push(token);
-      if (!option.inline) {
-        const value = argv[index + 1];
-        if (value === "--help" || value === "-h") {
-          const helpFilter = helpFilterFrom(value, argv.slice(index + 2));
-          return {
-            commandArgv: [],
-            topLevelHelp: true,
-            version: false,
-            ...helpFilter !== undefined && { helpFilter }
-          };
-        }
-        if (value === "--version" || value === "version") {
-          return { commandArgv: [], topLevelHelp: false, version: true };
-        }
-        if (value !== undefined)
-          globals.push(value);
-        index += value === undefined ? 1 : 2;
-      } else {
-        index += 1;
-      }
-      continue;
-    }
-    return {
-      command: defaultCommand,
-      commandArgv: [...globals, ...argv.slice(index)],
-      topLevelHelp: false,
-      version: false
-    };
-  }
-  return {
-    command: defaultCommand,
-    commandArgv: globals,
-    topLevelHelp: false,
-    version: false
-  };
-}
-
-class CliArgumentError extends Error {
-  name = "CliArgumentError";
-}
-function unwrap(field) {
-  if (field instanceof z.ZodOptional || field instanceof z.ZodNullable || field instanceof z.ZodDefault) {
-    return unwrap(field.unwrap());
-  }
-  return field;
-}
-function classify(field) {
-  if (field instanceof z.ZodBoolean)
-    return "boolean";
-  if (field instanceof z.ZodNumber)
-    return "number";
-  if (field instanceof z.ZodBigInt)
-    return "bigint";
-  if (field instanceof z.ZodDate)
-    return "date";
-  if (field instanceof z.ZodEnum)
-    return "enum";
-  if (field instanceof z.ZodArray)
-    return "array";
-  if (field instanceof z.ZodObject)
-    return "object";
-  if (field instanceof z.ZodString || field instanceof z.ZodLiteral)
-    return "string";
-  return "other";
-}
-function mergeField(fields, name, info) {
-  const existing = fields.get(name);
-  if (!existing) {
-    fields.set(name, info);
-    return;
-  }
-  if (existing.kind === info.kind)
-    return;
-  if (existing.kind === "boolean" || info.kind === "boolean") {
-    fields.set(name, { kind: "boolean" });
-    return;
-  }
-  fields.set(name, { kind: "other" });
-}
-function collectSchemaFields(schema, fields) {
-  const base = unwrap(schema);
-  if (base instanceof z.ZodObject) {
-    for (const [name, raw] of Object.entries(base.shape)) {
-      const fieldBase = unwrap(raw);
-      const kind = classify(fieldBase);
-      if (kind === "array" && fieldBase instanceof z.ZodArray) {
-        mergeField(fields, name, { kind, elementKind: classify(unwrap(fieldBase.element)) });
-      } else {
-        mergeField(fields, name, { kind });
-      }
-    }
-    return;
-  }
-  if (base instanceof z.ZodUnion) {
-    for (const option of base.def.options)
-      collectSchemaFields(option, fields);
-    return;
-  }
-  if (base instanceof z.ZodIntersection) {
-    collectSchemaFields(base.def.left, fields);
-    collectSchemaFields(base.def.right, fields);
-    return;
-  }
-}
-function describeSchemaFields(schema) {
-  const fields = new Map;
-  if (schema)
-    collectSchemaFields(schema, fields);
-  return fields;
-}
-var TRUE_WORDS = new Set(["true", "1", "yes", "on"]);
-var FALSE_WORDS = new Set(["false", "0", "no", "off"]);
-function isReservedBoolWord(value) {
-  const word = value.toLowerCase();
-  return TRUE_WORDS.has(word) || FALSE_WORDS.has(word);
-}
-function parseReservedBool(name, value) {
-  const v = value.toLowerCase();
-  if (TRUE_WORDS.has(v))
-    return true;
-  if (FALSE_WORDS.has(v))
-    return false;
-  throw new CliArgumentError(`--${name} expects a boolean (true/false), got "${value}"`);
-}
-function coerceScalar(kind, value) {
-  switch (kind) {
-    case "boolean": {
-      const v = value.toLowerCase();
-      if (TRUE_WORDS.has(v))
-        return true;
-      if (FALSE_WORDS.has(v))
-        return false;
-      return value;
-    }
-    case "number": {
-      const n = Number(value);
-      return value.trim() !== "" && !Number.isNaN(n) ? n : value;
-    }
-    case "bigint":
-      try {
-        return BigInt(value);
-      } catch {
-        return value;
-      }
-    case "date": {
-      const d = new Date(value);
-      return Number.isNaN(d.getTime()) ? value : d;
-    }
-    default:
-      return value;
-  }
-}
-function looseCoerce(value) {
-  if (value === "true")
-    return true;
-  if (value === "false")
-    return false;
-  const n = Number(value);
-  return value.trim() !== "" && !Number.isNaN(n) ? n : value;
-}
-function looksLikeJson(value) {
-  const t = value.trim();
-  return t.startsWith("[") || t.startsWith("{");
-}
-function coerceField(info, values) {
-  const last = values[values.length - 1] ?? "";
-  if (!info)
-    return values.length > 1 ? values : last;
-  if (info.kind === "array") {
-    if (values.length === 1 && looksLikeJson(last))
-      return last;
-    return values.map((v) => coerceScalar(info.elementKind ?? "string", v));
-  }
-  if (info.kind === "object")
-    return last;
-  return coerceScalar(info.kind, last);
-}
-function setNested(target, path, value) {
-  const unsafe = path.find(isUnsafeKey);
-  if (unsafe !== undefined) {
-    throw new CliArgumentError(`Unsafe option path segment "${unsafe}"`);
-  }
-  let node = target;
-  for (let i = 0;i < path.length - 1; i++) {
-    const key = path[i];
-    if (key === undefined)
-      return;
-    const next = node[key];
-    if (isRecord(next)) {
-      node = next;
-    } else {
-      const created = {};
-      node[key] = created;
-      node = created;
-    }
-  }
-  const leaf = path[path.length - 1];
-  if (leaf !== undefined)
-    node[leaf] = value;
-}
-function parseCliArgs(argv, schema, config = {}) {
-  const options = {
-    json: false,
-    wait: false,
-    quiet: false,
-    dryRun: false,
-    help: false
-  };
-  const fields = describeSchemaFields(schema);
-  for (const name of config.knownFields ?? []) {
-    if (!fields.has(name))
-      fields.set(name, { kind: "other" });
-  }
-  const flags = new Map;
-  const boolFlags = new Map;
-  const viewFlags = new Map;
-  let ascending = false;
-  const positionals = [];
-  const pushFlag = (name, value) => {
-    const existing = flags.get(name);
-    if (existing)
-      existing.push(value);
-    else
-      flags.set(name, [value]);
-  };
-  let optionsEnded = false;
-  for (let i = 0;i < argv.length; i++) {
-    const tok = argv[i];
-    if (tok === undefined)
-      continue;
-    if (!optionsEnded && tok === "--") {
-      optionsEnded = true;
-      continue;
-    }
-    if (optionsEnded || !tok.startsWith("-") || tok === "-") {
-      positionals.push(tok);
-      continue;
-    }
-    if (tok === "-h") {
-      options.help = true;
-      continue;
-    }
-    if (!tok.startsWith("--")) {
-      const match = /^-([A-Za-z])(?:=(.*))?$/.exec(tok);
-      const alias = match?.[1];
-      const field = alias === undefined ? undefined : config.optionAliases?.get(alias);
-      if (!alias || !field)
-        throw new CliArgumentError(`Unknown option "${tok}"`);
-      const inline = match?.[2];
-      const info2 = fields.get(field);
-      if (info2?.kind === "boolean") {
-        boolFlags.set(field, inline === undefined ? true : parseReservedBool(field, inline));
-        continue;
-      }
-      let value2 = inline;
-      if (value2 === undefined) {
-        const next = argv[i + 1];
-        if (next !== undefined && (!next.startsWith("-") || NUMERIC_VALUE.test(next))) {
-          value2 = next;
-          i++;
-        } else {
-          throw new CliArgumentError(`--${field} requires a value`);
-        }
-      }
-      pushFlag(field, value2);
-      continue;
-    }
-    const option = classifyLongOptionToken(tok);
-    if (!option)
-      throw new CliArgumentError(`Unknown option "${tok}"`);
-    const { name } = option;
-    let { value } = option;
-    if (name.length === 0)
-      throw new CliArgumentError("Invalid empty option name");
-    if (option.globalKind === "boolean") {
-      const enabled = value === undefined ? true : parseReservedBool(name, value);
-      if (name === "dry-run")
-        options.dryRun = enabled;
-      else if (name === "json")
-        options.json = enabled;
-      else if (name === "wait")
-        options.wait = enabled;
-      else if (name === "quiet")
-        options.quiet = enabled;
-      else if (name === "ascending")
-        ascending = enabled;
-      else
-        options.help = enabled;
-      continue;
-    }
-    if (option.globalKind === "value") {
-      const next = argv[i + 1];
-      value = value ?? next;
-      if (value === undefined || value.startsWith("-") && !NUMERIC_VALUE.test(value)) {
-        throw new CliArgumentError(`--${name} requires a value`);
-      }
-      if (!option.inline)
-        i++;
-      if (name === "wait-timeout") {
-        const timeout = Number(value);
-        if (!Number.isFinite(timeout) || timeout <= 0) {
-          throw new CliArgumentError("--wait-timeout must be a positive number");
-        }
-        options.waitTimeout = timeout;
-      } else if (VIEW_OPTIONS.has(name)) {
-        if (viewFlags.has(name))
-          throw new CliArgumentError(`--${name} was given twice`);
-        viewFlags.set(name, value);
-      } else {
-        options.outputDir = value;
-      }
-      continue;
-    }
-    if (value === undefined && name.startsWith("no-") && fields.get(name.slice(3))?.kind === "boolean") {
-      boolFlags.set(name.slice(3), false);
-      continue;
-    }
-    const unsafeSegment = name.split(".").find(isUnsafeKey);
-    if (unsafeSegment !== undefined) {
-      throw new CliArgumentError(`Unsafe option name "--${name}"`);
-    }
-    const info = fields.get(name);
-    const rootName = name.split(".")[0] ?? name;
-    if (!fields.has(rootName) && !config.allowUnknown) {
-      throw new CliArgumentError(`Unknown option "--${name}"`);
-    }
-    if (value === undefined) {
-      if (info?.kind === "boolean") {
-        boolFlags.set(name, true);
-        continue;
-      }
-      const next = argv[i + 1];
-      if (next !== undefined && (!next.startsWith("-") || NUMERIC_VALUE.test(next))) {
-        value = next;
-        i++;
-      } else {
-        throw new CliArgumentError(`--${name} requires a value`);
-      }
-    }
-    pushFlag(name, value);
-  }
-  const view = resolveCliView(viewFlags, ascending);
-  if (view)
-    options.view = view;
-  const toolArgs = {};
-  const fillable = config.positionals === undefined ? [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name) : [...config.positionals];
-  const variadicTail = config.positionals !== undefined && fields.get(fillable[fillable.length - 1] ?? "")?.kind === "array" ? fillable[fillable.length - 1] : undefined;
-  let pi = 0;
-  for (const key of fillable) {
-    if (pi >= positionals.length)
-      break;
-    if (key === variadicTail) {
-      if (flags.has(key)) {
-        throw new CliArgumentError(`--${key} conflicts with the positional values for "${key}" — pass one form, not both`);
-      }
-      toolArgs[key] = coerceField(fields.get(key), positionals.slice(pi));
-      pi = positionals.length;
-      break;
-    }
-    if (flags.has(key))
-      continue;
-    const value = positionals[pi++];
-    if (value !== undefined)
-      toolArgs[key] = coerceField(fields.get(key), [value]);
-  }
-  if (pi < positionals.length) {
-    throw new CliArgumentError(`Unexpected positional argument "${positionals[pi]}"`);
-  }
-  for (const [key, value] of boolFlags) {
-    toolArgs[key] = value;
-  }
-  const dottedRoots = new Map;
-  for (const key of flags.keys()) {
-    const dot = key.indexOf(".");
-    if (dot > 0)
-      dottedRoots.set(key.slice(0, dot), key);
-  }
-  for (const [root, dotted] of dottedRoots) {
-    if (flags.has(root)) {
-      throw new CliArgumentError(`--${root} conflicts with --${dotted} — pass one form, not both`);
-    }
-  }
-  for (const [key, values] of flags) {
-    if (key.includes(".")) {
-      if (values.length > 1) {
-        throw new CliArgumentError(`--${key} was passed ${values.length} times`);
-      }
-      setNested(toolArgs, key.split("."), looseCoerce(values[0] ?? ""));
-      continue;
-    }
-    const info = fields.get(key);
-    if (values.length > 1 && info !== undefined && info.kind !== "array" && info.kind !== "other") {
-      throw new CliArgumentError(`--${key} was passed ${values.length} times`);
-    }
-    toolArgs[key] = coerceField(info, values);
-  }
-  return { toolArgs, options };
-}
-function extractCliGlobalOptions(argv, schema) {
-  if (schema === undefined)
-    return { argv: [...argv], globals: {} };
-  const fields = describeSchemaFields(schema);
-  const rest = [];
-  const raw = new Map;
-  let ended = false;
-  for (let i = 0;i < argv.length; i++) {
-    const token = argv[i];
-    if (token === undefined)
-      continue;
-    if (!ended && token === "--")
-      ended = true;
-    const option = ended ? undefined : classifyLongOptionToken(token);
-    const info = option && option.globalKind === undefined ? fields.get(option.name) : undefined;
-    if (!option || !info) {
-      rest.push(token);
-      continue;
-    }
-    let { value } = option;
-    if (value === undefined && info.kind === "boolean") {
-      value = "true";
-    } else if (value === undefined) {
-      const next = argv[i + 1];
-      if (next !== undefined && (!next.startsWith("-") || NUMERIC_VALUE.test(next))) {
-        value = next;
-        i++;
-      } else {
-        throw new CliArgumentError(`--${option.name} requires a value`);
-      }
-    }
-    const existing = raw.get(option.name);
-    if (existing)
-      existing.push(value);
-    else
-      raw.set(option.name, [value]);
-  }
-  const args = {};
-  for (const [name, values] of raw)
-    args[name] = coerceField(fields.get(name), values);
-  const parsed = schema.safeParse(coerceJsonArgs(args, schema));
-  if (!parsed.success) {
-    const issue = parsed.error.issues[0];
-    const field = issue?.path[0];
-    const where = typeof field === "string" ? `--${field}` : "application option";
-    throw new CliArgumentError(`${where}: ${issue?.message ?? "invalid value"}`);
-  }
-  return { argv: rest, globals: parsed.data };
-}
-function resolveCliView(flags, ascending) {
-  if (flags.size === 0) {
-    if (ascending) {
-      throw new CliArgumentError("--ascending orders a record view; pass --sort with it");
-    }
-    return;
-  }
-  const countBy = flags.get("count-by");
-  const sum = flags.get("sum");
-  const table = flags.get("table");
-  const by = flags.get("by");
-  const rawTop = flags.get("top");
-  const named = [
-    ["--count-by", countBy],
-    ["--sum", sum]
-  ].filter(([, value]) => value !== undefined);
-  if (named.length > 1) {
-    throw new CliArgumentError(`${named.map(([flag]) => flag).join(" and ")} ask for different shapes — pass one`);
-  }
-  let top;
-  if (rawTop !== undefined) {
-    top = Number(rawTop);
-    if (!Number.isInteger(top) || top <= 0) {
-      throw new CliArgumentError("--top must be a positive whole number");
-    }
-  }
-  const sort = flags.get("sort");
-  if (table !== undefined || sort !== undefined) {
-    if (countBy !== undefined || sum !== undefined) {
-      throw new CliArgumentError(`${table !== undefined ? "--table" : "--sort"} lists records; --count-by and --sum aggregate them — pass one`);
-    }
-    if (by !== undefined) {
-      throw new CliArgumentError("--by groups a view; a record view orders with --sort");
-    }
-    if (top !== undefined && sort === undefined) {
-      throw new CliArgumentError("--top needs --sort here: unordered records have no n largest");
-    }
-    let fields;
-    if (table !== undefined) {
-      fields = table.split(",").map((field) => field.trim()).filter(Boolean);
-      if (fields.length === 0)
-        throw new CliArgumentError("--table needs at least one field");
-    }
-    return {
-      kind: "records",
-      ...sort !== undefined && { sort },
-      ...ascending && { ascending },
-      ...top !== undefined && { top },
-      ...fields && { table: fields }
-    };
-  }
-  if (ascending) {
-    throw new CliArgumentError("--ascending orders a record view; pass --sort with it");
-  }
-  if (sum !== undefined) {
-    if (top !== undefined && by === undefined) {
-      throw new CliArgumentError("--top needs --by: a single sum has nothing to rank");
-    }
-    return {
-      kind: "sum",
-      field: sum,
-      ...by !== undefined && { by },
-      ...top !== undefined && { top }
-    };
-  }
-  if (countBy !== undefined) {
-    if (by !== undefined) {
-      throw new CliArgumentError("--count-by already names the grouping field; drop --by");
-    }
-    return { kind: "count", field: countBy, ...top !== undefined && { top } };
-  }
-  if (by !== undefined) {
-    if (top === undefined) {
-      throw new CliArgumentError("--by groups a view; pass --count-by, --sum or --top with it");
-    }
-    return { kind: "count", field: by, top };
-  }
-  throw new CliArgumentError("--top needs --sort, --by, --count-by or --sum to rank");
-}
-
-// src/tools/cli-command.ts
-function defineCliCommand(definition) {
-  return definition;
-}
-function cliCommandReturnsResult(definition) {
-  return definition.output !== undefined;
-}
-function cliCommandSuccessExitCode(definition, data) {
-  const successExitCode = definition.exitCode?.(data) ?? 0;
-  if (!Number.isSafeInteger(successExitCode) || successExitCode < 0 || successExitCode > 255) {
-    throw new Error("CLI success exit code must be an integer from 0 to 255");
-  }
-  return successExitCode;
-}
-function prepareCliCommandEmission(definition, result, options) {
-  if (!result.ok || definition.output === undefined) {
-    return { result, successExitCode: 0 };
-  }
-  try {
-    const successExitCode = cliCommandSuccessExitCode(definition, result.data);
-    const presentation = definition.present?.({ result: result.data, options });
-    if (presentation !== undefined && typeof presentation !== "string") {
-      throw new Error("CLI result presenter must return a string");
-    }
-    return { result, presentation, successExitCode };
-  } catch (error) {
-    return {
-      result: toolResultFromError(new Error("CLI result policy failed", { cause: error })),
-      successExitCode: 0
-    };
-  }
-}
-function cliCommandPresentationSchema(definition) {
-  return buildToolPresentationSchema({
-    inputSchema: definition.input,
-    unrepresentable: "any"
-  });
-}
-async function executeCliCommand(definition, rawArgs, options, writers, coerceJson, globals = {}) {
-  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,
-      globals,
-      ...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,
-  BAD_REQUEST: 1,
-  UNAUTHORIZED: 2,
-  FORBIDDEN: 3,
-  NOT_FOUND: 4,
-  CONFLICT: 5,
-  RATE_LIMITED: 6,
-  TIMEOUT: 7,
-  WAIT_FAILED: 1,
-  INTERNAL_SERVER_ERROR: 1
-};
-function cliExitCode(result, exitCodes) {
-  if (result.ok)
-    return 0;
-  const codes = { ...DEFAULT_EXIT_CODES, ...exitCodes };
-  return Object.hasOwn(codes, result.code) ? codes[result.code] ?? 1 : 1;
-}
-function emitResult(result, writers, opts) {
-  if (result.ok) {
-    if (result.data === undefined)
-      return 0;
-    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);
-  const text = opts.json ? JSON.stringify(error) : JSON.stringify(error, null, 2);
-  writers.stderr(`${text}
-`);
-  return cliExitCode(result, opts.exitCodes);
-}
-
-// src/tools/cli-policy.ts
-var SHORT_ALIAS = /^[A-Za-z]$/;
-var RESERVED_SHORT_OPTIONS = new Set(["h"]);
-function fieldMap(descriptor) {
-  return new Map(jsonSchemaFields(descriptor.presentationSchema).map((field) => [field.name, field]));
-}
-function resolveAliases(command, descriptor, configured) {
-  if (!configured)
-    return new Map;
-  const fields = fieldMap(descriptor);
-  const aliases = new Map;
-  for (const [alias, target] of Object.entries(configured)) {
-    if (!SHORT_ALIAS.test(alias)) {
-      throw new Error(`[stitchkit] CLI command "${command}" alias "${alias}" must be one ASCII letter`);
-    }
-    if (RESERVED_SHORT_OPTIONS.has(alias)) {
-      throw new Error(`[stitchkit] CLI command "${command}" alias "-${alias}" is reserved`);
-    }
-    if (isUnsafeKey(target) || !fields.has(target)) {
-      throw new Error(`[stitchkit] CLI command "${command}" alias "-${alias}" targets unknown field "${target}"`);
-    }
-    const existing = aliases.get(target);
-    if (existing !== undefined) {
-      throw new Error(`[stitchkit] CLI command "${command}" field "${target}" has multiple aliases: -${existing}, -${alias}`);
-    }
-    aliases.set(target, alias);
-  }
-  return aliases;
-}
-function resolvePositionals(command, descriptor, configured) {
-  if (configured === undefined)
-    return;
-  const fields = fieldMap(descriptor);
-  const kinds = describeSchemaFields(descriptor.argumentSchema);
-  const seen = new Set;
-  let optionalSeen = false;
-  for (const name of configured) {
-    const field = fields.get(name);
-    if (isUnsafeKey(name) || !field || !kinds.has(name)) {
-      throw new Error(`[stitchkit] CLI command "${command}" positional targets unknown field "${name}"`);
-    }
-    if (seen.has(name)) {
-      throw new Error(`[stitchkit] CLI command "${command}" repeats positional field "${name}"`);
-    }
-    if (kinds.get(name)?.kind === "boolean") {
-      throw new Error(`[stitchkit] CLI command "${command}" boolean field "${name}" cannot be positional`);
-    }
-    if (optionalSeen && field.required) {
-      throw new Error(`[stitchkit] CLI command "${command}" required positional "${name}" cannot follow an optional positional`);
-    }
-    if (!field.required)
-      optionalSeen = true;
-    seen.add(name);
-  }
-  return [...configured];
-}
-function applyCliPresentationPolicy(command, descriptor, config) {
-  const base = { ...descriptor, aliases: new Map };
-  const configuredAliases = config.optionAliases && Object.hasOwn(config.optionAliases, command) ? config.optionAliases[command] : undefined;
-  const configuredPositionals = config.positionals && Object.hasOwn(config.positionals, command) ? config.positionals[command] : undefined;
-  return {
-    ...base,
-    aliases: resolveAliases(command, base, configuredAliases),
-    positionals: resolvePositionals(command, base, configuredPositionals)
-  };
-}
-function assertCliPoliciesResolved(commands, config) {
-  const configuredNames = new Set([
-    ...Object.keys(config.optionAliases ?? {}),
-    ...Object.keys(config.positionals ?? {})
-  ]);
-  if (config.defaultCommand !== undefined)
-    configuredNames.add(config.defaultCommand);
-  for (const name of configuredNames) {
-    if (!commands.has(name)) {
-      throw new Error(`[stitchkit] CLI policy targets unavailable command "${name}"`);
-    }
-  }
-}
-
-// src/tools/cli-invoke.ts
-function parseCliGlobals(schema, globals) {
-  if (!schema)
-    return globals ?? {};
-  return schema.parse(globals ?? {});
-}
-function cliInvocationResult(result, toolName, config) {
-  if (result.ok)
-    return { ok: true, exitCode: 0, data: result.data };
-  const normalized = toolErrorFromResult(result);
-  const hints = [];
-  if (result.hint)
-    hints.push(result.hint);
-  const global = config.errorHint?.(toolName, result.code);
-  if (global)
-    hints.push(global);
-  return {
-    ok: false,
-    exitCode: cliExitCode(result, config.exitCodes),
-    error: {
-      code: result.code,
-      message: normalized.message,
-      ...result.details !== undefined && { details: result.details },
-      ...hints.length > 0 && { hint: hints.join(" ") },
-      ...result.retryable !== undefined && { retryable: result.retryable }
-    }
-  };
-}
-async function createCliInvoker(config, globals) {
-  const typedGlobals = parseCliGlobals(config.globalOptions, globals);
-  const auth = await (config.resolveAuth ? config.resolveAuth(typedGlobals) : config.auth);
-  const natives = new Map((config.commands ?? []).filter(cliCommandReturnsResult).map((definition) => [definition.name, definition]));
-  const nativeHelp = new Map([...natives].map(([name, definition]) => [
-    name,
-    { description: definition.description, argumentSchema: {}, presentationSchema: {} }
-  ]));
-  const { tools, help } = buildCliSurface(config, auth, new Map, new Set);
-  const runTool = createToolRunner({
-    source: "cli",
-    context: { ...config.context?.(auth, typedGlobals), signal: config.signal },
-    hooks: config.hooks,
-    lifecycle: config.lifecycle,
-    errorHint: config.errorHint,
-    coerceJsonArgs: config.coerceJsonArgs
-  });
-  return {
-    commands: [...nativeHelp, ...help].map(([name, presentation]) => ({
-      name,
-      description: presentation.description
-    })),
-    invoke: async (command, args) => {
-      const native = natives.get(command);
-      if (native)
-        return runNativeCommand(native, args, config, typedGlobals);
-      const tool = tools.get(command);
-      if (!tool) {
-        return cliInvocationResult({
-          ok: false,
-          code: "NOT_FOUND",
-          details: { message: `Unknown command "${command}"` }
-        }, command, config);
-      }
-      let result;
-      try {
-        result = await runTool(tool, args);
-      } catch (error) {
-        result = toolResultFromError(error);
-      }
-      return cliInvocationResult(result, command, config);
-    }
-  };
-}
-var IN_PROCESS_RUN_OPTIONS = Object.freeze({
-  json: false,
-  wait: false,
-  quiet: true,
-  dryRun: false,
-  help: false
-});
-async function runNativeCommand(definition, args, config, globals) {
-  let out = "";
-  let err = "";
-  const result = await executeCliCommand(definition, args, IN_PROCESS_RUN_OPTIONS, {
-    stdout: (text) => {
-      out += text;
-    },
-    stderr: (text) => {
-      err += text;
-    }
-  }, config.coerceJsonArgs ?? true, globals);
-  let invocation = cliInvocationResult(result, definition.name, config);
-  if (invocation.ok) {
-    try {
-      invocation = {
-        ...invocation,
-        exitCode: cliCommandSuccessExitCode(definition, result.ok ? result.data : undefined)
-      };
-    } catch (error) {
-      invocation = cliInvocationResult(toolResultFromError(error), definition.name, config);
-    }
-  }
-  if (out === "" && err === "")
-    return invocation;
-  return {
-    ...invocation,
-    written: { ...out !== "" && { stdout: out }, ...err !== "" && { stderr: err } }
-  };
-}
-function buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, assertShape) {
-  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 descriptor = applyCliPresentationPolicy(mountable.name, managedCliDescriptor(mountable), config);
-    assertShape?.(mountable.name, descriptor, help.has(mountable.name), config.passthrough?.[mountable.name], applicationGlobalNames);
-    tools.set(mountable.name, mountable);
-    help.set(mountable.name, descriptor);
-  }
-  assertCliPoliciesResolved(help, config);
-  return { tools, help };
-}
-function managedCliDescriptor(tool) {
-  return {
-    description: tool.method.desc,
-    argumentSchema: tool.argumentSchema,
-    presentationSchema: tool.presentationSchema
-  };
-}
-
-// src/tools/cli-view.ts
-var ABSENT = "(absent)";
-function selectRecords(data) {
-  if (Array.isArray(data))
-    return data;
-  if (isRecord(data)) {
-    const arrays = Object.entries(data).filter(([, value]) => Array.isArray(value));
-    const only = arrays[0];
-    if (arrays.length === 1 && only && Array.isArray(only[1]))
-      return only[1];
-    if (arrays.length > 1) {
-      throw new CliArgumentError(`an aggregate needs one collection, but the result carries several: ${arrays.map(([key]) => key).join(", ")} — name the shape you want with jq instead`);
-    }
-  }
-  throw new CliArgumentError("an aggregate needs a collection; this result is not one");
-}
-function readField(record, path) {
-  let current = record;
-  for (const segment of path) {
-    if (!isRecord(current))
-      return;
-    current = current[segment];
-  }
-  return current;
-}
-function fieldPath(field) {
-  const path = field.split(".");
-  if (path.some((segment) => segment.length === 0 || isUnsafeKey(segment))) {
-    throw new CliArgumentError(`"${field}" is not a readable field path`);
-  }
-  return path;
-}
-function availableFields(records) {
-  const keys = new Set;
-  for (const record of records) {
-    if (isRecord(record))
-      for (const key of Object.keys(record))
-        keys.add(key);
-  }
-  return [...keys].sort();
-}
-function assertFieldPresent(records, field) {
-  const path = fieldPath(field);
-  const present = records.some((record) => readField(record, path) !== undefined);
-  if (!present) {
-    const available = availableFields(records);
-    throw new CliArgumentError(`no record carries the field "${field}"${available.length > 0 ? ` — available: ${available.join(", ")}` : ""}`);
-  }
-  return path;
-}
-function groupKey(value) {
-  if (value === undefined)
-    return ABSENT;
-  if (value === null)
-    return "null";
-  if (typeof value === "object")
-    return JSON.stringify(value);
-  return String(value);
-}
-function ordered(totals, top) {
-  const entries = [...totals].sort(([leftKey, left], [rightKey, right]) => right === left ? leftKey.localeCompare(rightKey) : right - left);
-  const sliced = top === undefined ? entries : entries.slice(0, top);
-  return Object.fromEntries(sliced);
-}
-function numericValue(value, field) {
-  if (value === undefined || value === null)
-    return;
-  if (typeof value === "number" && Number.isFinite(value))
-    return value;
-  if (typeof value === "bigint")
-    return Number(value);
-  throw new CliArgumentError(`--sum ${field}: "${groupKey(value)}" is not a number`);
-}
-function renderTable(records, fields) {
-  const paths = fields.map((field) => assertFieldPresent(records, field));
-  const cell = (value) => {
-    if (value === undefined)
-      return "";
-    if (value === null)
-      return "null";
-    if (typeof value === "object")
-      return JSON.stringify(value);
-    return String(value);
-  };
-  const rows = records.map((record) => paths.map((path) => cell(readField(record, path))));
-  const widths = fields.map((field, column) => Math.max(field.length, ...rows.map((row) => row[column]?.length ?? 0)));
-  const line = (cells) => cells.map((value, column) => value.padEnd(widths[column] ?? value.length)).join("  ").trimEnd();
-  return `${[line(fields), line(widths.map((width) => "-".repeat(width))), ...rows.map(line)].join(`
-`)}
-`;
-}
-function compareFieldValues(left, right) {
-  if (left === undefined || left === null)
-    return right === undefined || right === null ? 0 : 1;
-  if (right === undefined || right === null)
-    return -1;
-  if (typeof left === "number" && typeof right === "number")
-    return left - right;
-  if (typeof left === "bigint" || typeof right === "bigint") {
-    return Number(left) - Number(right);
-  }
-  return groupKey(left).localeCompare(groupKey(right));
-}
-function renderRecords(records, view) {
-  let selected = [...records];
-  if (view.sort !== undefined) {
-    const path = assertFieldPresent(records, view.sort);
-    const direction = view.ascending ? 1 : -1;
-    selected.sort((left, right) => {
-      const order = compareFieldValues(readField(left, path), readField(right, path));
-      const absent = readField(left, path) === undefined || readField(right, path) === undefined;
-      return absent ? order : order * direction;
-    });
-  }
-  if (view.top !== undefined)
-    selected = selected.slice(0, view.top);
-  return view.table ? { kind: "text", text: renderTable(selected, view.table) } : { kind: "json", data: selected };
-}
-function renderCliView(data, view) {
-  const records = selectRecords(data);
-  if (view.kind === "records")
-    return renderRecords(records, view);
-  if (view.kind === "count") {
-    const path2 = assertFieldPresent(records, view.field);
-    const totals2 = new Map;
-    for (const record of records) {
-      const key = groupKey(readField(record, path2));
-      totals2.set(key, (totals2.get(key) ?? 0) + 1);
-    }
-    return { kind: "json", data: ordered(totals2, view.top) };
-  }
-  const path = assertFieldPresent(records, view.field);
-  if (view.by === undefined) {
-    let total = 0;
-    for (const record of records)
-      total += numericValue(readField(record, path), view.field) ?? 0;
-    return { kind: "json", data: total };
-  }
-  const byPath = assertFieldPresent(records, view.by);
-  const totals = new Map;
-  for (const record of records) {
-    const key = groupKey(readField(record, byPath));
-    totals.set(key, (totals.get(key) ?? 0) + (numericValue(readField(record, path), view.field) ?? 0));
-  }
-  return { kind: "json", data: ordered(totals, view.top) };
-}
-
-// src/tools/wait-core.ts
-var DEFAULT_BACKOFF = [2, 3, 5, 5, 8, 10];
-var DEFAULT_TIMEOUT = 600;
-
-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 now = params.nowFn ?? (() => performance.now());
-  const startedAt = now();
-  const deadline = startedAt + timeoutSec * 1000;
-  let last;
-  for (let attempt = 0;; attempt++) {
-    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 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(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) => {
-      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,
-    signal: params.signal
-  });
-  if (timedOut) {
-    return {
-      ok: false,
-      code: "TIMEOUT",
-      details: { message: `Timed out after ${timeoutSec}s waiting for "${wait.tool}"` }
-    };
-  }
-  if (state === failedState && state.ok)
-    return waitFailure(wait.tool, state.data);
-  return state;
-}
-
-// src/tools/cli.ts
-import { writeSync } from "node:fs";
-import { basename, resolve } from "node:path";
-
-// src/internal/secure-fetch.ts
-import { lookup } from "node:dns/promises";
-import { request as httpRequest } from "node:http";
-import { request as httpsRequest } from "node:https";
-import { isIP } from "node:net";
-var NUMERIC_HOST = /^(0x[0-9a-f]+|[0-9.]+)$/i;
-var MAX_REDIRECTS = 5;
-function assertHttpUrl(url) {
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error(`refusing to fetch a non-http(s) URL (${url.protocol})`);
-  }
-}
-function mappedIpv4FromIpv6(ip) {
-  const rest = ip.startsWith("::ffff:") ? ip.slice("::ffff:".length) : ip.startsWith("0:0:0:0:0:ffff:") ? ip.slice("0:0:0:0:0:ffff:".length) : null;
-  if (rest === null)
-    return null;
-  if (isIP(rest) === 4)
-    return rest;
-  const [hiRaw, loRaw, extra] = rest.split(":");
-  if (hiRaw === undefined || loRaw === undefined || extra !== undefined)
-    return null;
-  if (!/^[0-9a-f]{1,4}$/i.test(hiRaw) || !/^[0-9a-f]{1,4}$/i.test(loRaw))
-    return null;
-  const hi = Number.parseInt(hiRaw, 16);
-  const lo = Number.parseInt(loRaw, 16);
-  return [hi >> 8, hi & 255, lo >> 8, lo & 255].join(".");
-}
-function ipv6Words(ip) {
-  const halves = ip.toLowerCase().split("::");
-  if (halves.length > 2)
-    return null;
-  const head = halves[0] ? halves[0].split(":") : [];
-  const tail = halves[1] ? halves[1].split(":") : [];
-  const missing = 8 - head.length - tail.length;
-  if (halves.length === 1 && missing !== 0 || missing < 0)
-    return null;
-  const parts = halves.length === 2 ? [...head, ...Array(missing).fill("0"), ...tail] : head;
-  if (parts.length !== 8)
-    return null;
-  const words = [];
-  for (const part of parts) {
-    if (!/^[0-9a-f]{1,4}$/i.test(part))
-      return null;
-    words.push(Number.parseInt(part, 16));
-  }
-  return words;
-}
-function isPrivateIp(ip) {
-  const normalized = ip.replace(/^\[|\]$/g, "");
-  const family = isIP(normalized);
-  if (family === 4) {
-    const [a, b] = normalized.split(".").map(Number);
-    if (a === undefined || b === undefined)
-      return true;
-    const value = normalized.split(".").map(Number).reduce((total, octet) => total * 256 + octet, 0);
-    const inCidr = (base, prefix) => {
-      const baseValue = base.split(".").map(Number).reduce((total, octet) => total * 256 + octet, 0);
-      const size = 2 ** (32 - prefix);
-      return value >= baseValue && value < baseValue + size;
-    };
-    const blockedRanges = [
-      ["0.0.0.0", 8],
-      ["10.0.0.0", 8],
-      ["100.64.0.0", 10],
-      ["127.0.0.0", 8],
-      ["169.254.0.0", 16],
-      ["172.16.0.0", 12],
-      ["192.0.0.0", 24],
-      ["192.0.2.0", 24],
-      ["192.31.196.0", 24],
-      ["192.52.193.0", 24],
-      ["192.88.99.0", 24],
-      ["192.168.0.0", 16],
-      ["192.175.48.0", 24],
-      ["198.18.0.0", 15],
-      ["198.51.100.0", 24],
-      ["203.0.113.0", 24],
-      ["224.0.0.0", 4],
-      ["240.0.0.0", 4]
-    ];
-    return blockedRanges.some(([base, prefix]) => inCidr(base, prefix));
-  }
-  if (family === 6) {
-    const lower = normalized.toLowerCase();
-    const mapped = mappedIpv4FromIpv6(lower);
-    if (mapped)
-      return isPrivateIp(mapped);
-    const words = ipv6Words(lower);
-    if (!words)
-      return true;
-    const [first, second, third] = words;
-    if (first === undefined || second === undefined || third === undefined)
-      return true;
-    return first === 0 || first === 100 && second === 65435 && third === 1 || first === 256 && second === 0 || first === 8193 && (second <= 511 || second === 3512) || first === 8194 || first === 16383 || first === 24320 || (first & 65024) === 64512 || (first & 65472) === 65152 || (first & 65280) === 65280;
-  }
-  return false;
-}
-function raceWithAbort(promise, signal) {
-  if (signal.aborted) {
-    promise.catch(() => {
-      return;
-    });
-    return Promise.reject(signal.reason ?? new Error("aborted"));
-  }
-  return new Promise((resolve, reject) => {
-    const onAbort = () => reject(signal.reason ?? new Error("aborted"));
-    signal.addEventListener("abort", onAbort, { once: true });
-    promise.then((value) => {
-      signal.removeEventListener("abort", onAbort);
-      resolve(value);
-    }, (error) => {
-      signal.removeEventListener("abort", onAbort);
-      reject(error);
-    });
-  });
-}
-async function assertPublicUrl(url, signal) {
-  await resolvePublicAddress(url, signal);
-}
-async function fetchGuarded(start, allowPrivate, options = {}) {
-  const timeoutMs = options.timeoutMs ?? 15000;
-  const bodyTimeoutMs = options.bodyTimeoutMs ?? 120000;
-  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-    throw new Error("timeoutMs must be positive");
-  }
-  if (!Number.isFinite(bodyTimeoutMs) || bodyTimeoutMs <= 0) {
-    throw new Error("bodyTimeoutMs must be positive");
-  }
-  const controller = new AbortController;
-  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
-  const headerTimer = setTimeout(() => {
-    controller.abort(new Error(`fetch did not produce response headers within ${timeoutMs}ms`));
-  }, timeoutMs);
-  headerTimer.unref?.();
-  let settled = false;
-  try {
-    let url = start;
-    for (let hop = 0;hop <= MAX_REDIRECTS; hop++) {
-      if (allowPrivate)
-        assertHttpUrl(url);
-      else
-        await assertPublicUrl(url, signal);
-      const res = await fetch(url, { redirect: "manual", signal });
-      const location = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
-      if (location === null) {
-        settled = true;
-        clearTimeout(headerTimer);
-        const bodyTimer = setTimeout(() => {
-          controller.abort(new Error(`fetch body was not consumed within ${bodyTimeoutMs}ms`));
-        }, bodyTimeoutMs);
-        bodyTimer.unref?.();
-        return res;
-      }
-      await res.body?.cancel();
-      url = new URL(location, url);
-    }
-    throw new Error("too many redirects");
-  } finally {
-    if (!settled)
-      clearTimeout(headerTimer);
-  }
-}
-
-class PrivateAddressRefusal extends Error {
-  name = "PrivateAddressRefusal";
-}
-async function resolvePublicAddress(url, signal) {
-  assertHttpUrl(url);
-  const host = url.hostname.replace(/^\[|\]$/g, "");
-  if (!host)
-    throw new Error("refusing to fetch a URL with no host");
-  const ipFamily = isIP(host);
-  if (ipFamily) {
-    if (isPrivateIp(host))
-      throw new PrivateAddressRefusal("refusing to fetch a private address");
-    return { address: host, family: ipFamily === 6 ? 6 : 4 };
-  }
-  if (NUMERIC_HOST.test(host)) {
-    throw new PrivateAddressRefusal("refusing to fetch a non-canonical numeric host");
-  }
-  if (host === "localhost" || host.endsWith(".local") || host.endsWith(".internal")) {
-    throw new PrivateAddressRefusal("refusing to fetch an internal host");
-  }
-  const pending = lookup(host, { all: true });
-  const records = signal ? await raceWithAbort(pending, signal) : await pending;
-  for (const record2 of records) {
-    if (isPrivateIp(record2.address)) {
-      throw new PrivateAddressRefusal("refusing to fetch a host that resolves to a private address");
-    }
-  }
-  const record = records[0];
-  if (!record)
-    throw new Error("public hostname resolved to no addresses");
-  return { address: record.address, family: record.family === 6 ? 6 : 4 };
-}
-async function fetchPinnedDocument(start, options) {
-  if (!Number.isInteger(options.maxBytes) || options.maxBytes < 1) {
-    throw new Error("maxBytes must be a positive integer");
-  }
-  if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
-    throw new Error("timeoutMs must be positive");
-  }
-  let url = start;
-  const maxRedirects = options.maxRedirects ?? MAX_REDIRECTS;
-  if (!Number.isInteger(maxRedirects) || maxRedirects < 0) {
-    throw new Error("maxRedirects must be a non-negative integer");
-  }
-  const signal = AbortSignal.timeout(options.timeoutMs);
-  for (let hop = 0;hop <= maxRedirects; hop++) {
-    if (options.requireHttps && url.protocol !== "https:") {
-      throw new Error("document URL and every redirect must use https");
-    }
-    if (url.username || url.password) {
-      throw new Error("document URL cannot contain credentials");
-    }
-    const resolved = await resolvePublicAddress(url, signal);
-    const transport = url.protocol === "https:" ? httpsRequest : httpRequest;
-    const response = await new Promise((resolve, reject) => {
-      const request = transport({
-        protocol: url.protocol,
-        hostname: resolved.address,
-        family: resolved.family,
-        port: url.port || undefined,
-        path: `${url.pathname}${url.search}`,
-        method: "GET",
-        signal,
-        servername: url.hostname,
-        headers: {
-          host: url.host,
-          accept: "application/json",
-          ...options.headers
-        }
-      }, (incoming) => {
-        const headers = new Headers;
-        for (const [name, value] of Object.entries(incoming.headers)) {
-          if (Array.isArray(value)) {
-            for (const item of value)
-              headers.append(name, item);
-          } else if (value !== undefined) {
-            headers.set(name, value);
-          }
-        }
-        const chunks = [];
-        let total = 0;
-        incoming.on("data", (chunk) => {
-          total += chunk.byteLength;
-          if (total > options.maxBytes) {
-            incoming.destroy(new Error("response body exceeds configured byte limit"));
-            return;
-          }
-          chunks.push(chunk);
-        });
-        incoming.once("error", reject);
-        incoming.once("end", () => {
-          const body = new Uint8Array(total);
-          let offset = 0;
-          for (const chunk of chunks) {
-            body.set(chunk, offset);
-            offset += chunk.byteLength;
-          }
-          resolve({ status: incoming.statusCode ?? 0, headers, body, url });
-        });
-      });
-      request.once("error", reject);
-      request.end();
-    });
-    if (response.status < 300 || response.status >= 400)
-      return response;
-    const location = response.headers.get("location");
-    if (!location)
-      return response;
-    url = new URL(location, url);
-  }
-  throw new Error("too many redirects");
-}
-async function readCapped(res, max) {
-  const reader = res.body?.getReader();
-  if (!reader)
-    return Buffer.alloc(0);
-  const chunks = [];
-  let total = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done)
-        break;
-      total += value.length;
-      if (total > max) {
-        await reader.cancel();
-        return null;
-      }
-      chunks.push(value);
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  return Buffer.concat(chunks);
-}
-
-// src/internal/write-download.ts
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
-async function writeDownload(root, target, data) {
-  if (!isWithinDir(root, target)) {
-    throw new Error("download name escapes the output dir");
-  }
-  await mkdir(dirname(target), { recursive: true });
-  await writeFile(target, data);
-}
-
-// src/tools/cli.ts
-var GLOBAL_OPTIONS = [
-  ["--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"],
-  ["--quiet", "Suppress non-essential stderr output"],
-  ["--dry-run", "Print the resolved call without executing it"],
-  ["--help, -h", "Show help for a command"],
-  ["--help <text>", "List only the commands matching a substring"],
-  ["--count-by <field>", "Count records per distinct value of a field"],
-  ["--sum <field>", "Total a numeric field, optionally grouped by --by"],
-  ["--sort <field>", "Order the records by a field, largest first"],
-  ["--ascending", "Flip --sort to smallest first"],
-  ["--top <n>", "Keep the n leading entries of the view asked for"],
-  ["--table <a,b>", "Render the named fields as an aligned table"]
-];
-async function readPipedStdin() {
-  if (process.stdin.isTTY)
-    return null;
-  const chunks = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
-  }
-  const text = Buffer.concat(chunks).toString("utf8").trim();
-  return text.length > 0 ? text : null;
-}
-function typeLabel(schema) {
-  if (Array.isArray(schema.enum))
-    return schema.enum.join("|");
-  if (schema.type === "array")
-    return "value…";
-  if (typeof schema.type === "string")
-    return schema.type;
-  return "value";
-}
-function padRight(text, width) {
-  return text.length >= width ? text : text + " ".repeat(width - text.length);
-}
-function summarize(desc) {
-  const firstLine = desc.split(`
-`)[0]?.trim() ?? "";
-  const firstSentence = firstLine.split(". ")[0]?.trim() ?? firstLine;
-  const max = 72;
-  return firstSentence.length > max ? `${firstSentence.slice(0, max - 1).trimEnd()}…` : firstSentence;
-}
-function looseCoerceValue(value) {
-  if (Array.isArray(value))
-    return value.map(looseCoerceValue);
-  if (typeof value !== "string")
-    return value;
-  if (value === "true")
-    return true;
-  if (value === "false")
-    return false;
-  const n = Number(value);
-  return value.trim() !== "" && !Number.isNaN(n) ? n : value;
-}
-function passthroughBase(value) {
-  if (isRecord(value))
-    return value;
-  if (typeof value === "string") {
-    try {
-      const parsed = safeJsonParse(value);
-      if (isRecord(parsed))
-        return parsed;
-    } catch {}
-  }
-  return;
-}
-function collectPassthrough(toolArgs, field, knownKeys) {
-  const known = new Set(knownKeys);
-  const bag = {};
-  for (const key of Object.keys(toolArgs)) {
-    if (key === field || known.has(key))
-      continue;
-    bag[key] = looseCoerceValue(toolArgs[key]);
-    delete toolArgs[key];
-  }
-  if (Object.keys(bag).length === 0)
-    return;
-  const base = passthroughBase(toolArgs[field]);
-  toolArgs[field] = base ? { ...base, ...bag } : bag;
-}
-function applicationOptionLines(fields) {
-  if (fields.length === 0)
-    return [];
-  const labels = new Map(fields.map((field) => [field.name, `--${field.name} <${typeLabel(field.schema)}>`]));
-  const width = Math.max(...fields.map((field) => labels.get(field.name)?.length ?? 0));
-  return [
-    "",
-    "Application options:",
-    ...fields.map((field) => `  ${padRight(labels.get(field.name) ?? `--${field.name}`, width)}  ${field.description ?? ""}`.trimEnd())
-  ];
-}
-function filterCommands(commands, filter) {
-  const needle = filter.toLowerCase();
-  return new Map([...commands].filter(([command, descriptor]) => command.toLowerCase().includes(needle) || descriptor.description.toLowerCase().includes(needle)));
-}
-function renderTopHelp(input) {
-  const { name, version, defaultCommand } = input;
-  const commands = input.filter === undefined ? input.commands : filterCommands(input.commands, input.filter);
-  const lines = [
-    `${name} ${version}`,
-    "",
-    `Usage: ${name} ${defaultCommand ? "[command]" : "<command>"} [args] [--flags]`,
-    "",
-    input.filter === undefined ? "Commands:" : `Commands matching "${input.filter}" (${commands.size} of ${input.commands.size}):`
-  ];
-  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)}${command === defaultCommand ? " (default)" : ""}`);
-  }
-  if (input.unavailable !== undefined) {
-    lines.push("", `Managed commands are unavailable: ${input.unavailable}`);
-  }
-  if (input.filter !== undefined) {
-    lines.push("", `Run "${name} <command> --help" for command-specific flags.`);
-    return `${lines.join(`
-`)}
-`;
-  }
-  lines.push("", "Global options:");
-  const optWidth = Math.max(...GLOBAL_OPTIONS.map(([flag]) => flag.length));
-  for (const [flag, desc] of GLOBAL_OPTIONS)
-    lines.push(`  ${padRight(flag, optWidth)}  ${desc}`);
-  lines.push(...applicationOptionLines(input.applicationOptions));
-  lines.push("", `Run "${name} <command> --help" for command-specific flags.`);
-  return `${lines.join(`
-`)}
-`;
-}
-function renderCommandHelp(name, command, descriptor, applicationOptions = []) {
-  const fields = jsonSchemaFields(descriptor.presentationSchema);
-  const fieldsByName = new Map(fields.map((field) => [field.name, field]));
-  const kinds = describeSchemaFields(descriptor.argumentSchema);
-  const positionals = [];
-  const positionalNames = descriptor.positionals ?? [...kinds].filter(([, info]) => info.kind !== "boolean").map(([fieldName]) => fieldName);
-  for (const fieldName of positionalNames) {
-    const field = fieldsByName.get(fieldName);
-    if (field)
-      positionals.push(field);
-  }
-  const variadicTail = descriptor.positionals !== undefined && kinds.get(descriptor.positionals[descriptor.positionals.length - 1] ?? "")?.kind === "array" ? descriptor.positionals[descriptor.positionals.length - 1] : undefined;
-  const positionalSyntax = new Map(positionals.map((field) => {
-    const label = field.name === variadicTail ? `${field.name}...` : field.name;
-    return [field.name, field.required ? `<${label}>` : `[${label}]`];
-  }));
-  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 labels = new Map(fields.map((field) => {
-      const positional = positionalSyntax.get(field.name);
-      const alias = descriptor.aliases.get(field.name);
-      const option = alias ? `-${alias}, --${field.name}` : `--${field.name}`;
-      return [field.name, positional ? `${positional} | ${option}` : option];
-    }));
-    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}` : "";
-      const label = labels.get(f.name) ?? `--${f.name}`;
-      lines.push(`  ${padRight(label, width)}  <${typeLabel(f.schema)}>${req}${desc}`);
-    }
-    lines.push("");
-  }
-  const applicationLines = applicationOptionLines(applicationOptions);
-  if (applicationLines.length > 0)
-    lines.push(...applicationLines.slice(1), "");
-  return `${lines.join(`
-`)}
-`;
-}
-function nativeDescriptor(definition) {
-  return {
-    description: definition.description,
-    argumentSchema: definition.input,
-    presentationSchema: cliCommandPresentationSchema(definition)
-  };
-}
-function assertCommandShape(name, descriptor, exists, passthroughField, applicationGlobals = new Set) {
-  assertUniqueToolName(name, exists, "CLI command");
-  if (name === "help" || name === "version") {
-    throw new Error(`[stitchkit] CLI command "${name}" is reserved`);
-  }
-  const fieldNames = jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name);
-  const conflicting = fieldNames.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(", ")}`);
-  }
-  const shadowed = fieldNames.filter((field) => applicationGlobals.has(field));
-  if (shadowed.length > 0) {
-    throw new Error(`[stitchkit] CLI command "${name}" declares field(s) shadowed by application global options: ${shadowed.join(", ")}`);
-  }
-  if (passthroughField !== undefined && descriptor.aliases.has(passthroughField)) {
-    throw new Error(`[stitchkit] CLI command "${name}" cannot alias passthrough field "${passthroughField}"`);
-  }
-}
-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),
-      optionAliases: new Map([...descriptor.aliases].map(([field, alias]) => [alias, field])),
-      positionals: descriptor.positionals
-    });
-  } 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) {
-      if (descriptor.positionals === undefined) {
-        toolArgs[firstUnset.name] = piped;
-      } else {
-        const stdinArgs = parseCliArgs([`--${firstUnset.name}`, piped], descriptor.argumentSchema);
-        toolArgs[firstUnset.name] = stdinArgs.toolArgs[firstUnset.name];
-      }
-    }
-  }
-  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);
-  let succeeded = true;
-  for (const file of files) {
-    try {
-      const res = await fetchGuarded(new URL(file.url), allowPrivate, { timeoutMs });
-      if (!res.ok)
-        throw new Error(`HTTP ${res.status}`);
-      const buffer = await readCapped(res, maxBytes);
-      if (!buffer)
-        throw new Error(`file exceeds the ${maxBytes}-byte cap`);
-      const target = resolve(root, basename(file.name));
-      await writeDownload(root, target, buffer);
-      if (!quiet)
-        stderr(`saved ${target} (${(buffer.length / 1024).toFixed(0)}KB)
-`);
-    } catch (err) {
-      succeeded = false;
-      stderr(`failed to download ${file.url}: ${err instanceof Error ? err.message : String(err)}
-`);
-    }
-  }
-  return succeeded;
-}
-async function createCli(config) {
-  let pendingWrite;
-  let writeFailed = false;
-  const writeFd = (fd, text) => {
-    const bytes = Buffer.from(text, "utf8");
-    let offset = 0;
-    while (offset < bytes.length) {
-      try {
-        offset += writeSync(fd, bytes, offset, bytes.length - offset);
-      } catch (error) {
-        if (isRecord(error) && error.code === "EAGAIN") {
-          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
-          continue;
-        }
-        const stream = fd === 1 ? process.stdout : process.stderr;
-        const rest = bytes.subarray(offset);
-        pendingWrite = new Promise((resolve2) => {
-          stream.write(rest, (failure) => {
-            if (failure)
-              writeFailed = true;
-            resolve2();
-          });
-        });
-        return;
-      }
-    }
-  };
-  const stdout = config.stdout ?? ((text) => writeFd(1, text));
-  const stderr = config.stderr ?? ((text) => writeFd(2, text));
-  const exit = config.exit ?? ((code) => {
-    if (pendingWrite === undefined)
-      process.exit(code);
-    else
-      pendingWrite.then(() => process.exit(writeFailed ? 1 : code));
-  });
-  const argv = config.argv ?? process.argv.slice(2);
-  const readStdin = config.stdin ?? readPipedStdin;
-  if (config.auth !== undefined && config.resolveAuth !== undefined) {
-    throw new Error("[stitchkit] createCli: use either auth or resolveAuth, not both");
-  }
-  const applicationOptions = config.globalOptions ? jsonSchemaFields(buildToolPresentationSchema({
-    inputSchema: config.globalOptions,
-    unrepresentable: "any"
-  })) : [];
-  const applicationGlobalNames = new Set(applicationOptions.map((field) => field.name));
-  for (const name of applicationGlobalNames) {
-    if (RESERVED_CLI_OPTIONS.has(name)) {
-      throw new Error(`[stitchkit] CLI global option "--${name}" is reserved by the framework`);
-    }
-  }
-  const nativeCommands = new Map;
-  const nativeHelp = new Map;
-  for (const definition of config.commands ?? []) {
-    const descriptor2 = applyCliPresentationPolicy(definition.name, nativeDescriptor(definition), config);
-    assertCommandShape(definition.name, descriptor2, nativeCommands.has(definition.name), config.passthrough?.[definition.name], applicationGlobalNames);
-    nativeCommands.set(definition.name, definition);
-    nativeHelp.set(definition.name, descriptor2);
-  }
-  let globals;
-  let routableArgv;
-  try {
-    const lifted = extractCliGlobalOptions(argv, config.globalOptions);
-    globals = lifted.globals;
-    routableArgv = lifted.argv;
-  } catch (error) {
-    if (!(error instanceof CliArgumentError))
-      throw error;
-    stderr(`${error.message}
-`);
-    return exit(2);
-  }
-  const typedGlobals = globals;
-  const route = routeCliArgv(routableArgv, config.defaultCommand);
-  if (route.error) {
-    stderr(`${route.error}
-`);
-    return exit(2);
-  }
-  const { command, commandArgv } = route;
-  if (route.version || command === "--version" || command === "version") {
-    stdout(`${config.name} ${config.version}
-`);
-    return exit(0);
-  }
-  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, applicationOptions));
-      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, applicationOptions));
-      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, globals);
-    const emission = prepareCliCommandEmission(native, result2, options2);
-    let emittedExitCode;
-    if (emission.result.ok && emission.presentation !== undefined) {
-      stdout(emission.presentation);
-      emittedExitCode = 0;
-    } else {
-      emittedExitCode = emitResult(emission.result, { stdout, stderr }, {
-        json: options2.json,
-        toolName: command,
-        errorHint: config.errorHint,
-        exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
-      });
-    }
-    return exit(emission.result.ok ? emission.successExitCode : emittedExitCode);
-  }
-  let authPromise;
-  const resolveIdentity = () => {
-    authPromise ??= (async () => config.resolveAuth ? await config.resolveAuth(typedGlobals) : await config.auth)();
-    return authPromise;
-  };
-  const dynamicSurface = typeof config.services === "function" || typeof config.runtimeTools === "function";
-  const buildManagedSurface = async (forExecution) => {
-    let auth;
-    if (dynamicSurface || forExecution) {
-      try {
-        auth = await resolveIdentity();
-      } catch (error) {
-        const failure = toolResultFromError(error);
-        const normalized = toolErrorFromResult(failure);
-        return {
-          resolved: false,
-          failure,
-          reason: `${normalized.code}: ${normalized.message}`,
-          help: new Map(nativeHelp)
-        };
-      }
-    }
-    const { tools, help } = buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, assertCommandShape);
-    return { resolved: true, auth, help, tools };
-  };
-  const topLevelHelp = route.topLevelHelp || command === undefined || command === "help" || command === "--help" || command === "-h" || command.startsWith("--help=") && !isReservedBoolWord(command.slice("--help=".length));
-  const managed = await buildManagedSurface(!topLevelHelp && !helpRequested);
-  if (topLevelHelp) {
-    const helpFilter = route.helpFilter ?? (command !== undefined ? commandArgv[0] : undefined);
-    const filter = helpFilter !== undefined && !helpFilter.startsWith("-") ? helpFilter : undefined;
-    if (filter !== undefined && filterCommands(managed.help, filter).size === 0) {
-      stderr(`no command matches "${filter}" (${managed.help.size} available)
-` + (managed.resolved ? "" : `Managed commands are unavailable: ${managed.reason}
-`));
-      const codes = { ...DEFAULT_EXIT_CODES, ...config.exitCodes };
-      return exit(codes.NOT_FOUND ?? 4);
-    }
-    stdout(renderTopHelp({
-      name: config.name,
-      version: config.version,
-      commands: managed.help,
-      defaultCommand: config.defaultCommand,
-      applicationOptions,
-      ...filter !== undefined && { filter },
-      ...managed.resolved ? {} : { unavailable: managed.reason }
-    }));
-    return exit(0);
-  }
-  if (!managed.resolved) {
-    return exit(emitResult(managed.failure, { stdout, stderr }, {
-      json: beforeSeparator.includes("--json"),
-      toolName: command ?? config.name,
-      errorHint: config.errorHint,
-      exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
-    }));
-  }
-  const tool = managed.tools.get(command);
-  if (!tool) {
-    stderr(`Unknown command "${command}". Run "${config.name} --help" for the command list.
-`);
-    return exit(1);
-  }
-  const descriptor = managed.help.get(command);
-  if (!descriptor)
-    throw new Error("[stitchkit] managed CLI descriptor invariant failed");
-  if (helpRequested) {
-    stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
-    return exit(0);
-  }
-  const prepared = await prepareInvocation(command, commandArgv, descriptor, config, readStdin);
-  if (!prepared.ok) {
-    stderr(`${prepared.message}
-`);
-    return exit(2);
-  }
-  const { toolArgs, options } = prepared;
-  if (options.wait && !config.wait?.[command]) {
-    stderr(`--wait is not configured for command "${command}"
-`);
-    return exit(2);
-  }
-  if (options.waitTimeout !== undefined && !options.wait) {
-    stderr(`--wait-timeout requires --wait
-`);
-    return exit(2);
-  }
-  if (options.outputDir !== undefined && !config.download) {
-    stderr(`--output-dir is not configured for this CLI
-`);
-    return exit(2);
-  }
-  if (options.help) {
-    stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
-    return exit(0);
-  }
-  if (options.dryRun) {
-    stdout(`${JSON.stringify({ command, args: toolArgs }, null, 2)}
-`);
-    return exit(0);
-  }
-  const runTool = createToolRunner({
-    source: "cli",
-    context: { ...config.context?.(managed.auth, typedGlobals), signal: config.signal },
-    hooks: config.hooks,
-    lifecycle: config.lifecycle,
-    errorHint: config.errorHint,
-    coerceJsonArgs: config.coerceJsonArgs
-  });
-  let result;
-  try {
-    result = await runTool(tool, toolArgs);
-  } catch (err) {
-    result = toolResultFromError(err);
-  }
-  const waitConfig = config.wait?.[command];
-  if (options.wait && waitConfig) {
-    result = await pollUntilDone({
-      initial: result,
-      wait: waitConfig,
-      call: async (toolName, args) => {
-        const pollTool = managed.tools.get(toolName);
-        if (!pollTool) {
-          return {
-            ok: false,
-            code: "NOT_FOUND",
-            details: { message: `--wait: no command "${toolName}" to poll` }
-          };
-        }
-        return runTool(pollTool, args);
-      },
-      timeoutSec: options.waitTimeout,
-      onTick: options.quiet ? undefined : (attempt) => stderr(`waiting… (poll ${attempt})
-`),
-      signal: config.signal
-    });
-  }
-  let downloadsOk = true;
-  if (options.outputDir && result.ok && config.download) {
-    downloadsOk = await downloadResults(config.download(result.data), options.outputDir, stderr, options.quiet, config.allowPrivateDownloadHosts ?? false, config.maxDownloadBytes ?? DEFAULT_DOWNLOAD_MAX_BYTES, config.downloadTimeoutMs);
-  }
-  if (options.view && result.ok) {
-    let viewed;
-    try {
-      viewed = renderCliView(result.data, options.view);
-    } catch (error) {
-      if (!(error instanceof CliArgumentError))
-        throw error;
-      stderr(`${error.message}
-`);
-      return exit(2);
-    }
-    if (viewed.kind === "text") {
-      stdout(viewed.text);
-      return exit(downloadsOk ? 0 : 1);
-    }
-    result = { ...result, data: viewed.data };
-  }
-  const exitCode = emitResult(result, { stdout, stderr }, {
-    json: options.json,
-    toolName: command,
-    errorHint: config.errorHint,
-    exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
-  });
-  return exit(downloadsOk ? exitCode : 1);
-}
-
-export { WaitTimeoutError, runWaitOperation, fetchGuarded, PrivateAddressRefusal, fetchPinnedDocument, readCapped, routeCliArgv, CliArgumentError, parseCliArgs, extractCliGlobalOptions, defineCliCommand, DEFAULT_EXIT_CODES, cliExitCode, emitResult, cliInvocationResult, createCliInvoker, renderCliView, pollUntilDone, createCli };