stitchkit 0.118.1 → 0.120.0

package/dist/{index-w7jq3fz9.js → index-pq2m7t46.js}

@@ -14,36 +14,36 @@ import {
   objectShapeKeys,
   assertUniqueToolName,
   buildToolPresentationSchema
-} from "./index-rhzkndr5.js";
+} from "./index-x4p3kw1p.js";
 import {
   toolResultFromError,
   toolErrorFromResult
-} from "./index-v6vb5qx8.js";
+} from "./index-s3yxw6kt.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-htxh46ej.js";
+} from "./index-ycqhyars.js";
 import {
   writeContainedFile
-} from "./index-q968hy6y.js";
+} from "./index-e452syyh.js";
 import {
   openPinnedDirectory,
   isSafeEntryName,
   containedEntryMetadata
-} from "./index-arjmb6de.js";
+} from "./index-1jwsfkfz.js";
+import {
+  pollUntil
+} from "./index-bph35vpy.js";
 import {
   collectToolSurface
-} from "./index-86nbfysb.js";
+} from "./index-ff39f9dr.js";
 import {
   fetchGuarded,
   readCapped
-} from "./index-mgb7r8b8.js";
+} from "./index-jswst0h3.js";
 import {
   errnoOf
 } from "./index-jj9228tt.js";
-import {
-  sleep
-} from "./index-eemvahkc.js";
 import {
   isUnsafeKey,
   safeJsonParse
@@ -201,13 +201,15 @@ function emitPresentationFailure(result, failure, writers, opts) {
   }, writers, { json: opts.json, toolName: opts.toolName, exitCodes: opts.exitCodes });
 }
 
+// src/tools/cli/args-fields.ts
+import { z } from "zod";
+
 // src/tools/cli/argument-error.ts
 class CliArgumentError2 extends Error {
   name = "CliArgumentError";
 }
 
 // src/tools/cli/args-fields.ts
-import { z } from "zod";
 function appendCliOptionValue(raw, name, value, info) {
   const existing = raw.get(name);
   const repeatable = info?.kind === "array" || !name.includes(".") && info === undefined;
@@ -724,1287 +726,978 @@ function managedCliDescriptor(tool) {
   };
 }
 
-// src/tools/cli/args-route.ts
-function isOptionToken(token) {
-  return token.startsWith("--") || /^-[A-Za-z](?:=|$)/.test(token);
-}
-function looksLikeOption(token) {
-  return token.startsWith("--") || /^-[A-Za-z]/.test(token);
-}
-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 routeCliArgv2(argv, defaultCommand) {
-  if (defaultCommand === undefined) {
-    const [command, ...commandArgv] = argv;
-    const helpFilter = helpFilterFrom(command, commandArgv);
-    return {
-      command,
-      commandArgv,
-      topLevelHelp: false,
-      version: false,
-      ...helpFilter !== undefined && { helpFilter }
+// src/tools/cli/io.ts
+import { writeSync } from "node:fs";
+
+// src/tools/cli/stdin.ts
+function readPipedStdin(input = process.stdin) {
+  if (input.isTTY || input.readableEnded)
+    return Promise.resolve(null);
+  if (input.destroyed)
+    return Promise.reject(new Error("stdin closed before EOF"));
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    const cleanup = () => {
+      clearTimeout(timer);
+      input.pause();
+      input.off("data", onData);
+      input.off("end", onEnd);
+      input.off("error", onError);
+      input.off("close", onClose);
     };
-  }
-  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;
-      const next = argv[index];
-      if (option.value === undefined && next !== undefined && separateBoolValue(next) !== undefined) {
-        globals.push(next);
-        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 };
+    const onData = (chunk) => {
+      if (chunk.length === 0)
+        return;
+      clearTimeout(timer);
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    };
+    const onEnd = () => {
+      cleanup();
+      const text = Buffer.concat(chunks).toString("utf8").trim();
+      resolve(text.length > 0 ? text : null);
+    };
+    const onError = (error) => {
+      cleanup();
+      reject(error);
+    };
+    const onClose = () => onError(new Error("stdin closed before EOF"));
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve(null);
+    }, 250);
+    input.on("end", onEnd);
+    input.on("error", onError);
+    input.on("close", onClose);
+    input.on("data", onData);
+    input.resume();
+  });
+}
+
+// src/tools/cli/io.ts
+function createCliIo(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;
         }
-        if (value !== undefined)
-          globals.push(value);
-        index += value === undefined ? 1 : 2;
-      } else {
-        index += 1;
+        const stream = fd === 1 ? process.stdout : process.stderr;
+        const rest = bytes.subarray(offset);
+        pendingWrite = new Promise((resolve) => {
+          stream.write(rest, (failure) => {
+            if (failure)
+              writeFailed = true;
+            resolve();
+          });
+        });
+        return;
       }
-      continue;
     }
-    return {
-      command: defaultCommand,
-      commandArgv: [...globals, ...argv.slice(index)],
-      topLevelHelp: false,
-      version: false
-    };
-  }
-  return {
-    command: defaultCommand,
-    commandArgv: globals,
-    topLevelHelp: false,
-    version: false
   };
+  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 readStdin = config.stdin ?? readPipedStdin;
+  return { stdout, stderr, exit, readStdin };
 }
 
-// src/tools/cli/args.ts
-import { z as z2 } from "zod";
+// src/tools/cli/download.ts
+import { basename, resolve } from "node:path";
 
-// src/tools/cli/args-json.ts
-function cliFieldOption(option, fields) {
-  const json = option.inline && option.name.endsWith(":") && !fields.has(option.name);
-  const name = json ? option.name.slice(0, -1) : option.name;
-  return { name, json };
-}
-function appendCliFieldValue(raw, jsonFields, name, value, info, json) {
-  appendCliOptionValue(raw, name, value, json || jsonFields.has(name) ? { kind: "other" } : info);
-  if (json)
-    jsonFields.add(name);
-}
-function coerceCliFieldValue(info, values, label, json) {
-  if (!json)
-    return coerceField(info, values, label);
-  try {
-    return safeJsonParse(values[0] ?? "");
-  } catch (cause) {
-    throw new CliArgumentError2(`${label} expects valid JSON`, { cause });
+// src/internal/write-download.ts
+import path from "node:path";
+async function writeDownload(root, name, data) {
+  if (!isSafeEntryName(name) || path.basename(name) !== name) {
+    throw new Error("download name escapes the output dir");
   }
+  const parent = { handle: root, basename: name };
+  const metadata = await containedEntryMetadata(parent);
+  await writeContainedFile({
+    parent,
+    content: data,
+    replace: true,
+    ...metadata?.isFile() && { mode: metadata.mode }
+  });
 }
 
-// src/tools/cli/args-tokens.ts
-function readCliTokens(argv, fields, fieldFor, config) {
-  const options = {
-    json: false,
-    wait: false,
-    quiet: false,
-    dryRun: false,
-    help: false
-  };
-  const flags = new Map;
-  const jsonFields = new Set;
-  const literalBooleanFlags = new Set;
-  const frameworkFlags = new Map;
-  const viewFlags = new Map;
-  let ascending = false;
-  const positionals = [];
-  const pushFlag = (name, value, json = false) => {
-    appendCliFieldValue(flags, jsonFields, name, value, fieldFor(name), json);
-  };
-  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 || !looksLikeOption(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 CliArgumentError2(`Unknown option "${tok}"`);
-      const inline = match?.[2];
-      const info = fieldFor(field);
-      if (info?.kind === "boolean") {
-        const separate = inline === undefined ? separateBoolValue(argv[i + 1]) : undefined;
-        if (separate !== undefined)
-          i++;
-        pushFlag(field, inline ?? String(separate ?? true));
-        if (inline !== undefined)
-          parseReservedBool(field, inline);
-        literalBooleanFlags.add(field);
-        continue;
-      }
-      let value = inline;
-      if (value === undefined) {
-        const next = argv[i + 1];
-        if (next !== undefined && !isOptionToken(next)) {
-          value = next;
-          i++;
-        } else {
-          throw new CliArgumentError2(`--${field} requires a value`);
-        }
-      }
-      pushFlag(field, value);
-      continue;
-    }
-    const option = classifyLongOptionToken(tok);
-    if (!option)
-      throw new CliArgumentError2(`Unknown option "${tok}"`);
-    const { name, json } = cliFieldOption(option, fields);
-    let { value } = option;
-    if (name.length === 0)
-      throw new CliArgumentError2("Invalid empty option name");
-    if (json && RESERVED_CLI_OPTIONS.has(name)) {
-      throw new CliArgumentError2(`--${name} is a framework option and does not accept :=JSON`);
-    }
-    if (option.globalKind === "boolean") {
-      const separate = value === undefined ? separateBoolValue(argv[i + 1]) : undefined;
-      if (separate !== undefined)
-        i++;
-      if (name !== "help") {
-        appendCliOptionValue(frameworkFlags, name, value ?? String(separate ?? true), {
-          kind: "boolean"
-        });
-      }
-      const enabled = value === undefined ? separate ?? 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 = options.help || enabled;
-      continue;
-    }
-    if (option.globalKind === "value") {
-      const next = argv[i + 1];
-      value = value ?? next;
-      if (value === undefined || !option.inline && isOptionToken(value)) {
-        throw new CliArgumentError2(`--${name} requires a value`);
-      }
-      if (!option.inline)
-        i++;
-      appendCliOptionValue(frameworkFlags, name, value, { kind: "string" });
-      if (name === "wait-timeout") {
-        const timeout = Number(value);
-        if (!Number.isFinite(timeout) || timeout <= 0) {
-          throw new CliArgumentError2("--wait-timeout must be a positive number");
-        }
-        options.waitTimeout = timeout;
-      } else if (VIEW_OPTIONS.has(name)) {
-        viewFlags.set(name, value);
-      } else {
-        options.outputDir = value;
-      }
-      continue;
-    }
-    if (value === undefined && name.startsWith("no-") && fieldFor(name.slice(3))?.kind === "boolean") {
-      pushFlag(name.slice(3), "false");
-      literalBooleanFlags.add(name.slice(3));
-      continue;
-    }
-    const unsafeSegment = name.split(".").find(isUnsafeKey);
-    if (unsafeSegment !== undefined) {
-      throw new CliArgumentError2(`Unsafe option name "--${name}"`);
-    }
-    const info = fieldFor(name);
-    const rootName = name.split(".")[0] ?? name;
-    if (!fields.has(rootName) && !config.allowUnknown) {
-      throw new CliArgumentError2(`Unknown option "--${name}"`);
-    }
-    if (value === undefined) {
-      if (info?.kind === "boolean") {
-        const separate = separateBoolValue(argv[i + 1]);
-        if (separate !== undefined)
-          i++;
-        pushFlag(name, String(separate ?? true));
-        literalBooleanFlags.add(name);
-        continue;
-      }
-      const next = argv[i + 1];
-      if (next !== undefined && !isOptionToken(next)) {
-        value = next;
-        i++;
-      } else {
-        throw new CliArgumentError2(`--${name} requires a value`);
-      }
-    }
-    pushFlag(name, value, json);
-  }
-  return {
-    options,
-    flags,
-    jsonFields,
-    literalBooleanFlags,
-    viewFlags,
-    ascending,
-    positionals
-  };
-}
-
-// src/tools/cli/args-view.ts
-function resolveCliView(flags, ascending) {
-  if (flags.size === 0) {
-    if (ascending) {
-      throw new CliArgumentError2("--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 CliArgumentError2(`${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 CliArgumentError2("--top must be a positive whole number");
-    }
-  }
-  const sort = flags.get("sort");
-  if (table !== undefined || sort !== undefined) {
-    if (countBy !== undefined || sum !== undefined) {
-      throw new CliArgumentError2(`${table !== undefined ? "--table" : "--sort"} lists records; --count-by and --sum aggregate them — pass one`);
-    }
-    if (by !== undefined) {
-      throw new CliArgumentError2("--by groups a view; a record view orders with --sort");
-    }
-    if (top !== undefined && sort === undefined) {
-      throw new CliArgumentError2("--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 CliArgumentError2("--table needs at least one field");
-    }
-    return {
-      kind: "records",
-      ...sort !== undefined && { sort },
-      ...ascending && { ascending },
-      ...top !== undefined && { top },
-      ...fields && { table: fields }
-    };
-  }
-  if (ascending) {
-    throw new CliArgumentError2("--ascending orders a record view; pass --sort with it");
-  }
-  if (sum !== undefined) {
-    if (top !== undefined && by === undefined) {
-      throw new CliArgumentError2("--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 CliArgumentError2("--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 CliArgumentError2("--by groups a view; pass --count-by, --sum or --top with it");
-    }
-    return { kind: "count", field: by, top };
-  }
-  throw new CliArgumentError2("--top needs --sort, --by, --count-by or --sum to rank");
-}
-
-// src/tools/cli/args.ts
-function buildToolArgs(tokens, fields, fieldFor, declaredPositionals, allowUnknown) {
-  const { flags, jsonFields, literalBooleanFlags, positionals } = tokens;
-  if (declaredPositionals === undefined && positionals.length > 0) {
-    const arrayFlag = [...flags.keys()].find((key) => fieldFor(key)?.kind === "array");
-    if (arrayFlag !== undefined) {
-      throw new CliArgumentError2(`--${arrayFlag} cannot be combined with automatic positional arguments. Repeat --${arrayFlag} for each element or use --${arrayFlag}:=JSON; name other fields with flags, or declare a positional policy.`);
-    }
-  }
-  const toolArgs = {};
-  const fillable = declaredPositionals === undefined ? [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name) : [...declaredPositionals];
-  const variadicTail = declaredPositionals !== 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 CliArgumentError2(`--${key} conflicts with the positional values for "${key}" — pass one form, not both`);
-      }
-      toolArgs[key] = coerceField(fields.get(key), positionals.slice(pi), `<${key}>`);
-      pi = positionals.length;
-      break;
-    }
-    if (flags.has(key))
-      continue;
-    const value = positionals[pi++];
-    if (value !== undefined) {
-      toolArgs[key] = coerceField(fields.get(key), [value], `<${key}>`);
-    }
-  }
-  if (pi < positionals.length) {
-    throw new CliArgumentError2(`Unexpected positional argument "${positionals[pi]}"`);
-  }
-  const dottedRoots = new Map;
-  for (const key of flags.keys()) {
-    const dot = key.indexOf(".");
-    const exactLiteralBoolean = literalBooleanFlags.has(key) && fields.has(key);
-    if (dot > 0 && !exactLiteralBoolean) {
-      dottedRoots.set(key.slice(0, dot), key);
-    }
-  }
-  for (const [root, dotted] of dottedRoots) {
-    if (flags.has(root)) {
-      throw new CliArgumentError2(`--${root} conflicts with --${dotted} — pass one form, not both`);
-    }
+// src/tools/cli/download.ts
+var DEFAULT_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;
+async function downloadResults(files, dir, stderr, quiet, allowPrivate, maxBytes, timeoutMs) {
+  const root = resolve(dir);
+  if (files.length === 0)
+    return true;
+  let directory;
+  try {
+    directory = await openPinnedDirectory(root, { create: true, readable: false });
+  } catch (error) {
+    stderr(`failed to prepare download directory: ${error instanceof Error ? error.message : String(error)}
+`);
+    return false;
   }
-  for (const key of jsonFields) {
-    for (const other of flags.keys()) {
-      if (other.startsWith(`${key}.`) || key.startsWith(`${other}.`)) {
-        throw new CliArgumentError2(`--${key} conflicts with --${other} — pass one form, not both`);
+  let succeeded = true;
+  try {
+    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 name = basename(file.name);
+        await writeDownload(directory, name, buffer);
+        if (!quiet)
+          stderr(`saved ${resolve(root, name)} (${(buffer.length / 1024).toFixed(0)}KB)
+`);
+      } catch (err) {
+        succeeded = false;
+        const reason = errnoOf(err) ?? (err instanceof Error ? err.message : String(err));
+        stderr(`failed to download ${file.url}: ${reason}
+`);
       }
     }
-  }
-  for (const [key, values] of flags) {
-    const info = fieldFor(key);
-    const exactLiteralBoolean = literalBooleanFlags.has(key) && fields.has(key);
-    if (key.includes(".") && !exactLiteralBoolean) {
-      const root = key.split(".")[0] ?? key;
-      const value = !jsonFields.has(key) && info === undefined && allowUnknown && !fields.has(root) ? looseCoerce(values[0] ?? "") : coerceCliFieldValue(info, values, `--${key}`, jsonFields.has(key));
-      setNested(toolArgs, key.split("."), value);
-      continue;
-    }
-    toolArgs[key] = coerceCliFieldValue(info, values, `--${key}`, jsonFields.has(key));
-  }
-  return toolArgs;
-}
-function parseCliArgs2(argv, schema, config = {}) {
-  const fields = describeSchemaFields(schema);
-  for (const name of config.knownFields ?? []) {
-    if (!fields.has(name))
-      fields.set(name, { kind: "other" });
-  }
-  const fieldFor = (name) => fields.get(name) ?? (name.includes(".") ? describeSchemaPath(schema, name.split(".")) : undefined);
-  const tokens = readCliTokens(argv, fields, fieldFor, config);
-  const { options } = tokens;
-  const view = resolveCliView(tokens.viewFlags, tokens.ascending);
-  if (view)
-    options.view = view;
-  return {
-    toolArgs: buildToolArgs(tokens, fields, fieldFor, config.positionals, config.allowUnknown === true),
-    options
-  };
-}
-function refuseGlobalOption(issue) {
-  const field = issue?.path[0];
-  const where = typeof field === "string" ? `--${field}` : "application option";
-  throw new CliArgumentError2(`${where}: ${issue?.message ?? "invalid value"}`);
-}
-function extractCliGlobalOptions2(argv, schema) {
-  if (schema === undefined)
-    return { argv: [...argv], globals: {} };
-  const fields = describeSchemaFields(schema);
-  const rest = [];
-  const raw = new Map;
-  const jsonFields = new Set;
-  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 field = option ? cliFieldOption(option, fields) : undefined;
-    const info = field && option?.globalKind === undefined ? fields.get(field.name) : undefined;
-    if (!option || !field || !info) {
-      rest.push(token);
-      continue;
-    }
-    let { value } = option;
-    if (value === undefined && info.kind === "boolean") {
-      const separate = separateBoolValue(argv[i + 1]);
-      if (separate !== undefined)
-        i++;
-      value = String(separate ?? true);
-    } else if (value === undefined) {
-      const next = argv[i + 1];
-      if (next !== undefined && !isOptionToken(next)) {
-        value = next;
-        i++;
-      } else {
-        throw new CliArgumentError2(`--${option.name} requires a value`);
-      }
+  } finally {
+    try {
+      await directory.close();
+    } catch (error) {
+      succeeded = false;
+      stderr(`failed to close download directory: ${error instanceof Error ? error.message : String(error)}
+`);
     }
-    appendCliFieldValue(raw, jsonFields, field.name, value, info, field.json);
   }
-  const args = {};
-  for (const [name, values] of raw) {
-    args[name] = coerceCliFieldValue(fields.get(name), values, `--${name}`, jsonFields.has(name));
-  }
-  let coerced;
-  try {
-    coerced = coerceJsonArgs2(args, schema);
-  } catch (error) {
-    if (error instanceof z2.ZodError)
-      refuseGlobalOption(error.issues[0]);
-    throw error;
-  }
-  const parsed = schema.safeParse(coerced);
-  if (!parsed.success)
-    refuseGlobalOption(parsed.error.issues[0]);
-  return { argv: rest, globals: parsed.data };
+  return succeeded;
 }
 
-// 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 CliArgumentError2(`an aggregate needs one collection, but the result carries several: ${arrays.map(([key]) => key).join(", ")} — name the shape you want with jq instead`);
-    }
+// src/tools/cli/help.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"]
+];
+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 constraintLabel(schema) {
+  const limits = [];
+  const bounds = [
+    ["minimum", ">="],
+    ["exclusiveMinimum", ">"],
+    ["maximum", "<="],
+    ["exclusiveMaximum", "<"],
+    ["minLength", "length >="],
+    ["maxLength", "length <="],
+    ["minItems", "items >="],
+    ["maxItems", "items <="]
+  ];
+  for (const [keyword, label] of bounds) {
+    const bound = schema[keyword];
+    if (typeof bound !== "number")
+      continue;
+    if (schema.type === "integer" && Math.abs(bound) === Number.MAX_SAFE_INTEGER)
+      continue;
+    limits.push(`${label}${bound}`);
   }
-  throw new CliArgumentError2("an aggregate needs a collection; this result is not one");
-}
-function isAbsent(value) {
-  return value === undefined || value === null;
-}
-function readField(record, path) {
-  let current = record;
-  for (const segment of path) {
-    if (!isRecord(current) || !Object.hasOwn(current, segment))
-      return;
-    current = current[segment];
+  const compositions = [
+    ["anyOf", "any of", " | "],
+    ["oneOf", "one of", " | "],
+    ["allOf", "all of", " & "]
+  ];
+  for (const [keyword, label, separator] of compositions) {
+    const members = schema[keyword];
+    if (!Array.isArray(members))
+      continue;
+    const branches = members.map((member) => {
+      const constraints = isRecord(member) ? constraintLabel(member) : "";
+      const type = isRecord(member) ? typeLabel(member) : member === false ? "no value" : "any value";
+      return { constraints, text: `${type}${constraints}` };
+    });
+    if (branches.every((branch) => branch.constraints === ""))
+      continue;
+    limits.push(`${label}: ${branches.map((branch) => branch.text).join(separator)}`);
   }
-  return current;
+  return limits.length === 0 ? "" : ` [${limits.join(", ")}]`;
 }
-function fieldPath(field) {
-  const path = field.split(".");
-  if (path.some((segment) => segment.length === 0 || isUnsafeKey(segment))) {
-    throw new CliArgumentError2(`"${field}" is not a readable field path`);
-  }
-  return path;
+function fieldTypeLabel(schema) {
+  return `<${typeLabel(schema)}>${constraintLabel(schema)}`;
 }
-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 nullableField(schema) {
+  if (schema.type === "null")
+    return true;
+  if (Array.isArray(schema.type) && schema.type.includes("null"))
+    return true;
+  return Array.isArray(schema.anyOf) && schema.anyOf.some((member) => isRecord(member) && nullableField(member));
 }
-function assertFieldPresent(records, field) {
-  const path = fieldPath(field);
-  const present = records.some((record) => readField(record, path) !== undefined);
-  if (records.length > 0 && !present) {
-    const available = availableFields(records);
-    throw new CliArgumentError2(`no record carries the field "${field}"${available.length > 0 ? ` — available: ${available.join(", ")}` : ""}`);
-  }
-  return path;
+function jsonValueHelp(fields) {
+  const example = fields.find((field) => nullableField(field.schema))?.name;
+  return [
+    "Assign a whole JSON value with --field:=JSON; the declared schema still validates it.",
+    ...example === undefined ? [] : [`JSON null: --${example}:=null. The literal string stays --${example} null.`]
+  ];
 }
-function groupKey(value) {
-  if (value === undefined)
-    return ABSENT;
-  if (value === null)
-    return "null";
-  if (value === "null" || value === ABSENT)
-    return JSON.stringify(value);
-  if (typeof value === "object")
-    return JSON.stringify(value);
-  return String(value);
+function padRight(text, width) {
+  return text.length >= width ? text : text + " ".repeat(width - text.length);
 }
-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 {
-    kind: "json",
-    data: Object.fromEntries(sliced),
-    order: sliced.map(([key]) => key)
-  };
+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 stringifyGroups(data, order, compact) {
-  if (!isRecord(data) || order.length === 0)
-    return JSON.stringify(data);
-  const lines = order.map((key) => `${JSON.stringify(key)}:${compact ? "" : " "}${JSON.stringify(data[key])}`);
-  return compact ? `{${lines.join(",")}}` : `{
-  ${lines.join(`,
-  `)}
-}`;
+function applicationOptionLines(fields) {
+  if (fields.length === 0)
+    return [];
+  const labels = new Map(fields.map((field) => [field.name, `--${field.name} ${fieldTypeLabel(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 numericValue(value, field) {
-  if (isAbsent(value))
-    return;
-  if (typeof value === "number" && Number.isFinite(value))
-    return value;
-  if (typeof value === "bigint")
-    return Number(value);
-  throw new CliArgumentError2(`--sum ${field}: "${groupKey(value)}" is not a number`);
+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 renderTable(records, columns) {
-  const fields = columns.map(({ field }) => 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) => columns.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 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)" : ""}${descriptor.unavailableReason !== undefined ? " [unavailable]" : ""}`);
+    if (descriptor.unavailableReason !== undefined) {
+      lines.push(`    Unavailable: ${descriptor.unavailableReason}`);
+    }
+  }
+  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(`
 `)}
 `;
-}
-function compareFieldValues(left, right) {
-  if (isAbsent(left))
-    return isAbsent(right) ? 0 : 1;
-  if (isAbsent(right))
-    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));
+  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("", ...jsonValueHelp(input.applicationOptions));
+  lines.push("", `Run "${name} <command> --help" for command-specific flags.`);
+  return `${lines.join(`
+`)}
+`;
 }
-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 leftValue = readField(left, path);
-      const rightValue = readField(right, path);
-      const order = compareFieldValues(leftValue, rightValue);
-      return isAbsent(leftValue) || isAbsent(rightValue) ? order : order * direction;
-    });
+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 columns = view.table?.map((field) => ({
-    field,
-    path: assertFieldPresent(records, 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}]`];
   }));
-  if (view.top !== undefined)
-    selected = selected.slice(0, view.top);
-  return columns ? { kind: "text", text: renderTable(selected, columns) } : { kind: "json", data: selected };
-}
-function refuseEnvelopeFields(data, view) {
-  if (!isRecord(data))
-    return;
-  const fields = view.kind === "records" ? [...view.sort === undefined ? [] : [view.sort], ...view.table ?? []] : [view.field, ...view.kind === "sum" && view.by !== undefined ? [view.by] : []];
-  for (const field of fields) {
-    const first = field.split(".")[0] ?? "";
-    if (Object.hasOwn(data, first) && !Array.isArray(data[first])) {
-      throw new CliArgumentError2(`"${field}" belongs to the result object, not to its empty collection`);
+  const usage = [
+    `Usage: ${name} ${command}`,
+    ...positionals.map((field) => positionalSyntax.get(field.name) ?? field.name),
+    "[--flags]"
+  ].join(" ");
+  const lines = [descriptor.description, "", usage, ""];
+  if (descriptor.unavailableReason !== undefined) {
+    lines.push(`Unavailable: ${descriptor.unavailableReason}`, "");
+  }
+  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)}  ${fieldTypeLabel(f.schema)}${req}${desc}`);
     }
-  }
-}
-function renderCliView2(data, view) {
-  const records = selectRecords(data);
-  if (records.length === 0)
-    refuseEnvelopeFields(data, view);
-  if (view.kind === "records")
-    return renderRecords(records, view);
-  if (view.kind === "count") {
-    const path = assertFieldPresent(records, view.field);
-    const totals = new Map;
-    for (const record of records) {
-      const key = groupKey(readField(record, path));
-      totals.set(key, (totals.get(key) ?? 0) + 1);
+    const flag = [...kinds].find(([, info]) => info.kind === "boolean")?.[0];
+    if (flag !== undefined) {
+      lines.push("", `A boolean flag is on alone or takes true/false: --${flag}, --${flag} false, --no-${flag}`);
     }
-    return ordered(totals, 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));
+    const arrays = [...kinds].filter(([, info]) => info.kind === "array");
+    for (const [field] of arrays) {
+      lines.push("", `Repeat --${field} <value> for each element, or assign the whole array with --${field}:=JSON.`);
+    }
+    if (arrays.length > 0 && descriptor.positionals === undefined) {
+      lines.push("Array options cannot be combined with automatic positional arguments; name other fields with flags.");
+    }
+    lines.push("", ...jsonValueHelp(fields), "");
   }
-  return ordered(totals, view.top);
+  const applicationLines = applicationOptionLines(applicationOptions);
+  if (applicationLines.length > 0)
+    lines.push(...applicationLines.slice(1), "");
+  return `${lines.join(`
+`)}
+`;
 }
 
-// src/tools/operations/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";
-  }
-}
-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 pause = params.sleepFn ?? sleep;
-  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 pause(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/args-route.ts
+function isOptionToken(token) {
+  return token.startsWith("--") || /^-[A-Za-z](?:=|$)/.test(token);
 }
-
-// src/tools/cli/wait.ts
-var DEFAULT_TIMEOUT2 = 600;
-function waitFailure(tool, result) {
+function looksLikeOption(token) {
+  return token.startsWith("--") || /^-[A-Za-z]/.test(token);
+}
+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 {
-    ok: false,
-    code: "WAIT_FAILED",
-    details: {
-      message: `"${tool}" reached a terminal failed state`,
-      result
-    }
+    name,
+    value: equals >= 0 ? token.slice(equals + 1) : undefined,
+    inline: equals >= 0,
+    globalKind: BOOL_OPTIONS.has(name) ? "boolean" : VALUE_OPTIONS.has(name) ? "value" : undefined
   };
 }
-async function pollUntilDone2(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;
+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 routeCliArgv2(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;
+      const next = argv[index];
+      if (option.value === undefined && next !== undefined && separateBoolValue(next) !== undefined) {
+        globals.push(next);
+        index += 1;
       }
-      return wait.done(result.data);
-    },
-    backoff: wait.backoff,
-    timeoutSec,
-    sleepFn: params.sleepFn,
-    onTick: params.onTick,
-    signal: params.signal
-  });
-  if (timedOut) {
+      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 {
-      ok: false,
-      code: "TIMEOUT",
-      details: { message: `Timed out after ${timeoutSec}s waiting for "${wait.tool}"` }
+      command: defaultCommand,
+      commandArgv: [...globals, ...argv.slice(index)],
+      topLevelHelp: false,
+      version: false
     };
   }
-  if (state === failedState && state.ok)
-    return waitFailure(wait.tool, state.data);
-  return state;
+  return {
+    command: defaultCommand,
+    commandArgv: globals,
+    topLevelHelp: false,
+    version: false
+  };
+}
+
+// src/tools/cli/command-shape.ts
+function commandShapeIssue(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`);
+  }
+  if (passthroughField !== undefined && descriptor.aliases.has(passthroughField)) {
+    throw new Error(`[stitchkit] CLI command "${name}" cannot alias passthrough field "${passthroughField}"`);
+  }
+  const fieldNames = jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name);
+  const conflicting = fieldNames.filter((field) => RESERVED_CLI_OPTIONS.has(field));
+  if (conflicting.length > 0) {
+    return `[stitchkit] CLI command "${name}" declares reserved option field(s): ${conflicting.join(", ")}`;
+  }
+  const shadowed = fieldNames.filter((field) => applicationGlobals.has(field));
+  if (shadowed.length > 0) {
+    return `[stitchkit] CLI command "${name}" declares field(s) shadowed by application global options: ${shadowed.join(", ")}`;
+  }
 }
 
-// src/tools/cli/io.ts
-import { writeSync } from "node:fs";
+// src/tools/cli/managed-surface.ts
+async function buildManagedSurface(session, typedGlobals, forExecution) {
+  const { config, nativeHelp, applicationGlobalNames } = session;
+  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";
+  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, commandShapeIssue);
+  return { resolved: true, auth, help, tools };
+}
 
-// src/tools/cli/stdin.ts
-function readPipedStdin(input = process.stdin) {
-  if (input.isTTY || input.readableEnded)
-    return Promise.resolve(null);
-  if (input.destroyed)
-    return Promise.reject(new Error("stdin closed before EOF"));
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    const cleanup = () => {
-      clearTimeout(timer);
-      input.pause();
-      input.off("data", onData);
-      input.off("end", onEnd);
-      input.off("error", onError);
-      input.off("close", onClose);
-    };
-    const onData = (chunk) => {
-      if (chunk.length === 0)
-        return;
-      clearTimeout(timer);
-      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
-    };
-    const onEnd = () => {
-      cleanup();
-      const text = Buffer.concat(chunks).toString("utf8").trim();
-      resolve(text.length > 0 ? text : null);
-    };
-    const onError = (error) => {
-      cleanup();
-      reject(error);
-    };
-    const onClose = () => onError(new Error("stdin closed before EOF"));
-    const timer = setTimeout(() => {
-      cleanup();
-      resolve(null);
-    }, 250);
-    input.on("end", onEnd);
-    input.on("error", onError);
-    input.on("close", onClose);
-    input.on("data", onData);
-    input.resume();
-  });
+// src/tools/cli/args.ts
+import { z as z2 } from "zod";
+
+// src/tools/cli/args-json.ts
+function cliFieldOption(option, fields) {
+  const json = option.inline && option.name.endsWith(":") && !fields.has(option.name);
+  const name = json ? option.name.slice(0, -1) : option.name;
+  return { name, json };
+}
+function appendCliFieldValue(raw, jsonFields, name, value, info, json) {
+  appendCliOptionValue(raw, name, value, json || jsonFields.has(name) ? { kind: "other" } : info);
+  if (json)
+    jsonFields.add(name);
+}
+function coerceCliFieldValue(info, values, label, json) {
+  if (!json)
+    return coerceField(info, values, label);
+  try {
+    return safeJsonParse(values[0] ?? "");
+  } catch (cause) {
+    throw new CliArgumentError2(`${label} expects valid JSON`, { cause });
+  }
 }
 
-// src/tools/cli/io.ts
-function createCliIo(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;
+// src/tools/cli/args-tokens.ts
+function readCliTokens(argv, fields, fieldFor, config) {
+  const options = {
+    json: false,
+    wait: false,
+    quiet: false,
+    dryRun: false,
+    help: false
+  };
+  const flags = new Map;
+  const jsonFields = new Set;
+  const literalBooleanFlags = new Set;
+  const frameworkFlags = new Map;
+  const viewFlags = new Map;
+  let ascending = false;
+  const positionals = [];
+  const pushFlag = (name, value, json = false) => {
+    appendCliFieldValue(flags, jsonFields, name, value, fieldFor(name), json);
+  };
+  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 || !looksLikeOption(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 CliArgumentError2(`Unknown option "${tok}"`);
+      const inline = match?.[2];
+      const info = fieldFor(field);
+      if (info?.kind === "boolean") {
+        const separate = inline === undefined ? separateBoolValue(argv[i + 1]) : undefined;
+        if (separate !== undefined)
+          i++;
+        pushFlag(field, inline ?? String(separate ?? true));
+        if (inline !== undefined)
+          parseReservedBool(field, inline);
+        literalBooleanFlags.add(field);
+        continue;
+      }
+      let value = inline;
+      if (value === undefined) {
+        const next = argv[i + 1];
+        if (next !== undefined && !isOptionToken(next)) {
+          value = next;
+          i++;
+        } else {
+          throw new CliArgumentError2(`--${field} requires a value`);
         }
-        const stream = fd === 1 ? process.stdout : process.stderr;
-        const rest = bytes.subarray(offset);
-        pendingWrite = new Promise((resolve) => {
-          stream.write(rest, (failure) => {
-            if (failure)
-              writeFailed = true;
-            resolve();
-          });
+      }
+      pushFlag(field, value);
+      continue;
+    }
+    const option = classifyLongOptionToken(tok);
+    if (!option)
+      throw new CliArgumentError2(`Unknown option "${tok}"`);
+    const { name, json } = cliFieldOption(option, fields);
+    let { value } = option;
+    if (name.length === 0)
+      throw new CliArgumentError2("Invalid empty option name");
+    if (json && RESERVED_CLI_OPTIONS.has(name)) {
+      throw new CliArgumentError2(`--${name} is a framework option and does not accept :=JSON`);
+    }
+    if (option.globalKind === "boolean") {
+      const separate = value === undefined ? separateBoolValue(argv[i + 1]) : undefined;
+      if (separate !== undefined)
+        i++;
+      if (name !== "help") {
+        appendCliOptionValue(frameworkFlags, name, value ?? String(separate ?? true), {
+          kind: "boolean"
         });
-        return;
+      }
+      const enabled = value === undefined ? separate ?? 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 = options.help || enabled;
+      continue;
+    }
+    if (option.globalKind === "value") {
+      const next = argv[i + 1];
+      value = value ?? next;
+      if (value === undefined || !option.inline && isOptionToken(value)) {
+        throw new CliArgumentError2(`--${name} requires a value`);
+      }
+      if (!option.inline)
+        i++;
+      appendCliOptionValue(frameworkFlags, name, value, { kind: "string" });
+      if (name === "wait-timeout") {
+        const timeout = Number(value);
+        if (!Number.isFinite(timeout) || timeout <= 0) {
+          throw new CliArgumentError2("--wait-timeout must be a positive number");
+        }
+        options.waitTimeout = timeout;
+      } else if (VIEW_OPTIONS.has(name)) {
+        viewFlags.set(name, value);
+      } else {
+        options.outputDir = value;
+      }
+      continue;
+    }
+    if (value === undefined && name.startsWith("no-") && fieldFor(name.slice(3))?.kind === "boolean") {
+      pushFlag(name.slice(3), "false");
+      literalBooleanFlags.add(name.slice(3));
+      continue;
+    }
+    const unsafeSegment = name.split(".").find(isUnsafeKey);
+    if (unsafeSegment !== undefined) {
+      throw new CliArgumentError2(`Unsafe option name "--${name}"`);
+    }
+    const info = fieldFor(name);
+    const rootName = name.split(".")[0] ?? name;
+    if (!fields.has(rootName) && !config.allowUnknown) {
+      throw new CliArgumentError2(`Unknown option "--${name}"`);
+    }
+    if (value === undefined) {
+      if (info?.kind === "boolean") {
+        const separate = separateBoolValue(argv[i + 1]);
+        if (separate !== undefined)
+          i++;
+        pushFlag(name, String(separate ?? true));
+        literalBooleanFlags.add(name);
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next !== undefined && !isOptionToken(next)) {
+        value = next;
+        i++;
+      } else {
+        throw new CliArgumentError2(`--${name} requires a value`);
       }
     }
-  };
-  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 readStdin = config.stdin ?? readPipedStdin;
-  return { stdout, stderr, exit, readStdin };
-}
-
-// src/tools/cli/download.ts
-import { basename, resolve } from "node:path";
-
-// src/internal/write-download.ts
-import path from "node:path";
-async function writeDownload(root, name, data) {
-  if (!isSafeEntryName(name) || path.basename(name) !== name) {
-    throw new Error("download name escapes the output dir");
+    pushFlag(name, value, json);
   }
-  const parent = { handle: root, basename: name };
-  const metadata = await containedEntryMetadata(parent);
-  await writeContainedFile({
-    parent,
-    content: data,
-    replace: true,
-    ...metadata?.isFile() && { mode: metadata.mode }
-  });
+  return {
+    options,
+    flags,
+    jsonFields,
+    literalBooleanFlags,
+    viewFlags,
+    ascending,
+    positionals
+  };
 }
 
-// src/tools/cli/download.ts
-var DEFAULT_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;
-async function downloadResults(files, dir, stderr, quiet, allowPrivate, maxBytes, timeoutMs) {
-  const root = resolve(dir);
-  if (files.length === 0)
-    return true;
-  let directory;
-  try {
-    directory = await openPinnedDirectory(root, { create: true, readable: false });
-  } catch (error) {
-    stderr(`failed to prepare download directory: ${error instanceof Error ? error.message : String(error)}
-`);
-    return false;
-  }
-  let succeeded = true;
-  try {
-    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 name = basename(file.name);
-        await writeDownload(directory, name, buffer);
-        if (!quiet)
-          stderr(`saved ${resolve(root, name)} (${(buffer.length / 1024).toFixed(0)}KB)
-`);
-      } catch (err) {
-        succeeded = false;
-        const reason = errnoOf(err) ?? (err instanceof Error ? err.message : String(err));
-        stderr(`failed to download ${file.url}: ${reason}
-`);
-      }
-    }
-  } finally {
-    try {
-      await directory.close();
-    } catch (error) {
-      succeeded = false;
-      stderr(`failed to close download directory: ${error instanceof Error ? error.message : String(error)}
-`);
+// src/tools/cli/args-view.ts
+function resolveCliView(flags, ascending) {
+  if (flags.size === 0) {
+    if (ascending) {
+      throw new CliArgumentError2("--ascending orders a record view; pass --sort with it");
     }
+    return;
   }
-  return succeeded;
-}
-
-// src/tools/cli/help.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"]
-];
-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 constraintLabel(schema) {
-  const limits = [];
-  const bounds = [
-    ["minimum", ">="],
-    ["exclusiveMinimum", ">"],
-    ["maximum", "<="],
-    ["exclusiveMaximum", "<"],
-    ["minLength", "length >="],
-    ["maxLength", "length <="],
-    ["minItems", "items >="],
-    ["maxItems", "items <="]
-  ];
-  for (const [keyword, label] of bounds) {
-    const bound = schema[keyword];
-    if (typeof bound !== "number")
-      continue;
-    if (schema.type === "integer" && Math.abs(bound) === Number.MAX_SAFE_INTEGER)
-      continue;
-    limits.push(`${label}${bound}`);
+  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 CliArgumentError2(`${named.map(([flag]) => flag).join(" and ")} ask for different shapes — pass one`);
   }
-  const compositions = [
-    ["anyOf", "any of", " | "],
-    ["oneOf", "one of", " | "],
-    ["allOf", "all of", " & "]
-  ];
-  for (const [keyword, label, separator] of compositions) {
-    const members = schema[keyword];
-    if (!Array.isArray(members))
-      continue;
-    const branches = members.map((member) => {
-      const constraints = isRecord(member) ? constraintLabel(member) : "";
-      const type = isRecord(member) ? typeLabel(member) : member === false ? "no value" : "any value";
-      return { constraints, text: `${type}${constraints}` };
-    });
-    if (branches.every((branch) => branch.constraints === ""))
-      continue;
-    limits.push(`${label}: ${branches.map((branch) => branch.text).join(separator)}`);
+  let top;
+  if (rawTop !== undefined) {
+    top = Number(rawTop);
+    if (!Number.isInteger(top) || top <= 0) {
+      throw new CliArgumentError2("--top must be a positive whole number");
+    }
   }
-  return limits.length === 0 ? "" : ` [${limits.join(", ")}]`;
-}
-function fieldTypeLabel(schema) {
-  return `<${typeLabel(schema)}>${constraintLabel(schema)}`;
-}
-function nullableField(schema) {
-  if (schema.type === "null")
-    return true;
-  if (Array.isArray(schema.type) && schema.type.includes("null"))
-    return true;
-  return Array.isArray(schema.anyOf) && schema.anyOf.some((member) => isRecord(member) && nullableField(member));
-}
-function jsonValueHelp(fields) {
-  const example = fields.find((field) => nullableField(field.schema))?.name;
-  return [
-    "Assign a whole JSON value with --field:=JSON; the declared schema still validates it.",
-    ...example === undefined ? [] : [`JSON null: --${example}:=null. The literal string stays --${example} null.`]
-  ];
-}
-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 applicationOptionLines(fields) {
-  if (fields.length === 0)
-    return [];
-  const labels = new Map(fields.map((field) => [field.name, `--${field.name} ${fieldTypeLabel(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)" : ""}${descriptor.unavailableReason !== undefined ? " [unavailable]" : ""}`);
-    if (descriptor.unavailableReason !== undefined) {
-      lines.push(`    Unavailable: ${descriptor.unavailableReason}`);
+  const sort = flags.get("sort");
+  if (table !== undefined || sort !== undefined) {
+    if (countBy !== undefined || sum !== undefined) {
+      throw new CliArgumentError2(`${table !== undefined ? "--table" : "--sort"} lists records; --count-by and --sum aggregate them — pass one`);
+    }
+    if (by !== undefined) {
+      throw new CliArgumentError2("--by groups a view; a record view orders with --sort");
+    }
+    if (top !== undefined && sort === undefined) {
+      throw new CliArgumentError2("--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 CliArgumentError2("--table needs at least one field");
     }
+    return {
+      kind: "records",
+      ...sort !== undefined && { sort },
+      ...ascending && { ascending },
+      ...top !== undefined && { top },
+      ...fields && { table: fields }
+    };
   }
-  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(`
-`)}
-`;
+  if (ascending) {
+    throw new CliArgumentError2("--ascending orders a record view; pass --sort with it");
   }
-  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("", ...jsonValueHelp(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);
+  if (sum !== undefined) {
+    if (top !== undefined && by === undefined) {
+      throw new CliArgumentError2("--top needs --by: a single sum has nothing to rank");
+    }
+    return {
+      kind: "sum",
+      field: sum,
+      ...by !== undefined && { by },
+      ...top !== undefined && { top }
+    };
   }
-  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 (descriptor.unavailableReason !== undefined) {
-    lines.push(`Unavailable: ${descriptor.unavailableReason}`, "");
+  if (countBy !== undefined) {
+    if (by !== undefined) {
+      throw new CliArgumentError2("--count-by already names the grouping field; drop --by");
+    }
+    return { kind: "count", field: countBy, ...top !== undefined && { top } };
   }
-  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)}  ${fieldTypeLabel(f.schema)}${req}${desc}`);
+  if (by !== undefined) {
+    if (top === undefined) {
+      throw new CliArgumentError2("--by groups a view; pass --count-by, --sum or --top with it");
     }
-    const flag = [...kinds].find(([, info]) => info.kind === "boolean")?.[0];
-    if (flag !== undefined) {
-      lines.push("", `A boolean flag is on alone or takes true/false: --${flag}, --${flag} false, --no-${flag}`);
+    return { kind: "count", field: by, top };
+  }
+  throw new CliArgumentError2("--top needs --sort, --by, --count-by or --sum to rank");
+}
+
+// src/tools/cli/args.ts
+function buildToolArgs(tokens, fields, fieldFor, declaredPositionals, allowUnknown) {
+  const { flags, jsonFields, literalBooleanFlags, positionals } = tokens;
+  if (declaredPositionals === undefined && positionals.length > 0) {
+    const arrayFlag = [...flags.keys()].find((key) => fieldFor(key)?.kind === "array");
+    if (arrayFlag !== undefined) {
+      throw new CliArgumentError2(`--${arrayFlag} cannot be combined with automatic positional arguments. Repeat --${arrayFlag} for each element or use --${arrayFlag}:=JSON; name other fields with flags, or declare a positional policy.`);
     }
-    const arrays = [...kinds].filter(([, info]) => info.kind === "array");
-    for (const [field] of arrays) {
-      lines.push("", `Repeat --${field} <value> for each element, or assign the whole array with --${field}:=JSON.`);
+  }
+  const toolArgs = {};
+  const fillable = declaredPositionals === undefined ? [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name) : [...declaredPositionals];
+  const variadicTail = declaredPositionals !== 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 CliArgumentError2(`--${key} conflicts with the positional values for "${key}" — pass one form, not both`);
+      }
+      toolArgs[key] = coerceField(fields.get(key), positionals.slice(pi), `<${key}>`);
+      pi = positionals.length;
+      break;
     }
-    if (arrays.length > 0 && descriptor.positionals === undefined) {
-      lines.push("Array options cannot be combined with automatic positional arguments; name other fields with flags.");
+    if (flags.has(key))
+      continue;
+    const value = positionals[pi++];
+    if (value !== undefined) {
+      toolArgs[key] = coerceField(fields.get(key), [value], `<${key}>`);
     }
-    lines.push("", ...jsonValueHelp(fields), "");
   }
-  const applicationLines = applicationOptionLines(applicationOptions);
-  if (applicationLines.length > 0)
-    lines.push(...applicationLines.slice(1), "");
-  return `${lines.join(`
-`)}
-`;
-}
-
-// src/tools/cli/command-shape.ts
-function commandShapeIssue(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`);
+  if (pi < positionals.length) {
+    throw new CliArgumentError2(`Unexpected positional argument "${positionals[pi]}"`);
   }
-  if (passthroughField !== undefined && descriptor.aliases.has(passthroughField)) {
-    throw new Error(`[stitchkit] CLI command "${name}" cannot alias passthrough field "${passthroughField}"`);
+  const dottedRoots = new Map;
+  for (const key of flags.keys()) {
+    const dot = key.indexOf(".");
+    const exactLiteralBoolean = literalBooleanFlags.has(key) && fields.has(key);
+    if (dot > 0 && !exactLiteralBoolean) {
+      dottedRoots.set(key.slice(0, dot), key);
+    }
   }
-  const fieldNames = jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name);
-  const conflicting = fieldNames.filter((field) => RESERVED_CLI_OPTIONS.has(field));
-  if (conflicting.length > 0) {
-    return `[stitchkit] CLI command "${name}" declares reserved option field(s): ${conflicting.join(", ")}`;
+  for (const [root, dotted] of dottedRoots) {
+    if (flags.has(root)) {
+      throw new CliArgumentError2(`--${root} conflicts with --${dotted} — pass one form, not both`);
+    }
   }
-  const shadowed = fieldNames.filter((field) => applicationGlobals.has(field));
-  if (shadowed.length > 0) {
-    return `[stitchkit] CLI command "${name}" declares field(s) shadowed by application global options: ${shadowed.join(", ")}`;
+  for (const key of jsonFields) {
+    for (const other of flags.keys()) {
+      if (other.startsWith(`${key}.`) || key.startsWith(`${other}.`)) {
+        throw new CliArgumentError2(`--${key} conflicts with --${other} — pass one form, not both`);
+      }
+    }
+  }
+  for (const [key, values] of flags) {
+    const info = fieldFor(key);
+    const exactLiteralBoolean = literalBooleanFlags.has(key) && fields.has(key);
+    if (key.includes(".") && !exactLiteralBoolean) {
+      const root = key.split(".")[0] ?? key;
+      const value = !jsonFields.has(key) && info === undefined && allowUnknown && !fields.has(root) ? looseCoerce(values[0] ?? "") : coerceCliFieldValue(info, values, `--${key}`, jsonFields.has(key));
+      setNested(toolArgs, key.split("."), value);
+      continue;
+    }
+    toolArgs[key] = coerceCliFieldValue(info, values, `--${key}`, jsonFields.has(key));
   }
+  return toolArgs;
 }
-
-// src/tools/cli/managed-surface.ts
-async function buildManagedSurface(session, typedGlobals, forExecution) {
-  const { config, nativeHelp, applicationGlobalNames } = session;
-  let authPromise;
-  const resolveIdentity = () => {
-    authPromise ??= (async () => config.resolveAuth ? await config.resolveAuth(typedGlobals) : await config.auth)();
-    return authPromise;
+function parseCliArgs2(argv, schema, config = {}) {
+  const fields = describeSchemaFields(schema);
+  for (const name of config.knownFields ?? []) {
+    if (!fields.has(name))
+      fields.set(name, { kind: "other" });
+  }
+  const fieldFor = (name) => fields.get(name) ?? (name.includes(".") ? describeSchemaPath(schema, name.split(".")) : undefined);
+  const tokens = readCliTokens(argv, fields, fieldFor, config);
+  const { options } = tokens;
+  const view = resolveCliView(tokens.viewFlags, tokens.ascending);
+  if (view)
+    options.view = view;
+  return {
+    toolArgs: buildToolArgs(tokens, fields, fieldFor, config.positionals, config.allowUnknown === true),
+    options
   };
-  const dynamicSurface = typeof config.services === "function" || typeof config.runtimeTools === "function";
-  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)
-      };
+}
+function refuseGlobalOption(issue) {
+  const field = issue?.path[0];
+  const where = typeof field === "string" ? `--${field}` : "application option";
+  throw new CliArgumentError2(`${where}: ${issue?.message ?? "invalid value"}`);
+}
+function extractCliGlobalOptions2(argv, schema) {
+  if (schema === undefined)
+    return { argv: [...argv], globals: {} };
+  const fields = describeSchemaFields(schema);
+  const rest = [];
+  const raw = new Map;
+  const jsonFields = new Set;
+  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 field = option ? cliFieldOption(option, fields) : undefined;
+    const info = field && option?.globalKind === undefined ? fields.get(field.name) : undefined;
+    if (!option || !field || !info) {
+      rest.push(token);
+      continue;
+    }
+    let { value } = option;
+    if (value === undefined && info.kind === "boolean") {
+      const separate = separateBoolValue(argv[i + 1]);
+      if (separate !== undefined)
+        i++;
+      value = String(separate ?? true);
+    } else if (value === undefined) {
+      const next = argv[i + 1];
+      if (next !== undefined && !isOptionToken(next)) {
+        value = next;
+        i++;
+      } else {
+        throw new CliArgumentError2(`--${option.name} requires a value`);
+      }
     }
+    appendCliFieldValue(raw, jsonFields, field.name, value, info, field.json);
   }
-  const { tools, help } = buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, commandShapeIssue);
-  return { resolved: true, auth, help, tools };
+  const args = {};
+  for (const [name, values] of raw) {
+    args[name] = coerceCliFieldValue(fields.get(name), values, `--${name}`, jsonFields.has(name));
+  }
+  let coerced;
+  try {
+    coerced = coerceJsonArgs2(args, schema);
+  } catch (error) {
+    if (error instanceof z2.ZodError)
+      refuseGlobalOption(error.issues[0]);
+    throw error;
+  }
+  const parsed = schema.safeParse(coerced);
+  if (!parsed.success)
+    refuseGlobalOption(parsed.error.issues[0]);
+  return { argv: rest, globals: parsed.data };
 }
 
 // src/tools/cli/prepare.ts
@@ -2202,6 +1895,243 @@ function unavailableCommandJson(argv) {
   return false;
 }
 
+// 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 CliArgumentError2(`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 CliArgumentError2("an aggregate needs a collection; this result is not one");
+}
+function isAbsent(value) {
+  return value === undefined || value === null;
+}
+function readField(record, path) {
+  let current = record;
+  for (const segment of path) {
+    if (!isRecord(current) || !Object.hasOwn(current, segment))
+      return;
+    current = current[segment];
+  }
+  return current;
+}
+function fieldPath(field) {
+  const path = field.split(".");
+  if (path.some((segment) => segment.length === 0 || isUnsafeKey(segment))) {
+    throw new CliArgumentError2(`"${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 (records.length > 0 && !present) {
+    const available = availableFields(records);
+    throw new CliArgumentError2(`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 (value === "null" || value === ABSENT)
+    return JSON.stringify(value);
+  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 {
+    kind: "json",
+    data: Object.fromEntries(sliced),
+    order: sliced.map(([key]) => key)
+  };
+}
+function stringifyGroups(data, order, compact) {
+  if (!isRecord(data) || order.length === 0)
+    return JSON.stringify(data);
+  const lines = order.map((key) => `${JSON.stringify(key)}:${compact ? "" : " "}${JSON.stringify(data[key])}`);
+  return compact ? `{${lines.join(",")}}` : `{
+  ${lines.join(`,
+  `)}
+}`;
+}
+function numericValue(value, field) {
+  if (isAbsent(value))
+    return;
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value === "bigint")
+    return Number(value);
+  throw new CliArgumentError2(`--sum ${field}: "${groupKey(value)}" is not a number`);
+}
+function renderTable(records, columns) {
+  const fields = columns.map(({ field }) => 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) => columns.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 (isAbsent(left))
+    return isAbsent(right) ? 0 : 1;
+  if (isAbsent(right))
+    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 leftValue = readField(left, path);
+      const rightValue = readField(right, path);
+      const order = compareFieldValues(leftValue, rightValue);
+      return isAbsent(leftValue) || isAbsent(rightValue) ? order : order * direction;
+    });
+  }
+  const columns = view.table?.map((field) => ({
+    field,
+    path: assertFieldPresent(records, field)
+  }));
+  if (view.top !== undefined)
+    selected = selected.slice(0, view.top);
+  return columns ? { kind: "text", text: renderTable(selected, columns) } : { kind: "json", data: selected };
+}
+function refuseEnvelopeFields(data, view) {
+  if (!isRecord(data))
+    return;
+  const fields = view.kind === "records" ? [...view.sort === undefined ? [] : [view.sort], ...view.table ?? []] : [view.field, ...view.kind === "sum" && view.by !== undefined ? [view.by] : []];
+  for (const field of fields) {
+    const first = field.split(".")[0] ?? "";
+    if (Object.hasOwn(data, first) && !Array.isArray(data[first])) {
+      throw new CliArgumentError2(`"${field}" belongs to the result object, not to its empty collection`);
+    }
+  }
+}
+function renderCliView2(data, view) {
+  const records = selectRecords(data);
+  if (records.length === 0)
+    refuseEnvelopeFields(data, view);
+  if (view.kind === "records")
+    return renderRecords(records, view);
+  if (view.kind === "count") {
+    const path = assertFieldPresent(records, view.field);
+    const totals = new Map;
+    for (const record of records) {
+      const key = groupKey(readField(record, path));
+      totals.set(key, (totals.get(key) ?? 0) + 1);
+    }
+    return ordered(totals, 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 ordered(totals, view.top);
+}
+
+// src/tools/cli/wait.ts
+var DEFAULT_TIMEOUT = 600;
+function waitFailure(tool, result) {
+  return {
+    ok: false,
+    code: "WAIT_FAILED",
+    details: {
+      message: `"${tool}" reached a terminal failed state`,
+      result
+    }
+  };
+}
+async function pollUntilDone2(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_TIMEOUT;
+  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/run-managed.ts
 async function runManagedInvocation(session, route) {
   const { config } = session;
@@ -2453,4 +2383,4 @@ async function createCli2(config) {
   return runManagedInvocation(session, route);
 }
 
-export { WaitTimeoutError, runWaitOperation, defineCliCommand2, DEFAULT_EXIT_CODES2, cliExitCode2, emitResult2, CliArgumentError2, cliInvocationResult2, createCliInvoker2, routeCliArgv2, parseCliArgs2, extractCliGlobalOptions2, renderCliView2, pollUntilDone2, createCli2 };
+export { defineCliCommand2, DEFAULT_EXIT_CODES2, cliExitCode2, emitResult2, CliArgumentError2, cliInvocationResult2, createCliInvoker2, routeCliArgv2, parseCliArgs2, extractCliGlobalOptions2, renderCliView2, pollUntilDone2, createCli2 };