stitchkit 0.90.3 → 0.90.5

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

@@ -0,0 +1,44 @@
+/**
+ * What a discovered MCP tool's answer is, per transport.
+ *
+ * `tools/call` returns an envelope — `{ content: [...], structuredContent? }` —
+ * and an agent mount needs exactly that: the parts are what a model is shown.
+ * The CLI transport is different in kind, because the handler's value is what
+ * gets printed, piped and aggregated. Handed the envelope, `--count-by status`
+ * groups the *parts* and answers `no record carries the field "status" —
+ * available: text, type`, and `--json` emits the answer as a JSON string nested
+ * inside `content[0].text`, so every consumer unwraps before anything works.
+ *
+ * So the CLI unwraps, and only the CLI. The order is the server's own order of
+ * preference: `structuredContent` is the answer when the server sent one; a lone
+ * text part is the answer when it parses as JSON, and its text when it does not.
+ * Anything else — several parts, an image, audio — is passed through whole,
+ * because picking one part out of many would be inventing an answer.
+ */
+import { AppError } from '../../contract/errors.js';
+export declare function unwrapMcpResult(result: unknown): unknown;
+/**
+ * The class a relayed failure carries when the server sent no structured body.
+ *
+ * Not `INTERNAL_SERVER_ERROR`: nothing of ours broke. The honest statement is
+ * that the call failed upstream and we cannot say more than the server did.
+ */
+export declare const UPSTREAM_TOOL_ERROR = "UPSTREAM_TOOL_ERROR";
+/**
+ * Turn a failed `CallToolResult` into the error the caller can act on.
+ *
+ * The line this replaces threw a one-sentence `Error` and discarded the result,
+ * which cost three things at once: the code (so `exitCodes` had nothing to map
+ * and every remote failure exited `1`), the message the operator needed, and the
+ * error's own class — a plain `Error` is an *unexpected* error to the runner, so
+ * it printed a code frame of the framework bundle before the JSON failure and
+ * was then scrubbed to a bare `INTERNAL_SERVER_ERROR`.
+ *
+ * A structured `{ error, details }` body is the remote contract's own refusal
+ * and is relayed as one. Anything else keeps the framework's sentence and
+ * carries what the server did send — reporting less than we have is not caution.
+ * The status is 502 either way: whatever the code says, the failure happened
+ * upstream, and a consumer re-serving it over HTTP should say so.
+ */
+export declare function mcpToolFailure(toolName: string, result: unknown): AppError;
+//# sourceMappingURL=mcp-envelope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-envelope.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/mcp-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAIjD,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAaxD;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,CAa1E"}

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;AAIhF,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,CAqElC"}

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-83fafqw8.js";
 import"./index-7rkhw9ec.js";
 import {
   argumentsDigest
@@ -37,7 +37,7 @@ import {
 } from "./index-4fpa9dy2.js";
 import {
   createToolInvoker
-} from "./index-79hb1wyh.js";
+} from "./index-tgh3ksfh.js";
 import {
   WaitTimeoutError,
   createCli,
@@ -46,22 +46,22 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-1923shw9.js";
+} from "./index-fqg5mfk7.js";
 import"./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-wb15909q.js";
+} from "./index-zsdgd1tz.js";
 import {
   collectTools,
   createToolRunner,
   formatToolError
-} from "./index-2hrfpw2c.js";
+} from "./index-1bnkzq95.js";
 import {
   ToolExecutionControlError,
   executeToolMethod,
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-44ht2790.js";
+} from "./index-8pjqv3zh.js";
 import {
   getRequestContext,
   getTraceId,
@@ -78,21 +78,16 @@ import {
   ManagedFilePathSchema,
   ManagedFileRefSchema
 } from "./index-6k1937bx.js";
-import {
-  AppError,
-  STITCH_ERROR_STATUS
-} from "./index-scs3f1eg.js";
 import {
   resolvePropagationContext
 } from "./index-zcgf3gqf.js";
 import {
   coerceJsonArgs
 } from "./index-7zbps32p.js";
-import"./index-kzfs85xp.js";
 import {
   createRuntimeToolFactory,
   defineRuntimeTool
-} from "./index-kc6h6hg0.js";
+} from "./index-8z9we758.js";
 import {
   PORTABLE_JSON_SCHEMA_FORMATS,
   assertToolName,
@@ -103,8 +98,13 @@ import {
   prepareProjectedMcpTools,
   presentationMetadata,
   validateMcpRoundPolicy
-} from "./index-r159gjwy.js";
+} from "./index-fenaekmk.js";
 import"./index-cby4ar3v.js";
+import {
+  AppError,
+  STITCH_ERROR_STATUS
+} from "./index-scs3f1eg.js";
+import"./index-kzfs85xp.js";
 import {
   isRecord
 } from "./index-77fekveh.js";

package/dist/tracking.js

@@ -5,8 +5,8 @@ import {
   defineContract
 } from "./index-kazec06k.js";
 import"./index-6k1937bx.js";
-import"./index-scs3f1eg.js";
 import"./index-zcgf3gqf.js";
+import"./index-scs3f1eg.js";
 import"./index-kzfs85xp.js";
 import"./index-77fekveh.js";
 

package/llms-full.txt

@@ -7489,6 +7489,13 @@ 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                |
+| `--help <text>`       | List only the commands matching a substring                |
+| `--count-by <field>`  | Count records per distinct value — see [Aggregate views](#aggregate-views) |
+| `--sum <f> [--by <g>]`| Total a numeric field, optionally grouped                  |
+| `--sort <field>`      | Order records by a field, largest first                    |
+| `--ascending`         | Flip `--sort` to smallest first                            |
+| `--top <n>`           | Keep the n leading entries of the view asked for           |
+| `--table <a,b>`       | Render 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,
@@ -7498,6 +7505,34 @@ 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`.
 
+### A narrower question than "all of them"
+
+On a discovered surface `--help` is the only way to learn what exists, and that
+can be two hundred commands. At that size the list stops being an answer: it
+scrolls past a person and costs an agent the same context an unfiltered result
+would. So there is a question between "one command" and "all of them":
+
+```bash
+myapp --help broadcast     # also: -h broadcast · help broadcast · --help=broadcast
+```
+
+```
+Commands matching "broadcast" (3 of 205):
+  broadcast_send    Send a broadcast to every subscriber
+  broadcast_cancel  Stop a running broadcast
+  announce_publish  Publish an announcement as a broadcast
+```
+
+The description is searched as well as the name, because the word someone knows
+is often in the sentence rather than the name — `announce_publish` above is
+matched that way. The count says what was left out.
+
+**No match is an exit code**, not an empty success: `0` over an empty list reads
+as "there are none", which is a different statement from "none of these". It
+exits with whatever `NOT_FOUND` maps to (`4` by default). Bare `--help` is
+unchanged, and `--help=false` still means what it always did — the reserved
+boolean's negation — so one value never carries two meanings.
+
 ## Application global options
 
 `--json` and friends above are the framework's. An application usually has
@@ -7603,6 +7638,211 @@ 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
+```
+
+Two words, one each: **`--by` groups, `--sort` orders.** That leaves `--top` a
+single meaning everywhere — *the n leading entries of the view you asked for* —
+so the question a CLI actually gets asked composes out of the parts:
+
+```bash
+myapp item_list --top 5 --sort messages --table id,messages   # the five biggest, as a table
+myapp item_list --sort messages --top 5 --json                # the same five, as records
+myapp item_list --sort name --ascending                       # ordered the other way
+```
+
+Groups come back largest first for the same reason. A record that carries no
+value for the sort field sorts **last in both directions**: it is not the
+smallest, it is not on the scale at all, and letting it lead an ascending list
+would answer a question nobody asked.
+
+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.
+- **Ordering and grouping do not mix.** `--sort` with `--by`, `--count-by` or
+  `--sum` is refused rather than given a second meaning.
+
+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: omit `asset` and one script covers every published target, selecting
+// by uname at run time — otherwise that dispatch is the last hand-written piece
+// of the install path, and every publisher writes the same x86_64 → x64 table.
+renderCliInstaller({ manifest, binaryName: 'myapp' })
+// Or pin one target explicitly:
+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.
+
+**A remote refusal keeps its code.** A failed `tools/call` used to become a
+one-sentence `Error` with the result discarded, which cost three things at once:
+the code (so `exitCodes` had nothing to map and every remote failure exited `1`),
+the message the operator needed, and the error's own class — a plain `Error` is
+an *unexpected* error to the runner, so it printed a code frame of the framework
+bundle before the JSON failure and was then scrubbed to `INTERNAL_SERVER_ERROR`.
+A structured `{ error, details }` body is now relayed as the contract error it
+is, on every transport; anything else fails as `UPSTREAM_TOOL_ERROR` carrying
+what the server did send. Not `INTERNAL_SERVER_ERROR`, because nothing of ours
+broke.
+
+**On the CLI a discovered command prints the answer, not the envelope.**
+`tools/call` returns `{ content: [...], structuredContent? }`, and an agent mount
+needs exactly that — the parts are what a model is shown. The CLI is different in
+kind, because the handler's value is what gets printed, piped and aggregated:
+handed the envelope, `--count-by status` groups the *content parts* and answers
+`no record carries the field "status" — available: text, type`. So the CLI
+transport unwraps, and only it: `structuredContent` when the server sent one, a
+lone text part when it parses as JSON, its text when it does not. Several parts,
+an image or audio pass through whole — picking one of many would be inventing an
+answer.
+
+
 ## Auth parity
 
 A scoped command is guarded by the same `createAuthHook` your HTTP server uses —
@@ -16710,13 +16950,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` |
 
 ---
 
@@ -17032,6 +17275,33 @@ 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, binary name, default install directory, and an optional `asset` — omit it for one script that selects the target by `uname` |
+| `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 view — `count`, `sum`, or `records` (ordered and/or table-rendered) |
+| `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 |

package/package.json

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