stitchkit 0.90.2 → 0.90.4

package/dist/tools/connections/mcp.d.ts

@@ -1,5 +1,6 @@
 import { type RuntimeToolDefinition } from '../runtime-tool.js';
+import { type ConnectionToolSkipReporter } from './runtime.js';
 import type { McpClientConnection } from './types.js';
 /** Discover and mount every tool one MCP connection exposes. */
-export declare function mountMcpConnection(connection: McpClientConnection, instanceId: string): Promise<RuntimeToolDefinition[]>;
+export declare function mountMcpConnection(connection: McpClientConnection, instanceId: string, onSkipped: ConnectionToolSkipReporter): Promise<RuntimeToolDefinition[]>;
 //# sourceMappingURL=mcp.d.ts.map

package/dist/tools/connections/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mcp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAMhF,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,SAAS,CAAC;AAQlE,gEAAgE;AAChE,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAyDlC"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mcp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGhF,OAAO,EACL,KAAK,0BAA0B,EAIhC,MAAM,WAAW,CAAC;AAGnB,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,SAAS,CAAC;AAQlE,gEAAgE;AAChE,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,0BAA0B,GACpC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAgElC"}

package/dist/tools/connections/mount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAM7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAE5E;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,SAAS,oBAAoB,EAAE,EAC5C,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,SAAS,qBAAqB,EAAE,CAAC,CAsB3C"}
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAO7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAE5E;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,SAAS,oBAAoB,EAAE,EAC5C,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,SAAS,qBAAqB,EAAE,CAAC,CAuB3C"}

package/dist/tools/connections/openapi.d.ts

@@ -1,5 +1,6 @@
 import { type RuntimeToolDefinition } from '../runtime-tool.js';
+import { type ConnectionToolSkipReporter } from './runtime.js';
 import type { OpenApiConnection } from './types.js';
 /** Load and mount every operation of one OpenAPI document. */
-export declare function mountOpenApiConnection(connection: OpenApiConnection, instanceId: string): Promise<RuntimeToolDefinition[]>;
+export declare function mountOpenApiConnection(connection: OpenApiConnection, instanceId: string, onSkipped: ConnectionToolSkipReporter): Promise<RuntimeToolDefinition[]>;
 //# sourceMappingURL=openapi.d.ts.map

package/dist/tools/connections/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/openapi.ts"],"names":[],"mappings":"AAGA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAchF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAgBjD,8DAA8D;AAC9D,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,iBAAiB,EAC7B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAkGlC"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/openapi.ts"],"names":[],"mappings":"AAGA,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAWhF,OAAO,EACL,KAAK,0BAA0B,EAKhC,MAAM,WAAW,CAAC;AAGnB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAgBjD,8DAA8D;AAC9D,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,iBAAiB,EAC7B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,0BAA0B,GACpC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CA4GlC"}

package/dist/tools/connections/runtime.d.ts

@@ -1,5 +1,6 @@
 import { type ZodObject } from 'zod';
 import type { RuntimeContext } from '../../contract/index.js';
+import type { RuntimeToolDefinition } from '../runtime-tool.js';
 /** A connection's optional principal-scoped credential resolver. */
 export type ConnectionTokenProvider = (context?: RuntimeContext) => string | undefined | Promise<string | undefined>;
 interface TeardownTarget {
@@ -25,5 +26,21 @@ export declare function withConnectionToken<T>(params: {
 export declare function zodObjectFromJsonSchema(schema: Record<string, unknown> | undefined): ZodObject;
 /** Normalise a tool name into the characters every provider accepts. */
 export declare function sanitizeToolName(value: string): string;
+/** One discovered tool the mount could not turn into a definition. */
+export interface SkippedConnectionTool {
+    connection: string;
+    tool: string;
+    reason: string;
+}
+export type ConnectionToolSkipReporter = (skipped: SkippedConnectionTool) => void;
+/** Default report: name the tool and the reason, and keep the connection. */
+export declare function reportSkippedConnectionTool(skipped: SkippedConnectionTool): void;
+/**
+ * Build one definition per discovered entry, surviving the ones that cannot be
+ * built. A mount is all-or-nothing only if it is written that way, and a foreign
+ * surface of two hundred tools should not be lost to one unconvertible schema —
+ * the refusal is reported and named, which is what a caller can act on.
+ */
+export declare function mountToolsTolerantly<TEntry>(entries: readonly TEntry[], connection: string, nameOf: (entry: TEntry) => string, build: (entry: TEntry) => RuntimeToolDefinition, onSkipped: ConnectionToolSkipReporter): RuntimeToolDefinition[];
 export {};
 //# sourceMappingURL=runtime.d.ts.map

package/dist/tools/connections/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAK,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGrD,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,CAAC,EAAE,cAAc,KACrB,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtD,UAAU,cAAc;IACtB,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,MAAM,EAAE;IACN,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,EACD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,SAAS,CAKX;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAK,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG7D,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,CAAC,EAAE,cAAc,KACrB,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtD,UAAU,cAAc;IACtB,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,MAAM,EAAE;IACN,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,EACD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,SAAS,CAKX;AAcD,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAElF,6EAA6E;AAC7E,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAIhF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EACzC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACjC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,qBAAqB,EAC/C,SAAS,EAAE,0BAA0B,GACpC,qBAAqB,EAAE,CAczB"}

package/dist/tools/connections/types.d.ts

@@ -1,4 +1,5 @@
-import type { ConnectionTokenProvider } from './runtime.js';
+import type { RuntimeToolTransport } from '../runtime-tool.js';
+import type { ConnectionTokenProvider, ConnectionToolSkipReporter } from './runtime.js';
 /** Where one external MCP server lives, plus static request headers. */
 export interface McpConnectionTransport {
     url: string;
@@ -23,6 +24,14 @@ export interface McpClientConnectionConfig {
     timeoutMs?: number;
     /** Response body ceiling in bytes; defaults to 1 MiB. */
     maxResponseBytes?: number;
+    /**
+     * Which surfaces this server's discovered tools appear on; default MCP and
+     * AGENT. Naming `['CLI']` is how a whole server becomes a set of commands,
+     * without the consumer rebuilding each discovered definition — and a
+     * connection without it contributes nothing to the CLI, because CLI exposure
+     * is explicit everywhere else in the framework too.
+     */
+    transports?: readonly RuntimeToolTransport[];
 }
 /** A defined MCP connection. */
 export interface McpClientConnection extends McpClientConnectionConfig {
@@ -40,6 +49,8 @@ export interface OpenApiConnectionConfig {
     timeoutMs?: number;
     /** Response body ceiling in bytes; defaults to 1 MiB. */
     maxResponseBytes?: number;
+    /** Which surfaces every mounted operation appears on; default MCP and AGENT. */
+    transports?: readonly RuntimeToolTransport[];
 }
 /** A defined OpenAPI connection. */
 export interface OpenApiConnection extends OpenApiConnectionConfig {
@@ -56,5 +67,11 @@ export interface ConnectionBudget {
 /** Shared mount policy for every connection in one call. */
 export interface ConnectionMountOptions {
     budget?: ConnectionBudget;
+    /**
+     * Called for each discovered tool that could not be mounted. Defaults to a
+     * stderr line naming the connection, the tool and the reason; the rest of the
+     * surface is mounted either way.
+     */
+    onSkippedTool?: ConnectionToolSkipReporter;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/tools/connections/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEzD,wEAAwE;AACxE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,sBAAsB,CAAC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,gCAAgC;AAChC,MAAM,WAAW,mBAAoB,SAAQ,yBAAyB;IACpE,IAAI,EAAE,KAAK,CAAC;CACb;AAED,kFAAkF;AAClF,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAkB,SAAQ,uBAAuB;IAChE,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAE3E,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAErF,wEAAwE;AACxE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,sBAAsB,CAAC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC9C;AAED,gCAAgC;AAChC,MAAM,WAAW,mBAAoB,SAAQ,yBAAyB;IACpE,IAAI,EAAE,KAAK,CAAC;CACb;AAED,kFAAkF;AAClF,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,UAAU,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC9C;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAkB,SAAQ,uBAAuB;IAChE,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAE3E,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;OAIG;IACH,aAAa,CAAC,EAAE,0BAA0B,CAAC;CAC5C"}

package/dist/tools/json-schema-dialect.d.ts

@@ -0,0 +1,17 @@
+/** True when a document says, in its own `$schema`, that it is draft-07. */
+export declare function declaresDraft07(dialect: unknown): boolean;
+/**
+ * Move a document's top-level `definitions` to `$defs`, carrying its pointers.
+ *
+ * A JSON Schema document that names one dialect and uses another's keyword is
+ * not a style question: a reader registers reusable subschemas from the keyword
+ * the dialect declares and then cannot resolve `#/definitions/x` at all. Both
+ * halves of this framework met that document — the MCP SDK stamps 2020-12 onto
+ * the metadata it is handed, and our own MCP client obeyed the stamp.
+ *
+ * Only the top level moves. A `definitions` deeper in the document may be a
+ * property literally called "definitions", and guessing which is worse than
+ * leaving it where the author put it.
+ */
+export declare function withDefsDialect(schema: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=json-schema-dialect.d.ts.map

package/dist/tools/json-schema-dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-dialect.d.ts","sourceRoot":"","sources":["../../src/tools/json-schema-dialect.ts"],"names":[],"mappings":"AAQA,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEzD;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUxF"}

package/dist/tools/presentation.d.ts

@@ -10,6 +10,13 @@ export interface ToolPresentationConfig {
 /** Build the one model-facing document shared by MCP, agents and manifests. */
 export declare function buildToolPresentationSchema(config: ToolPresentationConfig): ToolPresentationSchema;
 export declare function isObjectPresentationSchema(schema: ToolPresentationSchema): boolean;
-/** Metadata passed to the Zod identity carrier; the SDK supplies its own dialect. */
+/**
+ * Metadata passed to the Zod identity carrier.
+ *
+ * The SDK supplies its own dialect and it is 2020-12, so the document has to
+ * speak 2020-12: a draft-07 `definitions` block under a 2020-12 `$schema` is a
+ * document that says one thing and does another, and a client that believes the
+ * stamp cannot resolve a single `#/definitions/...` pointer in it.
+ */
 export declare function presentationMetadata(schema: ToolPresentationSchema): ToolPresentationSchema;
 //# sourceMappingURL=presentation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../src/tools/presentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,WAAW,CAAC;AAGnB,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IACzC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;CACnC;AA+FD,+EAA+E;AAC/E,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,sBAAsB,GAC7B,sBAAsB,CAgDxB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAElF;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAE3F"}
+{"version":3,"file":"presentation.d.ts","sourceRoot":"","sources":["../../src/tools/presentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,WAAW,CAAC;AAInB,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IACzC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;CACnC;AA+KD,+EAA+E;AAC/E,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,sBAAsB,GAC7B,sBAAsB,CAgDxB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAElF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAE3F"}

package/dist/tools.js

@@ -21,7 +21,7 @@ import {
   buildToolManifest,
   describeToolCatalog,
   mountAgent
-} from "./index-gbqjt8jz.js";
+} from "./index-19ryv24q.js";
 import"./index-7rkhw9ec.js";
 import {
   argumentsDigest
@@ -37,7 +37,7 @@ import {
 } from "./index-4fpa9dy2.js";
 import {
   createToolInvoker
-} from "./index-79hb1wyh.js";
+} from "./index-7t0wq6j5.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -46,22 +46,22 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-8dph3pw6.js";
+} from "./index-y47z614h.js";
 import"./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-wb15909q.js";
+} from "./index-kzxpsf8y.js";
 import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-2hrfpw2c.js";
+} from "./index-32vjke6q.js";
 import {
   ToolExecutionControlError,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-44ht2790.js";
+} from "./index-vcnfwrtr.js";
 import {
   getRequestContext,
   getTraceId,
@@ -92,7 +92,7 @@ import"./index-kzfs85xp.js";
 import {
   createRuntimeToolFactory,
   defineRuntimeTool
-} from "./index-kc6h6hg0.js";
+} from "./index-8z9we758.js";
 import {
   PORTABLE_JSON_SCHEMA_FORMATS,
   assertToolName,
@@ -103,7 +103,7 @@ import {
   prepareProjectedMcpTools,
   presentationMetadata,
   validateMcpRoundPolicy
-} from "./index-r159gjwy.js";
+} from "./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
 import {
   isRecord

package/llms-full.txt

@@ -7443,6 +7443,30 @@ command schema. `-f` / `-f=false` are boolean forms; values accept `-n 100` and
 bundles such as `-fn`, attached values such as `-n100`, `--no-f` and unknown
 short flags are rejected. Canonical `--no-follow` remains available.
 
+### A trailing list
+
+When the LAST declared positional is an array field, it takes every remaining
+token, each coerced by the array's element type:
+
+```ts
+positionals: { handoff: ['to', 'files'] }   // files: z.array(z.string())
+```
+
+```
+myapp handoff proj a.md b.md     → { to: 'proj', files: ['a.md', 'b.md'] }
+myapp handoff proj a.md          → { to: 'proj', files: ['a.md'] }
+```
+
+One token is a one-element list, not a scalar, so the parsed shape never depends
+on how many a caller happened to pass. Command help marks it:
+`Usage: myapp handoff <to> <files...>`. The flag form still works
+(`--files '["a.md","b.md"]'`, or a repeated `--files`) — but passing both forms
+in one call is an argument error rather than a silent merge.
+
+Only the trailing position is variadic. An array declared anywhere else in the
+list keeps taking exactly one token (a JSON array), and its help stays `<tags>`,
+so the usage line always says which field is the list.
+
 `positionals` replaces automatic schema-order selection only for the named
 command. An empty array disables argv positionals. Fields remain available as
 long/short options and stdin still fills the first required unset field with the
@@ -7465,6 +7489,10 @@ same Zod schema an HTTP or MCP call does.
 | `--quiet`             | Suppress non-essential stderr output                       |
 | `--dry-run`           | Print the resolved call without executing                  |
 | `--help`, `-h`        | Usage — top-level or per-command flag table                |
+| `--count-by <field>`  | Count records per distinct value — see [Aggregate views](#aggregate-views) |
+| `--sum <f> [--by <g>]`| Total a numeric field, optionally grouped                  |
+| `--top <n> --by <f>`  | Keep only the n largest groups                             |
+| `--table <a,b>`       | Render named fields as an aligned table                    |
 
 stdout carries the result; structured errors and progress go to stderr. With
 `--json`, a success or structured failure is exactly one compact,
@@ -7474,6 +7502,68 @@ diagnostics remain ordinary stderr text. This keeps stdout pipeable and
 `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`, `NOT_FOUND → 4`,
 …) — override per app with `exitCodes`.
 
+## Application global options
+
+`--json` and friends above are the framework's. An application usually has
+globals of its own — which identity key to use, which checkout a call speaks
+for, which profile — and they belong to no single operation:
+
+```ts
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  globalOptions: z.object({
+    caller: z.string().optional().describe('Identity key file'),
+    root: z.string().optional().describe('Checkout the call speaks for'),
+  }),
+  resolveAuth: (globals) => loadIdentity(globals.caller),
+  context: (auth, globals) => ({ auth, root: globals.root }),
+  runtimeTools: (auth) => catalogFor(auth),
+})
+```
+
+```
+myapp --root /srv/app handoff_read --handoffId u
+myapp handoff_read --root /srv/app --handoffId u   # the same call
+```
+
+These flags are lifted out of argv wherever they stand — before or after the
+command name — validated against the declared schema, and kept out of every
+operation's arguments: `handoff_read` above receives `{ handoffId: 'u' }` and
+nothing else. The values reach `resolveAuth(globals)`, `context(auth, globals)`
+and a native command's `globals`. An invalid value is an argument error naming
+the flag; a name that collides with a framework option, or with a field of any
+command, is refused at startup rather than shadowing it silently. Past a bare
+`--` every token is a literal, so a positional value that reads like a global
+survives intact.
+
+Both help levels list them under `Application options:`.
+
+## When the managed surface cannot resolve
+
+A CLI whose commands come from a running server declares them with a factory,
+and that factory needs an identity. When `resolveAuth` fails — the server is
+down, the key file is missing — the commands it would have named are unknown to
+the CLI, but the native ones are not:
+
+```
+$ myapp --help
+myapp 1.0.0
+...
+Commands:
+  serve  Run the server
+
+Managed commands are unavailable: UNREACHABLE: socket closed
+```
+
+Help still lists what does not depend on identity and says, in one line, why the
+rest is missing. Calling a name the CLI cannot resolve answers with that same
+refusal and the exit code its error class declares through `exitCodes` — never
+`Unknown command`, which would claim the name does not exist when the truth is
+that it could not be looked up. A native command and its help still run: they
+never needed an identity. Identity is still resolved at most once per
+invocation, failure included.
+
 Per-command help derives the positional form from the same resolved policy as
 the argv parser. For example, a required `action` and optional `profile` render as
 `Usage: myapp skill <action> [profile] [--flags]`; the argument table also shows
@@ -7517,6 +7607,172 @@ myapp generate "a fox" --wait --output-dir ./out
 myapp generate "a fox" --wait --json > result.json &
 ```
 
+## Aggregate views
+
+The CLI's audience is agents, scripts and `jq`, so output is JSON. That settles
+the *encoding*; it does not settle whether the answer to "how many items per
+status" should be every item. Measured on a live server, one ordinary question:
+
+| call | characters returned |
+|---|---|
+| the listing (98 records) | 34 750 |
+| `--count-by status` | ~90 |
+
+An agent pays for every one of those characters in its context window, and `|
+jq` does not help: the bytes have been read into the conversation by the time
+`jq` sees them. So the aggregate is computed on the result, before anything is
+written.
+
+```bash
+myapp item_list --count-by status          # { "active": 33, "idle": 33, "stopped": 32 }
+myapp item_list --count-by status --top 2  # the two largest groups
+myapp item_list --sum messages             # 4753
+myapp item_list --sum messages --by status # one total per status
+myapp item_list --top 5 --by status        # same view, written the other way round
+myapp item_list --table id,status          # the one human-facing shape
+```
+
+`--by` always names the **grouping** field, in every form it appears in, so the
+grammar has one meaning rather than two. Groups are ordered largest first, which
+is what makes `--top` a defined slice rather than an arbitrary one.
+
+Three rules worth knowing before you rely on them:
+
+- **A field the result does not carry is an argument error.** A group of zero
+  over a misspelled field is indistinguishable from a true empty answer, and the
+  caller reads it as data. The message names the fields that *are* there.
+- **An aggregate needs a collection** — the result itself when it is an array,
+  or the single array field of a result object. An aggregate over a scalar, or
+  over an object with two array fields, is refused rather than guessed.
+- **Without a view flag the output is byte-for-byte what it was.** The flags are
+  reserved CLI behaviour like `--json`; they never reach a tool argument.
+
+A failed call still reports its own error and exit code. An aggregate over an
+error is not an answer to the question that was asked.
+
+## Named profiles
+
+A CLI that talks to a deployed server needs an address and a credential per
+environment, and the way a person picks one is a name: `--profile prod`.
+`globalOptions` gives the flag a home and `resolveAuth(globals)` gives it a
+resolution point. The rule that makes the mechanism safe is easy to write the
+wrong way round, because the unsafe version reads as kindness:
+
+> the named profile does not exist, but exactly one profile is configured — use it.
+
+That is correct exactly while a single profile exists. The day a second appears
+it is a command run against the wrong deployment, with nothing in the output to
+say so. **A profile named explicitly and not found is a refusal, never a
+substitution.** Substitution survives only where it cannot be wrong: no name was
+given at all and exactly one profile exists — and even then it is announced on
+stderr. The distinction has to be drawn at resolution; one step later, "prod" and
+"prod by default" are the same string.
+
+`createCliProfileStore` is that rule, plus the twenty lines every consumer of
+this shape writes:
+
+```ts
+import { createCliProfileStore } from 'stitchkit/cli'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { z } from 'zod'
+
+const profiles = createCliProfileStore({
+  directory: join(homedir(), '.config/myapp/profiles'),
+  schema: z.object({ url: z.url(), token: z.string().min(1) }),
+  createHint: (name, path) => `write ${path} with {"url","token"} for "${name}"`,
+})
+
+await createCli({
+  name: 'myapp',
+  version,
+  globalOptions: z.object({ profile: z.string().optional() }),
+  resolveAuth: (globals) => profiles.resolve(globals.profile).value,
+  services,
+})
+```
+
+Files are written `0600` in a `0700` directory — and a profile file other users
+can read is refused with the `chmod` that fixes it, because it holds a
+credential.
+
+## Distribution and self-update
+
+`createCli` ships no executable, and that is right — but the step after the
+executable is not application logic either. It is the same problem for every
+consumer, with the same three traps:
+
+1. **The installer cannot parse the manifest.** A `curl … | sh` runs on a
+   machine where nothing is installed yet, including `jq`. So the installer is
+   generated *from* the manifest, server-side, with the URL and digest already
+   substituted — it parses no JSON at all.
+2. **Replacing a running binary is a rename, not a write.** Anything else can
+   leave a half-written executable on someone's PATH when the connection drops.
+3. **The digest covers the decompressed bytes** — the file that will actually be
+   executed, not the archive that was transferred.
+
+The framework owns the manifest shape, the installer generation and the update
+primitive. The application owns where the assets live, which platforms it
+publishes and who may download them.
+
+```ts
+import {
+  CliBuildManifestSchema, assertCliPublishable, renderCliInstaller,
+  selectCliBuildAsset, checkCliUpdate, applyCliUpdate,
+} from 'stitchkit/cli'
+
+// Publishing: refuse to republish one version from a different commit —
+// otherwise everyone who already installed it never receives the fix.
+assertCliPublishable(previous, next)
+
+// Serving: one generated script per target, no JSON on the wire.
+renderCliInstaller({ manifest, asset: selectCliBuildAsset(manifest, target)!, binaryName: 'myapp' })
+
+// Checking: bounded, at most once per interval, silent on any failure.
+const check = await checkCliUpdate({ manifestUrl, currentVersion, lastCheckedAt })
+if (check.status === 'outdated' && check.asset) {
+  // Replacing is always an explicit command, never a side effect of a check.
+  await applyCliUpdate({ asset: check.asset })
+}
+```
+
+`checkCliUpdate` has **four** answers, not three: `skipped`, `current`,
+`outdated` and `unknown`. "Could not ask" is not "up to date" — collapsing them
+is how a tool goes quiet about its own staleness for months. It never throws,
+and a command still exits with the code it earned.
+
+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.
+
+## Commands discovered from a running server
+
+A CLI compiled from contracts carries the surface of the build it was compiled
+from. One built from discovery carries the surface the server has *right now* —
+which matters, because a long-lived MCP client freezes schemas at connect time
+and then refuses the server's own newer fields:
+
+```ts
+const discovered = await mountConnections([
+  defineMcpClientConnection({
+    name: 'api',
+    transport: { url },
+    token: () => key,
+    transports: ['CLI'],   // the opt-in: this server's tools are commands
+  }),
+])
+await createCli({ name: 'myapp', version, runtimeTools: discovered, commands: [...] })
+```
+
+`transports` is where the opt-in belongs: a whole server becomes a set of
+commands, and a connection without it still contributes nothing to the CLI —
+exposure stays explicit, as it is everywhere else in the framework.
+
+One unconvertible schema no longer takes the connection down with it. The tool
+is skipped and **named** (`onSkippedTool`, or a stderr line by default), so a
+surface of two hundred tools is not lost to one.
+
+
 ## Auth parity
 
 A scoped command is guarded by the same `createAuthHook` your HTTP server uses —
@@ -16443,14 +16699,14 @@ payload.
 | `AgentToolRegistry` / `AgentToolRegistryBuilder` / `AgentToolRegistryInput` | _type_ | the composed runtime surface and its builder: declared defaults, `replace`/`disable` by name, and the exact `{ tools, names }` a mount receives |
 | `defineToolRegistry` | function | compose runtime tools over one declared default set; an unknown `replace`/`disable` name is refused instead of silently leaving the default in place |
 | `AgentContext` | _type_ | the context merged into agent tool handlers |
-| `CliConfig` | _type_ | config for `createCli`, including program-level `defaultCommand` selection and command-scoped `optionAliases` / `positionals` policy |
+| `CliConfig` | _type_ | config for `createCli`, including program-level `defaultCommand` selection, application-wide `globalOptions` and command-scoped `optionAliases` / `positionals` policy |
 | `CliPresentationPolicyConfig` | _type_ | reusable default-command, short-alias and explicit-positional policy inherited by `CliConfig` |
 | `CliSurfaceSource` | _type_ | static managed surface or identity-dependent surface factory for `createCli` |
 | `CliCommandDefinition` | _type_ | Zod-first CLI-only command union |
 | `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
 | `CliCommandDefinitionWithOutput` | _type_ | native command with declared output schema, validated handler result and typed optional `present` / `exitCode` callbacks |
 | `CliCommandDefinitionWithoutOutput` | _type_ | void native command with no output schema |
-| `CliCommandContext` | _type_ | parsed native command input, global options and injected writers |
+| `CliCommandContext` | _type_ | parsed native command input, framework run options, the application's `globals` and injected writers |
 | `CliWaitConfig` | _type_ | `--wait` polling config |
 | `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
 | `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
@@ -16624,13 +16880,16 @@ and approval path.
 | `ConnectionTokenProvider` | _type_ | `() => string \| undefined \| Promise<string \| undefined>` — the lazily resolved credential |
 | `ConnectionBudget` | _type_ | `{ maxTools? }` ceiling on one `mountConnections` call |
 | `ConnectionDefinition` | _type_ | either a defined MCP client or OpenAPI connection |
-| `ConnectionMountOptions` | _type_ | shared `{ lifecycle?, budget? }` mount policy |
+| `ConnectionMountOptions` | _type_ | shared `{ lifecycle?, budget?, onSkippedTool? }` mount policy |
+| `ConnectionToolSkipReporter` | _type_ | `(skipped) => void` — called per discovered tool the mount could not build; defaults to a stderr line, and the rest of the surface still mounts |
+| `SkippedConnectionTool` | _type_ | `{ connection, tool, reason }` — which tool was not mounted, and why |
+| `RuntimeToolTransport` | _type_ | `'MCP' \| 'AGENT' \| 'CLI'` — the surfaces a connection's `transports` may name |
 | `McpClientConnection` | _type_ | a defined MCP client connection |
-| `McpClientConnectionConfig` | _type_ | name, transport, tool filter, token provider, instance key and allowed hosts |
+| `McpClientConnectionConfig` | _type_ | name, transport, tool filter, token provider, instance key, allowed hosts and `transports` — naming `['CLI']` makes the whole server's discovered tools commands, with no per-definition rewriting |
 | `McpConnectionTransport` | _type_ | `{ url, headers? }` for one MCP endpoint |
 | `McpToolFilter` | _type_ | `{ allow?, block? }` discovered-tool filter |
 | `OpenApiConnection` | _type_ | a defined OpenAPI connection |
-| `OpenApiConnectionConfig` | _type_ | name, spec, base URL, token provider, instance key and allowed hosts |
+| `OpenApiConnectionConfig` | _type_ | name, spec, base URL, token provider, instance key, allowed hosts and `transports` |
 
 ---
 
@@ -16946,17 +17205,44 @@ SDK nor the `ai` peer.
 | `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
 | `parseCliArgs` | function | argv → typed tool args against a schema (advanced) |
+| `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |
+| `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
+| `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, without the `stitchkit/tools` barrel |
+| `CliArgumentError` | class | the refusal `parseCliArgs` and the view flags raise; a CLI reports it and exits `2` |
+| `renderCliView` | function | compute an aggregate over a result (`--count-by`, `--sum`, `--top`, `--table`) — [guide](../guide/cli.md#aggregate-views) |
+| `createCliProfileStore` | function | named `0600` credential profiles resolved by name, with the never-substitute rule built in — [guide](../guide/cli.md#named-profiles) |
+| `CliProfileError` | class | an `AppError` refusing a named profile that is missing, unreadable or shared between users |
+| `renderCliInstaller` | function | generate the one-line installer from a build manifest, with the URL and digest substituted — [guide](../guide/cli.md#distribution-and-self-update) |
+| `checkCliUpdate` | function | bounded, interval-limited, never-throwing check for a newer published build |
+| `applyCliUpdate` | function | download, verify the decompressed digest and replace the binary by rename |
+| `assertCliPublishable` | function | refuse republishing one version from a different commit |
+| `selectCliBuildAsset` | function | the asset for one target, or `undefined` |
+| `currentCliBuildTarget` | function | `{ platform, arch }` of the running process |
+| `formatCliBuildStamp` | function | one line saying what the running build is |
+| `compareCliVersions` | function | compare two versions, or `undefined` when they are not comparable |
+| `CliBuildManifestSchema` / `CliBuildManifest` | schema / _type_ | name, version, commit, build time and assets |
+| `CliBuildAssetSchema` / `CliBuildAsset` | schema / _type_ | one download; `size` and `sha256` describe the **decompressed** bytes |
+| `CliBuildTargetSchema` / `CliBuildTarget` | schema / _type_ | `{ platform, arch }` |
+| `CliBuildStampSchema` / `CliBuildStamp` | schema / _type_ | the version/commit/build time carried inside a binary |
+| `CliInstallerConfig` | _type_ | manifest, asset, binary name and default install directory |
+| `CliUpdateCheckConfig` / `CliUpdateCheck` | _type_ | check inputs, and its four answers — `skipped`, `current`, `outdated`, `unknown` |
+| `CliUpdateApplyConfig` / `AppliedCliUpdate` | _type_ | apply inputs and the replaced path, byte count and digest |
+| `CliProfileStore` / `CliProfileStoreConfig` / `ResolvedCliProfile` | _type_ | the profile store, its directory/schema/hint config, and one resolution |
+| `CliResultView` | _type_ | the requested aggregate — `count`, `sum` or `table` |
+| `CliViewOutput` | _type_ | a JSON value, or the one human-facing text shape |
+| `CliGlobalOptionsParse` | _type_ | `{ argv, globals }` returned by `extractCliGlobalOptions` |
+| `CliArgvRoute` | _type_ | `{ command, commandArgv, topLevelHelp, version, error? }` returned by `routeCliArgv` |
 | `pollUntilDone` | function | the generic `--wait` poller (advanced) |
 | `emitResult` | function | write a pretty or compact `ToolResult` record to stdout/stderr + exit code (advanced) |
 | `DEFAULT_EXIT_CODES` | const | the default `ToolResult.code` → exit-code map |
-| `CliConfig` | _type_ | config for `createCli`; `defaultCommand`, `optionAliases` and `positionals` define the shared command presentation policy |
+| `CliConfig` | _type_ | config for `createCli`; `defaultCommand`, `globalOptions`, `optionAliases` and `positionals` define the shared command presentation policy |
 | `CliPresentationPolicyConfig` | _type_ | shared command presentation-policy subset of `CliConfig` |
 | `CliSurfaceSource` | _type_ | static service/runtime array or identity-dependent factory |
 | `CliCommandDefinition` | _type_ | native command definition union |
 | `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
 | `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output and typed optional `present` / successful `exitCode` callbacks |
 | `CliCommandDefinitionWithoutOutput` | _type_ | native void command without an output contract |
-| `CliCommandContext` | _type_ | parsed input, global options and stdout/stderr writers |
+| `CliCommandContext` | _type_ | parsed input, framework run options, the application's `globals` and stdout/stderr writers |
 | `CliRunOptions` | _type_ | parsed global flags (`--json` compacts success/error records, `--wait`, …) |
 | `ParsedCliArgs` | _type_ | result of `parseCliArgs` |
 | `CliWaitConfig` | _type_ | per-command `--wait` polling config; optional `failed(result)` maps a terminal domain failure to `WAIT_FAILED` and a non-zero exit |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.90.2",
+  "version": "0.90.4",
   "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",