stitchkit 0.92.0 → 0.93.0

package/CHANGELOG.md

@@ -15,6 +15,63 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.93.0] — 2026-09-22
+
+### ⚠️ Breaking changes
+
+- **The surface snapshot records what an operation asks before it runs, and
+  `manifestVersion` is `3`.** `mcp.inputRequired` changes the contract a host is
+  coded against — an operation gains or loses a question — and the snapshot did
+  not move a byte for it. Measured on 0.92.0: the same operation with and
+  without a declared round produced byte-identical manifests, so a consumer was
+  holding the link "declared → state key configured" with a test of their own.
+  An operation row now carries `mcp`: `null`, a list of `{key, message, schema}`,
+  or `'resolved-per-call'` when a resolver decides them. A committed snapshot on
+  an older version is refused by name, with the remedy in the message.
+  `// before: manifest.operations[0]  // no trace of a declared round` →
+  `// after:  manifest.operations[0].mcp  // null | [{ key, message, schema }] | { inputRequired: 'resolved-per-call' }`
+  → ADR 0195
+
+**Who must act:** anyone with a committed surface snapshot — regenerate it once
+and review the diff, which is large because the field is added to every
+operation row, most of them `null`; and anyone whose own test held the link
+between a declared `inputRequired` and its configured state key, who can now
+drop it.
+
+### Added
+
+- **A native command that returns a result is invokable in process.**
+  `createCliInvoker` excluded `config.commands` wholesale, on the reasoning that
+  a native command prints by construction. That is true of the half declaring
+  `output?: never` and was applied to both halves; a consumer measured six of
+  their eight native commands declaring `output`, and a `describe` line that had
+  worked in their stream began answering `NOT_FOUND`. The invoker now admits a
+  native command if and only if it declares `output`. `present` is not called —
+  it is stdout formatting and there is no stdout — while `exitCode` is applied
+  through the same function the command line uses. Whatever a handler writes
+  comes back as `CliInvocationResult.written` instead of interleaving with the
+  caller's own output. A printing command is still outside, now for its own
+  reason. → ADR 0194
+
+- **`SURFACE_MANIFEST_VERSION`, `SurfaceManifestOperationMcp` and
+  `SurfaceManifestOperationMcpSchema`** from `stitchkit/testing`, for reading
+  and asserting the new row.
+
+### Changed
+
+- **`CliConfig.commands` moved to `CliInvokerConfig`.** One declaration for both
+  surfaces; `createCli` keeps the field it always had.
+
+- **An update check refused by the SSRF boundary names the field that lifts it.**
+  A self-hosted deployment serves its manifest from its own network, the check
+  has `allowPrivateHosts` for exactly that, and the refusal relayed the guard's
+  own sentence — which reads like a timeout, so the deployment goes quietly
+  stale. The reason now says the endpoint is not public, names the field, and
+  says why `applyCliUpdate` keeps its own setting: a manifest URL is
+  configuration you wrote, an asset URL arrives inside a document. Only
+  address-privacy refusals get this; a refusal the field cannot lift keeps its
+  own reason.
+
 ## [0.92.0] — 2026-09-22
 
 ### ⚠️ Breaking changes

package/dist/cli.js

@@ -1,6 +1,7 @@
 import {
   CliArgumentError,
   DEFAULT_EXIT_CODES,
+  PrivateAddressRefusal,
   cliExitCode,
   cliInvocationResult,
   createCli,
@@ -14,7 +15,7 @@ import {
   readCapped,
   renderCliView,
   routeCliArgv
-} from "./index-7n145nbe.js";
+} from "./index-3bmnp41g.js";
 import {
   serializeCanonicalJson
 } from "./index-0j3vcp5m.js";
@@ -636,6 +637,12 @@ async function checkCliUpdate(config) {
       signature: verdict
     };
   } catch (error) {
+    if (error instanceof PrivateAddressRefusal) {
+      return {
+        status: "unknown",
+        reason: `${error.message} — the manifest endpoint is not public. Set ` + "`allowPrivateHosts` if it is your own deployment; the download keeps " + "its own setting, because an asset URL comes from the document."
+      };
+    }
     return {
       status: "unknown",
       reason: error instanceof Error ? error.message : String(error)

package/dist/{index-7n145nbe.js → index-3bmnp41g.js}

@@ -669,15 +669,22 @@ function resolveCliView(flags, ascending) {
 function defineCliCommand(definition) {
   return definition;
 }
+function cliCommandReturnsResult(definition) {
+  return definition.output !== undefined;
+}
+function cliCommandSuccessExitCode(definition, data) {
+  const successExitCode = definition.exitCode?.(data) ?? 0;
+  if (!Number.isSafeInteger(successExitCode) || successExitCode < 0 || successExitCode > 255) {
+    throw new Error("CLI success exit code must be an integer from 0 to 255");
+  }
+  return successExitCode;
+}
 function prepareCliCommandEmission(definition, result, options) {
   if (!result.ok || definition.output === undefined) {
     return { result, successExitCode: 0 };
   }
   try {
-    const successExitCode = definition.exitCode?.(result.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");
-    }
+    const successExitCode = cliCommandSuccessExitCode(definition, result.data);
     const presentation = definition.present?.({ result: result.data, options });
     if (presentation !== undefined && typeof presentation !== "string") {
       throw new Error("CLI result presenter must return a string");
@@ -877,6 +884,11 @@ function cliInvocationResult(result, toolName, config) {
 async function createCliInvoker(config, globals) {
   const typedGlobals = parseCliGlobals(config.globalOptions, globals);
   const auth = await (config.resolveAuth ? config.resolveAuth(typedGlobals) : config.auth);
+  const natives = new Map((config.commands ?? []).filter(cliCommandReturnsResult).map((definition) => [definition.name, definition]));
+  const nativeHelp = new Map([...natives].map(([name, definition]) => [
+    name,
+    { description: definition.description, argumentSchema: {}, presentationSchema: {} }
+  ]));
   const { tools, help } = buildCliSurface(config, auth, new Map, new Set);
   const runTool = createToolRunner({
     source: "cli",
@@ -887,11 +899,14 @@ async function createCliInvoker(config, globals) {
     coerceJsonArgs: config.coerceJsonArgs
   });
   return {
-    commands: [...help].map(([name, presentation]) => ({
+    commands: [...nativeHelp, ...help].map(([name, presentation]) => ({
       name,
       description: presentation.description
     })),
     invoke: async (command, args) => {
+      const native = natives.get(command);
+      if (native)
+        return runNativeCommand(native, args, config, typedGlobals);
       const tool = tools.get(command);
       if (!tool) {
         return cliInvocationResult({
@@ -910,6 +925,42 @@ async function createCliInvoker(config, globals) {
     }
   };
 }
+var IN_PROCESS_RUN_OPTIONS = Object.freeze({
+  json: false,
+  wait: false,
+  quiet: true,
+  dryRun: false,
+  help: false
+});
+async function runNativeCommand(definition, args, config, globals) {
+  let out = "";
+  let err = "";
+  const result = await executeCliCommand(definition, args, IN_PROCESS_RUN_OPTIONS, {
+    stdout: (text) => {
+      out += text;
+    },
+    stderr: (text) => {
+      err += text;
+    }
+  }, config.coerceJsonArgs ?? true, globals);
+  let invocation = cliInvocationResult(result, definition.name, config);
+  if (invocation.ok) {
+    try {
+      invocation = {
+        ...invocation,
+        exitCode: cliCommandSuccessExitCode(definition, result.ok ? result.data : undefined)
+      };
+    } catch (error) {
+      invocation = cliInvocationResult(toolResultFromError(error), definition.name, config);
+    }
+  }
+  if (out === "" && err === "")
+    return invocation;
+  return {
+    ...invocation,
+    written: { ...out !== "" && { stdout: out }, ...err !== "" && { stderr: err } }
+  };
+}
 function buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, assertShape) {
   const services = typeof config.services === "function" ? config.services(auth) : config.services ?? [];
   const runtimeTools = typeof config.runtimeTools === "function" ? config.runtimeTools(auth) : config.runtimeTools ?? [];
@@ -1398,6 +1449,10 @@ async function fetchGuarded(start, allowPrivate, options = {}) {
       clearTimeout(headerTimer);
   }
 }
+
+class PrivateAddressRefusal extends Error {
+  name = "PrivateAddressRefusal";
+}
 async function resolvePublicAddress(url, signal) {
   assertHttpUrl(url);
   const host = url.hostname.replace(/^\[|\]$/g, "");
@@ -1406,20 +1461,20 @@ async function resolvePublicAddress(url, signal) {
   const ipFamily = isIP(host);
   if (ipFamily) {
     if (isPrivateIp(host))
-      throw new Error("refusing to fetch a private address");
+      throw new PrivateAddressRefusal("refusing to fetch a private address");
     return { address: host, family: ipFamily === 6 ? 6 : 4 };
   }
   if (NUMERIC_HOST.test(host)) {
-    throw new Error("refusing to fetch a non-canonical numeric host");
+    throw new PrivateAddressRefusal("refusing to fetch a non-canonical numeric host");
   }
   if (host === "localhost" || host.endsWith(".local") || host.endsWith(".internal")) {
-    throw new Error("refusing to fetch an internal host");
+    throw new PrivateAddressRefusal("refusing to fetch an internal host");
   }
   const pending = lookup(host, { all: true });
   const records = signal ? await raceWithAbort(pending, signal) : await pending;
   for (const record2 of records) {
     if (isPrivateIp(record2.address)) {
-      throw new Error("refusing to fetch a host that resolves to a private address");
+      throw new PrivateAddressRefusal("refusing to fetch a host that resolves to a private address");
     }
   }
   const record = records[0];
@@ -2111,4 +2166,4 @@ async function createCli(config) {
   return exit(downloadsOk ? exitCode : 1);
 }
 
-export { WaitTimeoutError, runWaitOperation, fetchGuarded, fetchPinnedDocument, readCapped, routeCliArgv, CliArgumentError, parseCliArgs, extractCliGlobalOptions, defineCliCommand, DEFAULT_EXIT_CODES, cliExitCode, emitResult, cliInvocationResult, createCliInvoker, renderCliView, pollUntilDone, createCli };
+export { WaitTimeoutError, runWaitOperation, fetchGuarded, PrivateAddressRefusal, fetchPinnedDocument, readCapped, routeCliArgv, CliArgumentError, parseCliArgs, extractCliGlobalOptions, defineCliCommand, DEFAULT_EXIT_CODES, cliExitCode, emitResult, cliInvocationResult, createCliInvoker, renderCliView, pollUntilDone, createCli };

package/dist/internal/secure-fetch.d.ts

@@ -52,6 +52,18 @@ export interface PinnedDocumentResponse {
     body: Uint8Array;
     url: URL;
 }
+/**
+ * The network boundary refused this address — as opposed to the network failing.
+ *
+ * A caller that offers a way through the boundary has to be able to tell the two
+ * apart, and matching on a message is not telling them apart: the wording is
+ * ours to change and a match on it breaks silently the moment it does. The class
+ * is the distinction, so a caller can name its own remedy instead of relaying a
+ * sentence that reads like a timeout.
+ */
+export declare class PrivateAddressRefusal extends Error {
+    readonly name = "PrivateAddressRefusal";
+}
 /**
  * Fetch a small public document while pinning the TCP connection to the exact
  * public DNS answer that passed validation. This closes the check/use DNS

package/dist/internal/secure-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-fetch.d.ts","sourceRoot":"","sources":["../../src/internal/secure-fetch.ts"],"names":[],"mappings":"AAiEA,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8D/C;AA4BD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,GAAG,EACV,YAAY,EAAE,OAAO,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAiDnB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;CACV;AAsCD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAkFjC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBnF"}
+{"version":3,"file":"secure-fetch.d.ts","sourceRoot":"","sources":["../../src/internal/secure-fetch.ts"],"names":[],"mappings":"AAiEA,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8D/C;AA4BD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,GAAG,EACV,YAAY,EAAE,OAAO,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAiDnB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,2BAA2B;CACzC;AA6CD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAkFjC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBnF"}

package/dist/testing/surface-manifest.d.ts

@@ -4,12 +4,30 @@ import type { RealtimeContract, RealtimeEventRegistry } from '../realtime/contra
 import type { RouteGroup, ServiceDef } from '../server/types.js';
 import type { CliCommandDefinition } from '../tools/cli-command.js';
 import { type McpSchemaValidationConfig, type SurfaceRuntimeToolDefinition, type SurfaceToolExtension } from '../tools/internal/surface-projector.js';
+/** The snapshot format's own version — bumped whenever an operation gains a field. */
+export declare const SURFACE_MANIFEST_VERSION = 3;
 export declare const SurfaceSchemaDigestsSchema: z.ZodObject<{
     params: z.ZodNullable<z.ZodString>;
     input: z.ZodNullable<z.ZodString>;
     output: z.ZodNullable<z.ZodString>;
     multipart: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * The questions an operation asks before it runs, as the host sees them.
+ *
+ * `null` means the operation declares no MCP policy at all. A list means those
+ * exact rounds; `'resolved-per-call'` means a resolver decides them and only
+ * the fact that it does is fixed at declaration time. Gaining, losing or
+ * changing any of this changes the contract a host is coded against, so it
+ * belongs in the snapshot that review reads.
+ */
+export declare const SurfaceManifestOperationMcpSchema: z.ZodNullable<z.ZodObject<{
+    inputRequired: z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        message: z.ZodString;
+        schema: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>, z.ZodLiteral<"resolved-per-call">]>;
+}, z.core.$strip>>;
 export declare const SurfaceManifestOperationSchema: z.ZodObject<{
     kind: z.ZodEnum<{
         contract: "contract";
@@ -33,6 +51,13 @@ export declare const SurfaceManifestOperationSchema: z.ZodObject<{
         output: z.ZodNullable<z.ZodString>;
         multipart: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>;
+    mcp: z.ZodNullable<z.ZodObject<{
+        inputRequired: z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            message: z.ZodString;
+            schema: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>, z.ZodLiteral<"resolved-per-call">]>;
+    }, z.core.$strip>>;
     http: z.ZodArray<z.ZodObject<{
         method: z.ZodEnum<{
             DELETE: "DELETE";
@@ -110,7 +135,7 @@ export declare const SurfaceManifestRealtimeEventSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const SurfaceManifestSchema: z.ZodObject<{
-    manifestVersion: z.ZodLiteral<2>;
+    manifestVersion: z.ZodLiteral<3>;
     digestVersion: z.ZodLiteral<1>;
     operations: z.ZodArray<z.ZodObject<{
         kind: z.ZodEnum<{
@@ -135,6 +160,13 @@ export declare const SurfaceManifestSchema: z.ZodObject<{
             output: z.ZodNullable<z.ZodString>;
             multipart: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>;
+        mcp: z.ZodNullable<z.ZodObject<{
+            inputRequired: z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                message: z.ZodString;
+                schema: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>, z.ZodLiteral<"resolved-per-call">]>;
+        }, z.core.$strip>>;
         http: z.ZodArray<z.ZodObject<{
             method: z.ZodEnum<{
                 DELETE: "DELETE";
@@ -201,6 +233,7 @@ export declare const SurfaceManifestSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type SurfaceManifest = z.infer<typeof SurfaceManifestSchema>;
 export type SurfaceManifestOperation = z.infer<typeof SurfaceManifestOperationSchema>;
+export type SurfaceManifestOperationMcp = z.infer<typeof SurfaceManifestOperationMcpSchema>;
 export type SurfaceManifestTool = z.infer<typeof SurfaceManifestToolSchema>;
 export type SurfaceManifestToolSurface = z.infer<typeof SurfaceManifestToolSurfaceSchema>;
 export type SurfaceManifestRealtimeEvent = z.infer<typeof SurfaceManifestRealtimeEventSchema>;

package/dist/testing/surface-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface-manifest.d.ts","sourceRoot":"","sources":["../../src/testing/surface-manifest.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"surface-manifest.d.ts","sourceRoot":"","sources":["../../src/testing/surface-manifest.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -35,5 +35,5 @@ export { type AgentRaceBarrier, type AgentRaceDriver, type AgentRaceTrace, type
 export { type AgentStoreConformanceConfig, type AgentStoreConformanceContext, runAgentStoreConformance, } from './testing/agent-store-conformance.js';
 export { type ManagedResourceConformanceConfig, type ManagedResourceConformanceControls, ManagedResourceConformanceError, type ManagedResourceConformanceFactoryInput, type ManagedResourceConformanceFixture, type ManagedResourceConformancePhase, ManagedResourceConformancePhaseSchema, type ManagedResourceConformanceScenario, type ManagedResourceConformanceScenarioId, ManagedResourceConformanceScenarioIdSchema, ManagedResourceConformanceScenarioSchema, type ManagedResourceConformanceTraceEntry, ManagedResourceConformanceTraceEntrySchema, type ManagedResourceConformanceTraceOutcome, ManagedResourceConformanceTraceOutcomeSchema, runManagedResourceConformance, } from './testing/managed-resource-conformance.js';
 export { assertSurfaceDiscovery, type ConformanceTransport, type CreateRealtimeProbeDriverConfig, createRealtimeProbeDriver, type DefineRealtimeProbeConfig, defineRealtimeProbe, type RealtimeDisconnectObservation, RealtimeDisconnectObservationSchema, type RealtimeProbeAdapter, type RealtimeProbeFixture, type RealtimeProbeScenario, type RealtimeRejectionObservation, RealtimeRejectionObservationSchema, type RunSurfaceProbesConfig, runSurfaceProbes, type SurfaceDiscoveryObservation, type SurfaceProbe, type SurfaceProbeDriver, type SurfaceRealtimeDiscoveryObservation, type SurfaceToolDiscoveryObservation, type TransportObservation, TransportObservationSchema, } from './testing/surface-conformance.js';
-export { assertSurfaceManifestSnapshot, buildSurfaceManifest, type IncompatibleSchemaPolicy, type McpSchemaValidationConfig, type SurfaceAgentProjection, type SurfaceManifest, type SurfaceManifestConfig, type SurfaceManifestExtension, SurfaceManifestExtensionSchema, type SurfaceManifestOperation, SurfaceManifestOperationSchema, type SurfaceManifestRealtimeEvent, SurfaceManifestRealtimeEventSchema, SurfaceManifestSchema, type SurfaceManifestTool, SurfaceManifestToolSchema, type SurfaceManifestToolSurface, SurfaceManifestToolSurfaceSchema, type SurfaceMcpPreparation, SurfaceRealtimeSchemaPairSchema, type SurfaceRuntimeToolDefinition, SurfaceSchemaDigestsSchema, type SurfaceToolDefinition, type SurfaceToolExtension, serializeSurfaceValue, } from './testing/surface-manifest.js';
+export { assertSurfaceManifestSnapshot, buildSurfaceManifest, type IncompatibleSchemaPolicy, type McpSchemaValidationConfig, SURFACE_MANIFEST_VERSION, type SurfaceAgentProjection, type SurfaceManifest, type SurfaceManifestConfig, type SurfaceManifestExtension, SurfaceManifestExtensionSchema, type SurfaceManifestOperation, type SurfaceManifestOperationMcp, SurfaceManifestOperationMcpSchema, SurfaceManifestOperationSchema, type SurfaceManifestRealtimeEvent, SurfaceManifestRealtimeEventSchema, SurfaceManifestSchema, type SurfaceManifestTool, SurfaceManifestToolSchema, type SurfaceManifestToolSurface, SurfaceManifestToolSurfaceSchema, type SurfaceMcpPreparation, SurfaceRealtimeSchemaPairSchema, type SurfaceRuntimeToolDefinition, SurfaceSchemaDigestsSchema, type SurfaceToolDefinition, type SurfaceToolExtension, serializeSurfaceValue, } from './testing/surface-manifest.js';
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/testing.js

@@ -1487,6 +1487,7 @@ import { z as z3 } from "zod";
 // src/testing/surface-manifest.ts
 import { createHash } from "node:crypto";
 import { z as z2 } from "zod";
+var SURFACE_MANIFEST_VERSION = 3;
 var HttpMethodSchema = z2.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
 var ToolTransportSchema = z2.enum(["MCP", "AGENT", "CLI"]);
 var SurfaceTransportSchema = z2.enum(["HTTP", "MCP", "AGENT", "CLI", "REALTIME"]);
@@ -1496,6 +1497,12 @@ var SurfaceSchemaDigestsSchema = z2.object({
   output: z2.string().nullable(),
   multipart: z2.string().nullable()
 });
+var SurfaceManifestOperationMcpSchema = z2.object({
+  inputRequired: z2.union([
+    z2.array(z2.object({ key: z2.string(), message: z2.string(), schema: z2.string().nullable() })),
+    z2.literal("resolved-per-call")
+  ])
+}).nullable();
 var SurfaceManifestOperationSchema = z2.object({
   kind: z2.enum(["contract", "runtime"]),
   service: z2.string(),
@@ -1504,6 +1511,7 @@ var SurfaceManifestOperationSchema = z2.object({
   scope: z2.string().nullable(),
   description: z2.string(),
   schemas: SurfaceSchemaDigestsSchema,
+  mcp: SurfaceManifestOperationMcpSchema,
   http: z2.array(z2.object({ method: HttpMethodSchema, path: z2.string() }))
 });
 var SurfaceManifestToolSchema = z2.object({
@@ -1540,7 +1548,7 @@ var SurfaceManifestRealtimeEventSchema = z2.object({
   acknowledgement: SurfaceRealtimeSchemaPairSchema.nullable()
 });
 var SurfaceManifestSchema = z2.object({
-  manifestVersion: z2.literal(2),
+  manifestVersion: z2.literal(SURFACE_MANIFEST_VERSION),
   digestVersion: z2.literal(1),
   operations: z2.array(SurfaceManifestOperationSchema),
   toolSurfaces: z2.array(SurfaceManifestToolSurfaceSchema),
@@ -1594,18 +1602,24 @@ function operationFrom(kind, source) {
       output: schemaDigest(source.outputSchema, "output"),
       multipart: multipartDigest(source.multipart)
     },
+    mcp: mcpRoundsOf(source),
     http: []
   };
 }
-function operationFingerprint(source) {
-  const declaredRounds = source.mcp ? staticInputRounds(source.mcp) : undefined;
-  const mcp = source.mcp ? {
-    inputRequired: declaredRounds ? declaredRounds.map((request) => ({
+function mcpRoundsOf(source) {
+  if (!source.mcp)
+    return null;
+  const declared = staticInputRounds(source.mcp);
+  return {
+    inputRequired: declared ? declared.map((request) => ({
       key: request.key,
       message: request.message,
       schema: schemaDigest(request.schema, "input")
     })) : "resolved-per-call"
-  } : null;
+  };
+}
+function operationFingerprint(source) {
+  const mcp = mcpRoundsOf(source);
   return serializeSurfaceValue({
     method: source.method,
     serviceName: source.serviceName,
@@ -1789,7 +1803,7 @@ function buildSurfaceManifest(config) {
     operation.http.sort((left, right) => compareCodepoints(left.path, right.path) || compareCodepoints(left.method, right.method));
   }
   return SurfaceManifestSchema.parse({
-    manifestVersion: 2,
+    manifestVersion: SURFACE_MANIFEST_VERSION,
     digestVersion: 1,
     operations: [...operations.values()].sort((left, right) => compareCodepoints(left.service, right.service) || compareCodepoints(left.action, right.action) || compareCodepoints(left.kind, right.kind)),
     toolSurfaces: toolSurfaces.sort((left, right) => compareCodepoints(left.transport, right.transport) || compareCodepoints(left.surface ?? "", right.surface ?? "")),
@@ -1800,6 +1814,10 @@ function buildSurfaceManifest(config) {
   });
 }
 function assertSurfaceManifestSnapshot(manifest, snapshot) {
+  const committed = snapshot.manifestVersion;
+  if (committed !== SURFACE_MANIFEST_VERSION) {
+    throw new Error(`Surface snapshot is manifestVersion ${String(committed)}; this build writes ` + `${SURFACE_MANIFEST_VERSION}. Regenerate it and review the diff — the format ` + "changed, so the first regeneration is expected to be large.");
+  }
   const actual = serializeSurfaceValue(SurfaceManifestSchema.parse(manifest));
   const expected = serializeSurfaceValue(SurfaceManifestSchema.parse(snapshot));
   if (actual !== expected) {
@@ -2177,7 +2195,9 @@ export {
   SurfaceManifestSchema,
   SurfaceManifestRealtimeEventSchema,
   SurfaceManifestOperationSchema,
+  SurfaceManifestOperationMcpSchema,
   SurfaceManifestExtensionSchema,
+  SURFACE_MANIFEST_VERSION,
   RealtimeRejectionObservationSchema,
   RealtimeDisconnectObservationSchema,
   ManagedResourceConformanceTraceOutcomeSchema,

package/dist/tools/cli-command.d.ts

@@ -44,6 +44,24 @@ export interface PreparedCliCommandEmission {
     presentation?: string;
     successExitCode: number;
 }
+/**
+ * Whether a native command yields a value at all.
+ *
+ * The two halves of `CliCommandDefinition` are not the same kind of thing: one
+ * returns a validated result and lets the frame print it, the other prints
+ * itself and returns nothing. Only the first can be executed somewhere that has
+ * no stdout to print to — an in-process invocation, a stream of JSON lines —
+ * and this is the test that decides it.
+ */
+export declare function cliCommandReturnsResult(definition: CliCommandDefinition): definition is CliCommandDefinitionWithOutput<ZodObject, ZodType>;
+/**
+ * The exit code a successful result earns, or a throw naming the offence.
+ *
+ * Shared, because a command run in process must exit-code identically to the
+ * same command typed at a prompt; two copies of this rule would eventually
+ * disagree and the divergence would show up as a script that branches wrong.
+ */
+export declare function cliCommandSuccessExitCode(definition: CliCommandDefinition, data: unknown): number;
 /** Apply native-only presentation policy after canonical output validation. */
 export declare function prepareCliCommandEmission(definition: CliCommandDefinition, result: ToolResult, options: Readonly<CliRunOptions>): PreparedCliCommandEmission;
 export declare function cliCommandPresentationSchema(definition: CliCommandDefinition): Record<string, unknown>;

package/dist/tools/cli-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-command.d.ts","sourceRoot":"","sources":["../../src/tools/cli-command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-command.d.ts","sourceRoot":"","sources":["../../src/tools/cli-command.ts"],"names":[],"mappings":"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"}

package/dist/tools/cli-invoke.d.ts

@@ -17,12 +17,22 @@
  * `createCli` is built on this same function, so the stream and the command
  * line cannot answer differently: one surface, one runner, one exit table.
  *
- * Native commands (`config.commands`) are deliberately outside it. They write
- * to stdout and stderr by construction — that is what they are — and an
- * operation that prints is not an operation whose result can be returned.
+ * Native commands (`config.commands`) are in it when, and only when, they
+ * declare `output`. The two halves of a native definition are not the same kind
+ * of thing: one returns a validated value the frame prints, the other prints
+ * itself and returns `void`. Only the second cannot be run where there is no
+ * stdout, and excluding both because of it cost a consumer a working `describe`
+ * line for no reason the type could not already tell apart.
+ *
+ * `present` is not called on this path: it is stdout formatting, and there is
+ * no stdout. `exitCode` is, through the same function the command line uses, so
+ * a script branching on the code cannot see the two paths disagree. Anything
+ * the handler does write is captured and returned on the result rather than
+ * leaking into a caller's stream of answers.
  */
 import type { ZodObject, z } from 'zod';
 import type { ServiceDef, StitchLogger } from '../server/types.js';
+import { type CliCommandDefinition } from './cli-command.js';
 import { type ExitCodeMap } from './cli-format.js';
 import { type CliCommandPresentation, type CliPresentationPolicyConfig } from './cli-policy.js';
 import { type ErrorHintFn, type ToolCallHooks, type ToolLifecycle, type ToolResult } from './execute.js';
@@ -41,6 +51,8 @@ export interface CliInvokerConfig<TAuth = unknown, TContext extends Record<strin
     services?: CliSurfaceSource<TAuth, ServiceDef>;
     /** Pathless managed operations. CLI exposure always requires `transports: ['CLI']`. */
     runtimeTools?: CliSurfaceSource<TAuth, RuntimeToolDefinition>;
+    /** CLI-only executable commands, dispatched before the managed surface. */
+    commands?: readonly CliCommandDefinition[];
     auth?: TAuth | Promise<TAuth>;
     resolveAuth?: (globals: z.output<TGlobals>) => TAuth | Promise<TAuth>;
     globalOptions?: TGlobals;
@@ -69,6 +81,19 @@ export interface CliInvocationResult {
         hint?: string;
         retryable?: boolean;
     };
+    /**
+     * What a native handler wrote, when it wrote anything.
+     *
+     * A command that declares `output` is not supposed to write — the frame
+     * prints for it — but it holds the writers and may log. In process there is
+     * nowhere for that text to go: printing it would interleave with a caller's
+     * own output and corrupt a stream of JSON lines, and dropping it would lose a
+     * diagnostic silently. So it comes back here, and the caller decides.
+     */
+    written?: {
+        stdout?: string;
+        stderr?: string;
+    };
 }
 /** One resolved managed command. */
 export interface CliInvokerCommand {

package/dist/tools/cli-invoke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-invoke.d.ts","sourceRoot":"","sources":["../../src/tools/cli-invoke.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-invoke.d.ts","sourceRoot":"","sources":["../../src/tools/cli-invoke.ts"],"names":[],"mappings":"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"}

package/dist/tools/cli-update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-update.d.ts","sourceRoot":"","sources":["../../src/tools/cli-update.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-update.d.ts","sourceRoot":"","sources":["../../src/tools/cli-update.ts"],"names":[],"mappings":"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"}

package/dist/tools/cli.d.ts

@@ -1,5 +1,4 @@
 import type { ZodObject, z } from 'zod';
-import { type CliCommandDefinition } from './cli-command.js';
 import { type ExitCodeMap } from './cli-format.js';
 import { type CliInvocationResult, type CliInvoker, type CliInvokerCommand, type CliInvokerConfig, type CliSurfaceSource, cliInvocationResult, createCliInvoker } from './cli-invoke.js';
 import { type CliWaitConfig } from './cli-wait.js';
@@ -9,8 +8,6 @@ export { cliInvocationResult, createCliInvoker };
 export interface CliConfig<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>, TGlobals extends ZodObject = ZodObject> extends CliInvokerConfig<TAuth, TContext, TGlobals> {
     /** Program version — printed by `--version`. */
     version: string;
-    /** CLI-only executable commands, dispatched before auth and managed surface factories. */
-    commands?: readonly CliCommandDefinition[];
     /**
      * Identity for the single CLI invocation — resolved ONCE at startup (from an
      * env var / token file), like a stdio MCP server, not per call. A value or a

package/dist/tools/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/tools/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/tools/cli.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -48,7 +48,7 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-7n145nbe.js";
+} from "./index-3bmnp41g.js";
 import {
   compareCodepoints,
   serializeCanonicalJson

package/llms-full.txt

@@ -66,11 +66,11 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 37 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 38 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 20 of the 37 minors since 0.56.2, most recently 0.89.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 20 of the 38 minors since 0.56.2, most recently 0.89.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults and deterministic race controls |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -80,7 +80,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 37 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 38 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -8070,6 +8070,30 @@ Carry the build stamp inside the binary (`CliBuildStampSchema`,
 `formatCliBuildStamp`) so the tool can say what it is rather than leaving the
 reader to infer it from behaviour.
 
+#### A manifest inside your own network
+
+The check goes through the same SSRF boundary every outbound fetch does, so a
+manifest served from `10.x`, `localhost` or a `.internal` name is refused and
+the answer is `unknown`. For a self-hosted deployment that is a wrong answer
+dressed as a careful one, and the refusal says so — it names the field that
+lifts it rather than reading like a timeout:
+
+```text
+refusing to fetch an internal host — the manifest endpoint is not public.
+Set `allowPrivateHosts` if it is your own deployment; the download keeps its
+own setting, because an asset URL comes from the document.
+```
+
+```ts
+const check = await checkCliUpdate({ manifestUrl, currentVersion, allowPrivateHosts: true })
+```
+
+Set it from whether **your** endpoint is private, not as a blanket switch, and
+leave `applyCliUpdate` at its default. The two are not the same decision: the
+manifest URL is configuration you wrote, while an asset URL arrives inside a
+document the endpoint served, and a document is exactly what an SSRF boundary
+exists to distrust.
+
 ### Proving who built it — signing the manifest
 
 The asset digest proves the bytes that arrived are the bytes the manifest named.
@@ -8190,6 +8214,39 @@ already holding, plus a process start measured at 0.15 s — thirty seconds for
 two-hundred-line manifest before any work begins. The ban on nesting one stream
 inside another was a consequence of that child process, not a rule anyone wanted.
 
+### Native commands in the stream
+
+A native command is in the invoker's surface when — and only when — it declares
+`output`:
+
+```ts
+const describe = defineCliCommand({
+  name: 'describe', description: 'Describe the catalogue',
+  input: z.object({ model: z.string() }),
+  output: z.object({ model: z.string(), ratios: z.array(z.string()) }),
+  handler: ({ input }) => ({ model: input.model, ratios: ['1:1', '16:9'] }),
+})
+
+await createCliInvoker({ name: 'myapp', services, commands: [describe] })
+// invoke('describe', { model: 'flux' }) → { ok: true, exitCode: 0, data: { … } }
+```
+
+A command that declares `output?: never` prints itself and returns nothing, so
+there is no result to hand back; it answers `NOT_FOUND` and stays on the command
+line, where stdout exists. Your stream command is one of these, which is why a
+stream still cannot invoke itself.
+
+On this path `present` is not called — it is stdout formatting, and there is no
+stdout — while `exitCode` is applied through the same function the command line
+uses, so a script branching on the code sees one answer from both. Anything the
+handler writes comes back as `written` rather than interleaving with your own
+output:
+
+```ts
+const outcome = await invoker.invoke('describe', { model: 'flux' })
+outcome.written // { stderr: 'warming the cache\n' } — absent when nothing was written
+```
+
 ### Mounting the loop
 
 ```ts
@@ -12421,6 +12478,38 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.93.0
+
+1. **Regenerate every committed surface snapshot, once.** `manifestVersion` is
+   `3` and each operation row gained `mcp` — the rounds it declares before it
+   runs. Most rows get `null`, so the first diff is large and mechanical.
+   **Who must act:** anyone with a committed snapshot. A snapshot on the older
+   version is refused by name rather than failing a schema literal:
+
+   ```text
+   Surface snapshot is manifestVersion 2; this build writes 3. Regenerate it
+   and review the diff — the format changed, so the first regeneration is
+   expected to be large.
+   ```
+
+   ```ts
+   // before — a declared round left no trace, so declaring or removing one
+   // passed review invisibly
+   manifest.operations[0]
+   // after
+   manifest.operations[0].mcp
+   // null | { inputRequired: [{ key, message, schema }] }
+   //      | { inputRequired: 'resolved-per-call' }
+   ```
+
+   A project that kept its own test for "declared `inputRequired` implies a
+   configured state key" can drop it: the snapshot holds that link now.
+
+2. **Nothing else to do.** Native commands that declare `output` became
+   invokable in process; a name that answered `NOT_FOUND` from
+   `createCliInvoker` in 0.92.0 may now resolve. If an application relied on
+   native commands being unreachable there, stop passing them to the invoker.
+
 ## Released migration: 0.92.0
 
 1. **`RequestEvent.method`, `path` and `statusCode` are optional.** Work that did
@@ -17732,6 +17821,8 @@ handler pipeline without opening a TCP port.
 | `TransportObservation` | _type_ | validated normalized driver result |
 | `SurfaceManifest` / `SurfaceManifestConfig` | _type_ | deterministic surface snapshot and its inputs |
 | `SurfaceManifestOperation` / `SurfaceManifestOperationSchema` | _type_ / schema | one contract or runtime operation row |
+| `SurfaceManifestOperationMcp` / `SurfaceManifestOperationMcpSchema` | _type_ / schema | the rounds an operation declares before it runs: a fixed list, `'resolved-per-call'`, or `null` for no MCP policy |
+| `SURFACE_MANIFEST_VERSION` | const | the format version this build writes; a committed snapshot on an older one is refused by name |
 | `SurfaceManifestTool` / `SurfaceManifestToolSchema` | _type_ / schema | one mounted tool row with advertised input digest |
 | `SurfaceManifestToolSurface` / `SurfaceManifestToolSurfaceSchema` | _type_ / schema | one static transport projection, optionally keyed for a finite MCP surface |
 | `SurfaceManifestRealtimeEvent` / `SurfaceManifestRealtimeEventSchema` | _type_ / schema | one named directional realtime event with input/output args and ack digests |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.92.0",
+  "version": "0.93.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",