stitchkit 0.122.1 → 0.123.0

package/dist/{index-aswegq1r.js → index-xjb131sc.js}

@@ -1,45 +1,53 @@
 import {
   validateDeclaredOutput
-} from "./index-k42ckyzx.js";
+} from "./index-ndjzbt2v.js";
 import {
   jsonSchemaObjectCoercionMembers
 } from "./index-dsa676h8.js";
 import {
   coerceJsonArgs2
-} from "./index-rbzq0q16.js";
+} from "./index-t8jz0e20.js";
 import {
+  toJsonSchema,
   jsonSchemaFields
 } from "./index-ct75c3at.js";
 import {
+  toolSurfaceOutputSchema,
   objectShapeKeys,
+  mergeSchemas,
+  toToolName,
   assertUniqueToolName,
   buildToolPresentationSchema
-} from "./index-x4p3kw1p.js";
+} from "./index-tynna0n4.js";
 import {
   toolResultFromError,
   toolErrorFromResult
-} from "./index-s3yxw6kt.js";
+} from "./index-s512scra.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-ycqhyars.js";
+} from "./index-qc7tq0za.js";
 import {
   isRepeatableRead
 } from "./index-332d0m9g.js";
+import {
+  readContractStreamItems,
+  contractStreamLifetimeExceeded
+} from "./index-0v9xb8pz.js";
 import {
   writeContainedFile
-} from "./index-aqmadanx.js";
+} from "./index-fa53vygr.js";
 import {
   openPinnedDirectory,
   isSafeEntryName,
   containedEntryMetadata
-} from "./index-eeahxwvg.js";
+} from "./index-ww3gss55.js";
 import {
   pollUntil
 } from "./index-bph35vpy.js";
 import {
   collectToolSurface
-} from "./index-ff39f9dr.js";
+} from "./index-993vtv1w.js";
 import {
   fetchGuarded,
   readCapped
@@ -57,32 +65,108 @@ import {
 import {
   AppError2,
   STITCH_ERROR_STATUS2
-} from "./index-qcn84byh.js";
+} from "./index-0w0hxp7n.js";
 import {
-  isRecord
-} from "./index-9jfdm5tg.js";
+  isRecord,
+  isAsyncIterable
+} from "./index-hkxgennw.js";
+
+// src/tools/cli/format.ts
+var DEFAULT_EXIT_CODES2 = {
+  VALIDATION_ERROR: 1,
+  BAD_REQUEST: 1,
+  UNAUTHORIZED: 2,
+  FORBIDDEN: 3,
+  NOT_FOUND: 4,
+  UNKNOWN_OPERATION: 4,
+  CONFLICT: 5,
+  RATE_LIMITED: 6,
+  TIMEOUT: 7,
+  REQUEST_ABORTED: 130,
+  REQUEST_TIMEOUT: 7,
+  CONNECTION_TIMEOUT: 7,
+  STREAM_LIFETIME_EXCEEDED: 7,
+  CONNECTION_RESPONSE_TOO_LARGE: 1,
+  CONNECTION_REQUEST_FAILED: 1,
+  UPSTREAM_TOOL_ERROR: 1,
+  WAIT_FAILED: 1,
+  CLI_COMMAND_UNAVAILABLE: 1,
+  CLI_PRESENTATION_FAILED: 8,
+  INTERNAL_SERVER_ERROR: 1
+};
+function cliExitCode2(result, exitCodes) {
+  if (result.ok)
+    return 0;
+  const codes = { ...DEFAULT_EXIT_CODES2, ...exitCodes };
+  return Object.hasOwn(codes, result.code) ? codes[result.code] ?? 1 : 1;
+}
+function emitResult2(result, writers, opts) {
+  if (result.ok) {
+    if (result.data === undefined)
+      return 0;
+    const text = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
+    writers.stdout(`${text}
+`);
+    return 0;
+  }
+  const error = formatToolError(result, opts.toolName, opts.errorHint);
+  const text = opts.json ? JSON.stringify(error) : JSON.stringify(error, null, 2);
+  writers.stderr(`${text}
+`);
+  return cliExitCode2(result, opts.exitCodes);
+}
+function presentationFailureHint(repeatable, printed) {
+  if (repeatable) {
+    return "The result was not printed: this command only reads. Repeat it with a corrected view.";
+  }
+  return printed ? "The complete, unformatted result is on stdout. Do not repeat the command to recover its result." : "The command returned no result. Do not repeat it.";
+}
+function emitPresentationFailure(result, failure, writers, opts) {
+  const printed = !opts.repeatable && result.data !== undefined;
+  if (printed)
+    emitResult2(result, writers, opts);
+  return emitResult2({
+    ok: false,
+    code: "CLI_PRESENTATION_FAILED",
+    retryable: false,
+    details: {
+      message: "The command completed successfully, but its result presentation failed.",
+      command: opts.toolName,
+      operationSucceeded: true,
+      resultOnStdout: printed,
+      cause: formatToolError(failure)
+    },
+    hint: presentationFailureHint(opts.repeatable, printed)
+  }, writers, { json: opts.json, toolName: opts.toolName, exitCodes: opts.exitCodes });
+}
 
 // src/tools/cli/command.ts
+function defineCliResult2(output, policy) {
+  return { ...policy, output };
+}
 function defineCliCommand2(definition) {
   return definition;
 }
 function cliCommandReturnsResult(definition) {
   return definition.output !== undefined;
 }
-function cliCommandSuccessExitCode(definition, data) {
-  const successExitCode = definition.exitCode?.(data) ?? 0;
+function cliCommandSuccessExitCode(policy, data) {
+  const successExitCode = policy?.exitCode?.(data) ?? 0;
   if (!Number.isSafeInteger(successExitCode) || successExitCode < 0 || successExitCode > 255) {
     throw new Error("CLI success exit code must be an integer from 0 to 255");
   }
   return successExitCode;
 }
-function prepareCliCommandEmission(definition, result, options) {
-  if (!result.ok || definition.output === undefined) {
+function cliCommandResultPolicy(definition) {
+  return cliCommandReturnsResult(definition) ? definition : undefined;
+}
+function prepareCliCommandEmission(policy, result, options) {
+  if (!result.ok || policy === undefined) {
     return { result, successExitCode: 0 };
   }
   let successExitCode;
   try {
-    successExitCode = cliCommandSuccessExitCode(definition, result.data);
+    successExitCode = cliCommandSuccessExitCode(policy, result.data);
   } catch (error) {
     return {
       result: toolResultFromError(new Error("CLI result policy failed", { cause: error })),
@@ -90,9 +174,9 @@ function prepareCliCommandEmission(definition, result, options) {
     };
   }
   try {
-    if (definition.present === undefined)
+    if (policy.present === undefined)
       return { result, successExitCode };
-    const presentation = definition.present({ result: result.data, options });
+    const presentation = policy.present({ result: result.data, options });
     if (typeof presentation !== "string") {
       throw new Error("CLI result presenter must return a string");
     }
@@ -105,6 +189,18 @@ function prepareCliCommandEmission(definition, result, options) {
     };
   }
 }
+function emitCliCommandResult(policy, result, options, writers, emit) {
+  const emission = prepareCliCommandEmission(policy, result, options);
+  if (emission.result.ok && emission.presentationFailure !== undefined) {
+    return emitPresentationFailure(emission.result, emission.presentationFailure, writers, emit);
+  }
+  if (emission.result.ok && emission.presentation !== undefined) {
+    writers.stdout(emission.presentation);
+    return emission.successExitCode;
+  }
+  const emitted = emitResult2(emission.result, writers, emit);
+  return emission.result.ok ? emission.successExitCode : emitted;
+}
 function cliCommandPresentationSchema(definition) {
   return buildToolPresentationSchema({
     inputSchema: definition.input,
@@ -146,73 +242,6 @@ async function executeCliCommand(definition, rawArgs, options, writers, coerceJs
   }
 }
 
-// src/tools/cli/format.ts
-var DEFAULT_EXIT_CODES2 = {
-  VALIDATION_ERROR: 1,
-  BAD_REQUEST: 1,
-  UNAUTHORIZED: 2,
-  FORBIDDEN: 3,
-  NOT_FOUND: 4,
-  CONFLICT: 5,
-  RATE_LIMITED: 6,
-  TIMEOUT: 7,
-  REQUEST_ABORTED: 130,
-  REQUEST_TIMEOUT: 7,
-  CONNECTION_TIMEOUT: 7,
-  CONNECTION_RESPONSE_TOO_LARGE: 1,
-  CONNECTION_REQUEST_FAILED: 1,
-  UPSTREAM_TOOL_ERROR: 1,
-  WAIT_FAILED: 1,
-  CLI_COMMAND_UNAVAILABLE: 1,
-  CLI_PRESENTATION_FAILED: 8,
-  INTERNAL_SERVER_ERROR: 1
-};
-function cliExitCode2(result, exitCodes) {
-  if (result.ok)
-    return 0;
-  const codes = { ...DEFAULT_EXIT_CODES2, ...exitCodes };
-  return Object.hasOwn(codes, result.code) ? codes[result.code] ?? 1 : 1;
-}
-function emitResult2(result, writers, opts) {
-  if (result.ok) {
-    if (result.data === undefined)
-      return 0;
-    const text = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
-    writers.stdout(`${text}
-`);
-    return 0;
-  }
-  const error = formatToolError(result, opts.toolName, opts.errorHint);
-  const text = opts.json ? JSON.stringify(error) : JSON.stringify(error, null, 2);
-  writers.stderr(`${text}
-`);
-  return cliExitCode2(result, opts.exitCodes);
-}
-function presentationFailureHint(repeatable, printed) {
-  if (repeatable) {
-    return "The result was not printed: this command only reads. Repeat it with a corrected view.";
-  }
-  return printed ? "The complete, unformatted result is on stdout. Do not repeat the command to recover its result." : "The command returned no result. Do not repeat it.";
-}
-function emitPresentationFailure(result, failure, writers, opts) {
-  const printed = !opts.repeatable && result.data !== undefined;
-  if (printed)
-    emitResult2(result, writers, opts);
-  return emitResult2({
-    ok: false,
-    code: "CLI_PRESENTATION_FAILED",
-    retryable: false,
-    details: {
-      message: "The command completed successfully, but its result presentation failed.",
-      command: opts.toolName,
-      operationSucceeded: true,
-      resultOnStdout: printed,
-      cause: formatToolError(failure)
-    },
-    hint: presentationFailureHint(opts.repeatable, printed)
-  }, writers, { json: opts.json, toolName: opts.toolName, exitCodes: opts.exitCodes });
-}
-
 // src/tools/cli/args-fields.ts
 import { z } from "zod";
 
@@ -575,6 +604,9 @@ function resolvePositionals(command, descriptor, configured) {
   }
   return [...configured];
 }
+function cliResultPolicy(config, command) {
+  return config.results && Object.hasOwn(config.results, command) ? config.results[command] : undefined;
+}
 function applyCliPresentationPolicy(command, descriptor, config) {
   const base = { ...descriptor, aliases: new Map };
   const configuredAliases = config.optionAliases && Object.hasOwn(config.optionAliases, command) ? config.optionAliases[command] : undefined;
@@ -588,7 +620,8 @@ function applyCliPresentationPolicy(command, descriptor, config) {
 function assertCliPoliciesResolved(commands, config) {
   const configuredNames = new Set([
     ...Object.keys(config.optionAliases ?? {}),
-    ...Object.keys(config.positionals ?? {})
+    ...Object.keys(config.positionals ?? {}),
+    ...Object.keys(config.results ?? {})
   ]);
   if (config.defaultCommand !== undefined)
     configuredNames.add(config.defaultCommand);
@@ -599,6 +632,33 @@ function assertCliPoliciesResolved(commands, config) {
   }
 }
 
+// src/tools/cli/stream-surface.ts
+function collectCliStreams(services) {
+  const streams = new Map;
+  for (const service of services) {
+    for (const [methodName, method] of Object.entries(service.methods)) {
+      if (method.stream === undefined || !method.expose?.includes("CLI"))
+        continue;
+      const name = toToolName(service.name, methodName);
+      streams.set(name, {
+        descriptor: method.stream,
+        tool: {
+          method,
+          name,
+          argumentSchema: mergeSchemas(method.paramsSchema, method.inputSchema),
+          presentationSchema: buildToolPresentationSchema({
+            paramsSchema: method.paramsSchema,
+            inputSchema: method.inputSchema,
+            unrepresentable: "any"
+          }),
+          shouldExtend: false
+        }
+      });
+    }
+  }
+  return streams;
+}
+
 // src/tools/cli/invoke.ts
 function parseCliGlobals(schema, globals) {
   if (!schema)
@@ -657,8 +717,8 @@ async function createCliInvoker2(config, globals) {
       if (!tool) {
         return cliInvocationResult2({
           ok: false,
-          code: "NOT_FOUND",
-          details: { message: `Unknown command "${command}"` }
+          code: "UNKNOWN_OPERATION",
+          details: { message: `Unknown command "${command}"`, operation: command }
         }, command, config);
       }
       let result;
@@ -667,10 +727,19 @@ async function createCliInvoker2(config, globals) {
       } catch (error) {
         result = toolResultFromError(error);
       }
-      return cliInvocationResult2(result, command, config);
+      return withSuccessExitCode(cliInvocationResult2(result, command, config), cliResultPolicy(config, command), result, command, config);
     }
   };
 }
+function withSuccessExitCode(invocation, policy, result, command, config) {
+  if (!result.ok || policy === undefined)
+    return invocation;
+  try {
+    return { ...invocation, exitCode: cliCommandSuccessExitCode(policy, result.data) };
+  } catch (error) {
+    return cliInvocationResult2(toolResultFromError(new Error("CLI result policy failed", { cause: error })), command, config);
+  }
+}
 var IN_PROCESS_RUN_OPTIONS = Object.freeze({
   json: false,
   wait: false,
@@ -689,17 +758,7 @@ async function runNativeCommand(definition, args, config, globals) {
       err += text;
     }
   }, config.coerceJsonArgs ?? true, globals);
-  let invocation = cliInvocationResult2(result, definition.name, config);
-  if (invocation.ok) {
-    try {
-      invocation = {
-        ...invocation,
-        exitCode: cliCommandSuccessExitCode(definition, result.ok ? result.data : undefined)
-      };
-    } catch (error) {
-      invocation = cliInvocationResult2(toolResultFromError(error), definition.name, config);
-    }
-  }
+  const invocation = withSuccessExitCode(cliInvocationResult2(result, definition.name, config), cliCommandResultPolicy(definition), result, definition.name, config);
   if (out === "" && err === "")
     return invocation;
   return {
@@ -727,14 +786,38 @@ function buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, shape
       help.set(mountable.name, descriptor);
     }
   }
+  const streams = collectCliStreams(services);
+  for (const [name, stream] of streams) {
+    const descriptor = applyCliPresentationPolicy(name, {
+      ...managedCliDescriptor(stream.tool),
+      outputSchema: stream.descriptor.item,
+      stream: true
+    }, config);
+    const issue = shapeIssue?.(name, descriptor, help.has(name), config.passthrough?.[name], applicationGlobalNames);
+    if (issue !== undefined)
+      throw new Error(issue);
+    help.set(name, descriptor);
+  }
   assertCliPoliciesResolved(help, config);
-  return { tools, help };
+  for (const [name, policy] of Object.entries(config.results ?? {})) {
+    if (!tools.has(name) && !streams.has(name)) {
+      throw new Error(`[stitchkit] CLI result policy "${name}" targets a command that is not managed; a native command declares present and exitCode on defineCliCommand`);
+    }
+    if (policy.output !== undefined && policy.output !== help.get(name)?.outputSchema) {
+      throw new Error(`[stitchkit] CLI result policy "${name}" is typed against a schema that is not the one the command answers with; pass the command's own output schema to defineCliResult`);
+    }
+    if (streams.has(name) && policy.exitCode !== undefined) {
+      throw new Error(`[stitchkit] CLI result policy "${name}" declares exitCode for a stream command; a stream has no single result to classify`);
+    }
+  }
+  return { tools, streams, help };
 }
 function managedCliDescriptor(tool) {
   return {
     description: tool.method.desc,
     argumentSchema: tool.argumentSchema,
-    presentationSchema: tool.presentationSchema
+    presentationSchema: tool.presentationSchema,
+    outputSchema: toolSurfaceOutputSchema(tool.method)
   };
 }
 
@@ -786,6 +869,9 @@ function readPipedStdin(input = process.stdin) {
 }
 
 // src/tools/cli/io.ts
+function isReaderGone(error) {
+  return isRecord(error) && (error.code === "EPIPE" || error.code === "ERR_STREAM_DESTROYED");
+}
 function createCliIo(config) {
   let pendingWrite;
   let writeFailed = false;
@@ -796,6 +882,8 @@ function createCliIo(config) {
       try {
         offset += writeSync(fd, bytes, offset, bytes.length - offset);
       } catch (error) {
+        if (fd === 1 && isReaderGone(error))
+          throw error;
         if (isRecord(error) && error.code === "EAGAIN") {
           Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
           continue;
@@ -813,7 +901,24 @@ function createCliIo(config) {
       }
     }
   };
-  const stdout = config.stdout ?? ((text) => writeFd(1, text));
+  const writeStdout = config.stdout ?? ((text) => writeFd(1, text));
+  let readerGone = false;
+  const stdoutWhileOpen = (text) => {
+    if (readerGone)
+      return false;
+    try {
+      writeStdout(text);
+      return true;
+    } catch (error) {
+      if (!isReaderGone(error))
+        throw error;
+      readerGone = true;
+      return false;
+    }
+  };
+  const stdout = (text) => {
+    stdoutWhileOpen(text);
+  };
   const stderr = config.stderr ?? ((text) => writeFd(2, text));
   const exit = config.exit ?? ((code) => {
     if (pendingWrite === undefined)
@@ -822,7 +927,7 @@ function createCliIo(config) {
       pendingWrite.then(() => process.exit(writeFailed ? 1 : code));
   });
   const readStdin = config.stdin ?? readPipedStdin;
-  return { stdout, stderr, exit, readStdin };
+  return { stdout, stdoutWhileOpen, stderr, exit, readStdin };
 }
 
 // src/tools/cli/download.ts
@@ -900,6 +1005,7 @@ var GLOBAL_OPTIONS = [
   ["--output-dir <dir>", "Download result media into a directory"],
   ["--quiet", "Suppress non-essential stderr output"],
   ["--dry-run", "Print the resolved call without executing it"],
+  ["--schema", "Print the JSON Schema of a command input and output"],
   ["--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"],
@@ -1105,7 +1211,15 @@ function isOptionToken(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 BOOL_OPTIONS = new Set([
+  "json",
+  "wait",
+  "quiet",
+  "dry-run",
+  "help",
+  "schema",
+  "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]);
@@ -1291,8 +1405,8 @@ async function buildManagedSurface(session, typedGlobals, forExecution) {
       };
     }
   }
-  const { tools, help } = buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, commandShapeIssue);
-  return { resolved: true, auth, help, tools };
+  const { tools, streams, help } = buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, commandShapeIssue);
+  return { resolved: true, auth, help, tools, streams };
 }
 
 // src/tools/cli/args.ts
@@ -1416,6 +1530,8 @@ function readCliTokens(argv, fields, fieldFor, config) {
         options.quiet = enabled;
       else if (name === "ascending")
         ascending = enabled;
+      else if (name === "schema")
+        continue;
       else
         options.help = options.help || enabled;
       continue;
@@ -1790,7 +1906,8 @@ function nativeDescriptor(definition) {
   return {
     description: definition.description,
     argumentSchema: definition.input,
-    presentationSchema: cliCommandPresentationSchema(definition)
+    presentationSchema: cliCommandPresentationSchema(definition),
+    outputSchema: definition.output
   };
 }
 function createCliSession(config, io) {
@@ -1859,12 +1976,14 @@ function resolveCliRoute(session, argv) {
     return;
   }
   const beforeSeparator = commandArgv.indexOf("--") === -1 ? commandArgv : commandArgv.slice(0, commandArgv.indexOf("--"));
-  const helpRequested = beforeSeparator.some((token) => {
-    if (token === "--help" || token === "-h")
+  const asked = (name) => beforeSeparator.some((token) => {
+    if (token === `--${name}` || name === "help" && token === "-h")
       return true;
     const option = classifyLongOptionToken(token);
-    return option?.name === "help" && option.value !== undefined && isReservedBoolWord(option.value) && parseReservedBool("help", option.value);
+    return option?.name === name && option.value !== undefined && isReservedBoolWord(option.value) && parseReservedBool(name, option.value);
   });
+  const helpRequested = asked("help");
+  const schemaRequested = !helpRequested && asked("schema");
   return {
     globals,
     typedGlobals,
@@ -1872,9 +1991,20 @@ function resolveCliRoute(session, argv) {
     command,
     commandArgv,
     beforeSeparator,
-    helpRequested
+    helpRequested,
+    schemaRequested
   };
 }
+function renderCommandSchema(command, descriptor) {
+  return `${JSON.stringify({
+    command,
+    input: descriptor.presentationSchema,
+    ...descriptor.outputSchema !== undefined && {
+      [descriptor.stream ? "item" : "output"]: toJsonSchema(descriptor.outputSchema, "output", "any", "draft-07")
+    }
+  })}
+`;
+}
 function emitOptionsFor(config, json, toolName) {
   return {
     json,
@@ -1884,6 +2014,106 @@ function emitOptionsFor(config, json, toolName) {
   };
 }
 
+// src/tools/cli/run-stream.ts
+async function runStreamCommand(session, route, managed, stream, { toolArgs, options }) {
+  const { config } = session;
+  const { stdout, stderr, exit } = session.io;
+  const command = stream.tool.name;
+  if (options.wait || options.outputDir !== undefined || options.view !== undefined) {
+    stderr(`--wait, --output-dir and aggregate views do not apply to stream command "${command}"
+`);
+    return exit(2);
+  }
+  const abort = new AbortController;
+  let cancelled = false;
+  const cancel = () => {
+    cancelled = true;
+    abort.abort(config.signal?.reason);
+  };
+  if (config.signal?.aborted)
+    cancel();
+  else
+    config.signal?.addEventListener("abort", cancel, { once: true });
+  const runTool = createToolRunner({
+    source: "cli",
+    toolSurface: true,
+    context: { ...config.context?.(managed.auth, route.typedGlobals), signal: abort.signal },
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    coerceJsonArgs: config.coerceJsonArgs
+  });
+  let opened;
+  try {
+    opened = await runTool(stream.tool, toolArgs);
+  } catch (error) {
+    opened = toolResultFromError(error);
+  }
+  const policy = cliResultPolicy(config, command);
+  let outcome;
+  if (!opened.ok)
+    outcome = opened;
+  else if (!isAsyncIterable(opened.data)) {
+    outcome = toolResultFromError(new Error(`Stream command "${command}" handler did not return an async iterable`));
+  } else {
+    outcome = await printStreamItems(opened.data, stream, abort, () => cancelled, (item) => session.io.stdoutWhileOpen(streamLine(command, item, policy, options)));
+  }
+  config.signal?.removeEventListener("abort", cancel);
+  if (outcome === "completed" || outcome === "reader-gone")
+    return exit(0);
+  if (outcome === "cancelled" || cancelled) {
+    return exit(cliExitCode2({ ok: false, code: "REQUEST_ABORTED" }, config.exitCodes));
+  }
+  return exit(emitResult2(outcome, { stdout, stderr }, emitOptionsFor(config, options.json, command)));
+}
+function streamLine(command, item, policy, options) {
+  if (policy?.present === undefined)
+    return `${JSON.stringify(item)}
+`;
+  let line;
+  try {
+    line = policy.present({ result: item, options });
+    if (typeof line !== "string")
+      throw new Error("CLI result presenter must return a string");
+  } catch (error) {
+    throw new AppError2("CLI_PRESENTATION_FAILED", {
+      message: "A stream item was produced, but its presentation failed.",
+      status: 500,
+      details: { command, cause: formatToolError(toolResultFromError(error)) }
+    });
+  }
+  return line;
+}
+async function printStreamItems(source, { descriptor }, abort, wasCancelled, write) {
+  const iterator = source[Symbol.asyncIterator]();
+  let lifetimeExpired = false;
+  const lifetime = descriptor.lifetimeMs === undefined ? undefined : setTimeout(() => {
+    lifetimeExpired = true;
+    abort.abort(new Error("Stream lifetime expired"));
+  }, descriptor.lifetimeMs);
+  lifetime?.unref?.();
+  try {
+    for await (const { item } of readContractStreamItems(iterator, descriptor, abort.signal)) {
+      if (!write(item))
+        return "reader-gone";
+    }
+    return "completed";
+  } catch (error) {
+    if (wasCancelled())
+      return "cancelled";
+    if (lifetimeExpired) {
+      return toolResultFromError(contractStreamLifetimeExceeded());
+    }
+    return toolResultFromError(error);
+  } finally {
+    if (lifetime !== undefined)
+      clearTimeout(lifetime);
+    abort.abort();
+    Promise.resolve().then(() => iterator.return?.(undefined)).catch(() => {
+      return;
+    });
+  }
+}
+
 // src/tools/cli/unavailable.ts
 function unavailableCommand(reason) {
   return toolResultFromError(new AppError2("CLI_COMMAND_UNAVAILABLE", {
@@ -2148,9 +2378,9 @@ async function pollUntilDone2(params) {
 async function runManagedInvocation(session, route) {
   const { config } = session;
   const { stdout, stderr, exit } = session.io;
-  const { command, helpRequested, beforeSeparator } = route;
+  const { command, helpRequested, schemaRequested, beforeSeparator } = route;
   const topLevelHelp = route.route.topLevelHelp || command === undefined || command === "help" || command === "--help" || command === "-h" || command.startsWith("--help=") && !isReservedBoolWord(command.slice("--help=".length));
-  const managed = await buildManagedSurface(session, route.typedGlobals, !topLevelHelp && !helpRequested);
+  const managed = await buildManagedSurface(session, route.typedGlobals, !topLevelHelp && !helpRequested && !schemaRequested);
   if (topLevelHelp)
     return respondTopLevelHelp(session, route, managed);
   if (!managed.resolved) {
@@ -2196,11 +2426,16 @@ async function runManagedCommand(session, route, command, managed) {
     stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
     return exit(0);
   }
+  if (route.schemaRequested) {
+    stdout(renderCommandSchema(command, descriptor));
+    return exit(0);
+  }
   if (descriptor.unavailableReason !== undefined) {
     return exit(emitResult2(unavailableCommand(descriptor.unavailableReason), { stdout, stderr }, emitOptionsFor(config, unavailableCommandJson(route.commandArgv), command)));
   }
+  const stream = managed.streams.get(command);
   const tool = managed.tools.get(command);
-  if (!tool)
+  if (!tool && !stream)
     throw new Error("[stitchkit] managed CLI executable invariant failed");
   const prepared = await prepareInvocation(command, route.commandArgv, descriptor, config, readStdin);
   if (!prepared.ok) {
@@ -2233,6 +2468,10 @@ async function runManagedCommand(session, route, command, managed) {
 `);
     return exit(0);
   }
+  if (stream)
+    return runStreamCommand(session, route, managed, stream, { toolArgs, options });
+  if (!tool)
+    throw new Error("[stitchkit] managed CLI executable invariant failed");
   const result = await executeManagedTool(session, route, command, managed, tool, {
     toolArgs,
     options
@@ -2269,8 +2508,11 @@ async function executeManagedTool(session, route, command, managed, tool, { tool
         if (!pollTool) {
           return {
             ok: false,
-            code: "NOT_FOUND",
-            details: { message: `--wait: no command "${toolName}" to poll` }
+            code: "UNKNOWN_OPERATION",
+            details: {
+              message: `--wait: no command "${toolName}" to poll`,
+              operation: toolName
+            }
           };
         }
         return runTool(pollTool, args);
@@ -2314,7 +2556,8 @@ async function emitManagedResult(session, command, initial, options, repeatable)
     }
     result = { ...result, data: viewed.data };
   }
-  const exitCode = emitResult2(result, { stdout, stderr }, emitOptionsFor(config, options.json, command));
+  const policy = options.view === undefined && !options.wait ? cliResultPolicy(config, command) : undefined;
+  const exitCode = emitCliCommandResult(policy, result, options, { stdout, stderr }, { ...emitOptionsFor(config, options.json, command), repeatable });
   return exit(downloadsOk ? exitCode : 1);
 }
 
@@ -2330,6 +2573,10 @@ async function runNativeCommand2(session, route, command, native) {
     stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
     return exit(0);
   }
+  if (route.schemaRequested) {
+    stdout(renderCommandSchema(command, descriptor));
+    return exit(0);
+  }
   const prepared = await prepareInvocation(command, commandArgv, descriptor, config, readStdin);
   if (!prepared.ok) {
     stderr(`${prepared.message}
@@ -2362,18 +2609,7 @@ async function runNativeCommand2(session, route, command, native) {
     return exit(0);
   }
   const result = await executeCliCommand(native, toolArgs, options, { stdout, stderr }, config.coerceJsonArgs ?? true, globals);
-  const emission = prepareCliCommandEmission(native, result, options);
-  if (emission.result.ok && emission.presentationFailure !== undefined) {
-    return exit(emitPresentationFailure(emission.result, emission.presentationFailure, { stdout, stderr }, { ...emitOptionsFor(config, options.json, command), repeatable: false }));
-  }
-  let emittedExitCode;
-  if (emission.result.ok && emission.presentation !== undefined) {
-    stdout(emission.presentation);
-    emittedExitCode = 0;
-  } else {
-    emittedExitCode = emitResult2(emission.result, { stdout, stderr }, emitOptionsFor(config, options.json, command));
-  }
-  return exit(emission.result.ok ? emission.successExitCode : emittedExitCode);
+  return exit(emitCliCommandResult(cliCommandResultPolicy(native), result, options, { stdout, stderr }, { ...emitOptionsFor(config, options.json, command), repeatable: false }));
 }
 
 // src/tools/cli/create-cli.ts
@@ -2395,4 +2631,4 @@ async function createCli2(config) {
   return runManagedInvocation(session, route);
 }
 
-export { defineCliCommand2, DEFAULT_EXIT_CODES2, cliExitCode2, emitResult2, CliArgumentError2, cliInvocationResult2, createCliInvoker2, routeCliArgv2, parseCliArgs2, extractCliGlobalOptions2, renderCliView2, pollUntilDone2, createCli2 };
+export { DEFAULT_EXIT_CODES2, cliExitCode2, emitResult2, defineCliResult2, defineCliCommand2, CliArgumentError2, cliInvocationResult2, createCliInvoker2, routeCliArgv2, parseCliArgs2, extractCliGlobalOptions2, renderCliView2, pollUntilDone2, createCli2 };