stitchkit 0.121.0 → 0.122.0

package/dist/server/openapi-security.d.ts

@@ -0,0 +1,73 @@
+/**
+ * How an OpenAPI document says what a protected operation needs from its
+ * caller: the standard `components.securitySchemes` and one `security`
+ * requirement per operation.
+ *
+ * The document describes the host's auth policy; it never enforces it. The
+ * runtime gate stays `createAuthHook` and its scope rules, so the mapping here
+ * is keyed by the same scope names the contracts already declare — no second
+ * copy of which endpoint is protected. The generator refuses to advertise a
+ * protected operation it cannot describe: a scope missing from the mapping
+ * would otherwise reach the spec as an open endpoint, and a generic client
+ * would call it without a credential.
+ */
+import { z } from 'zod';
+/** One way a request presents its credential — the OpenAPI Security Scheme Object. */
+export declare const OpenApiSecuritySchemeSchema: z.ZodUnion<readonly [z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"http">;
+    scheme: z.ZodLiteral<"bearer">;
+    bearerFormat: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"http">;
+    scheme: z.ZodLiteral<"basic">;
+}, z.core.$strict>, z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"apiKey">;
+    in: z.ZodEnum<{
+        cookie: "cookie";
+        header: "header";
+        query: "query";
+    }>;
+    name: z.ZodString;
+}, z.core.$strict>]>;
+export type OpenApiSecurityScheme = z.infer<typeof OpenApiSecuritySchemeSchema>;
+export declare const OpenApiSecuritySchema: z.ZodObject<{
+    schemes: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"http">;
+        scheme: z.ZodLiteral<"bearer">;
+        bearerFormat: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"http">;
+        scheme: z.ZodLiteral<"basic">;
+    }, z.core.$strict>, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"apiKey">;
+        in: z.ZodEnum<{
+            cookie: "cookie";
+            header: "header";
+            query: "query";
+        }>;
+        name: z.ZodString;
+    }, z.core.$strict>]>>;
+    scopes: z.ZodRecord<z.ZodString, z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    defaultScope: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OpenApiSecurity = z.infer<typeof OpenApiSecuritySchema>;
+/** The scope that needs no credential, as `createAuthHook` and the 401/403 responses read it. */
+export declare const PUBLIC_SCOPE = "public";
+/** A configuration checked once, before any operation is emitted. */
+export interface OpenApiSecurityPlan {
+    readonly schemes: Readonly<Record<string, OpenApiSecurityScheme>>;
+    /**
+     * The operation's `security` value, or `undefined` for an open one.
+     * `operation` names the endpoint in a refusal.
+     */
+    requirement(scope: string | undefined, operation: string): Array<Record<string, string[]>> | undefined;
+}
+/** Validate the host's security description, failing on the first contradiction. */
+export declare function planOpenApiSecurity(input: OpenApiSecurity): OpenApiSecurityPlan;
+//# sourceMappingURL=openapi-security.d.ts.map

package/dist/server/openapi-security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-security.d.ts","sourceRoot":"","sources":["../../src/server/openapi-security.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,sFAAsF;AACtF,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;oBActC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;kBAWhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,iGAAiG;AACjG,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAClE;;;OAGG;IACH,WAAW,CACT,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,EAAE,MAAM,GAChB,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;CAChD;AAMD,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,mBAAmB,CAsC/E"}

package/dist/server/openapi.d.ts

@@ -10,6 +10,7 @@
  * emits — not a divergent code path. Schemas are inlined (valid OpenAPI);
  * `$ref` de-duplication can come later if a spec grows unwieldy.
  */
+import { type OpenApiSecurity, type OpenApiSecurityScheme } from './openapi-security.js';
 import type { MethodDef, RawRoute, ServiceDef } from './types.js';
 export interface OpenApiInfo {
     title: string;
@@ -44,12 +45,23 @@ export interface OpenApiConfig {
      * separate filtered document for a public route (see the guide).
      */
     includeMethod?: (method: Readonly<MethodDef>) => boolean;
+    /**
+     * How a caller presents its credential, by the scopes the contracts already
+     * declare. Emits `components.securitySchemes` and a `security` requirement on
+     * every protected operation, so a generic client knows which header to send.
+     * Generation refuses a protected scope with no scheme rather than advertise
+     * the endpoint as open. Omit for a document without security metadata.
+     */
+    security?: OpenApiSecurity;
 }
 export interface OpenApiDocument {
     openapi: '3.1.0';
     info: OpenApiInfo;
     servers?: OpenApiServer[];
     paths: Record<string, Record<string, unknown>>;
+    components?: {
+        securitySchemes: Record<string, OpenApiSecurityScheme>;
+    };
 }
 /**
  * Generate an OpenAPI 3.1 document from contract services. Only methods exposed

package/dist/server/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAChE,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AA6DD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAsM9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,QAAQ,CAM9E"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAG3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAChE,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC;IACzD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/C,UAAU,CAAC,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAA;KAAE,CAAC;CACzE;AA4GD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAwK9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,QAAQ,CAM9E"}

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

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEjF,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAiHT"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEjF,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CA2HT"}

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

@@ -47,8 +47,17 @@ export interface EmitOptions {
  */
 export declare function cliExitCode(result: ToolResult, exitCodes?: ExitCodeMap): number;
 export declare function emitResult(result: ToolResult, writers: CliWriters, opts: EmitOptions): number;
-/** A presentation failure cannot erase a successfully completed operation. */
+/**
+ * A presentation failure cannot erase a successfully completed operation.
+ *
+ * A command with an effect prints its complete result, because a second call
+ * would repeat the effect instead of recovering the answer. A command that only
+ * reads withholds it: the answer is one corrected call away, and an unformatted
+ * payload is exactly what the caller asked not to receive.
+ */
 export declare function emitPresentationFailure(result: Extract<ToolResult, {
     ok: true;
-}>, failure: ToolFailure, writers: CliWriters, opts: EmitOptions): number;
+}>, failure: ToolFailure, writers: CliWriters, opts: EmitOptions & {
+    repeatable: boolean;
+}): number;
 //# sourceMappingURL=format.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGjE,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAmBhC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;;GAIG;AACH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CAY/E;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAeR;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC,EACzC,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAmBR"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGjE,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAmBhC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;;GAIG;AACH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CAY/E;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAeR;AAWD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC,EACzC,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAAG;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,GAC1C,MAAM,CAsBR"}

package/dist/tools/cli/repeatable-read.d.ts

@@ -0,0 +1,9 @@
+import type { OperationIdentity } from '../../server/types.js';
+/**
+ * Whether calling the operation again returns its answer without a new effect.
+ *
+ * The declared `readOnlyHint` decides in either direction; without one, `GET` is
+ * the contract's own statement that the endpoint reads.
+ */
+export declare function isRepeatableRead(operation: Pick<OperationIdentity, 'method' | 'annotations'>): boolean;
+//# sourceMappingURL=repeatable-read.d.ts.map

package/dist/tools/cli/repeatable-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeatable-read.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/repeatable-read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,aAAa,CAAC,GAC3D,OAAO,CAET"}

package/dist/tools/cli/run-managed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-managed.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/run-managed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAWrC,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAkB,MAAM,WAAW,CAAC;AAQ3E,wFAAwF;AACxF,wBAAsB,oBAAoB,CACxC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAC1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC1F"}
+{"version":3,"file":"run-managed.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/run-managed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAYrC,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAkB,MAAM,WAAW,CAAC;AAQ3E,wFAAwF;AACxF,wBAAsB,oBAAoB,CACxC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAC1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC1F"}

package/dist/tools/cli/run-native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-native.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/run-native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,EACL,KAAK,oBAAoB,EAG1B,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAkB,MAAM,WAAW,CAAC;AAE3E;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAyEf"}
+{"version":3,"file":"run-native.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/run-native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,EACL,KAAK,oBAAoB,EAG1B,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAkB,MAAM,WAAW,CAAC;AAE3E;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA0Ef"}

package/dist/tools/runtime-call-context.d.ts

@@ -0,0 +1,15 @@
+import type { McpReportProgress } from '../contract/runtime-context.js';
+import type { LocalStepDurability } from '../durability/contract.js';
+/** What the agent runtime hands one tool call beside the SDK's own options. */
+export interface RuntimeToolCall {
+    /** The run's step ledger; absent when the runtime runs without durability. */
+    durability?: LocalStepDurability;
+    /** Publishes the call's progress into the run's event stream — the handler's `ctx.reportProgress`. */
+    reportProgress: McpReportProgress;
+}
+type Factory = (callId: string, signal?: AbortSignal) => RuntimeToolCall;
+/** Opaque SDK context; no credentials, functions or runtime objects enter provider messages. */
+export declare function createRuntimeToolContext(factory: Factory): object;
+export declare function resolveRuntimeToolCall(context: unknown, callId: string, signal?: AbortSignal): RuntimeToolCall | undefined;
+export {};
+//# sourceMappingURL=runtime-call-context.d.ts.map

package/dist/tools/runtime-call-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-call-context.d.ts","sourceRoot":"","sources":["../../src/tools/runtime-call-context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,sGAAsG;IACtG,cAAc,EAAE,iBAAiB,CAAC;CACnC;AAED,KAAK,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,eAAe,CAAC;AAGzE,gGAAgG;AAChG,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAIjE;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,eAAe,GAAG,SAAS,CAG7B"}

package/llms/agent-runtime-browser.txt

@@ -25,7 +25,10 @@ including `AgentAttemptResetEventSchema` for `attempt-reset`),
 `AgentControlErrorCodeSchema` / `AgentControlErrorCode` (the one vocabulary of every control
 error code: `FORBIDDEN`, `CONNECTION_CLOSED`, `REQUEST_CAPACITY`, `ATTACHMENT_CAPACITY`,
 `LEASE_CONFLICT`, `EVENT_OVERFLOW` and the rest), `AgentMultiSessionCursorSchema` /
-`AgentMultiSessionCursor`, `AgentConversationView`, `AgentControlView`,
+`AgentMultiSessionCursor`, `AgentConversationView`, `AgentControlView`, `AgentRunTransient` (a
+run's streamed text, reasoning and running tool calls before its next checkpoint),
+`AgentToolActivity` (one running call with its last reported progress),
+`AGENT_TOOL_PROGRESS_MESSAGE_MAX` (the longest progress message a run publishes),
 `advanceAgentMultiSessionCursor`, `createAgentControlView`, `reduceAgentControlSnapshot`,
 `reduceAgentControlEvent` and
 `agentDurableEventId`. It imports no model provider, executor, store, event sink

package/llms/agent-runtime.2.txt

@@ -482,6 +482,19 @@ or it keeps the failed attempt's partial text on screen.
   start and output on completion. A mounted typed failure carries the same safe
   `{ error, retryable, details?, _hint? }` envelope as the durable result; an unknown
   internal cause remains generic and stays in local observability only;
+- `tool-progress` is transient: what a running tool handler reported through
+  `ctx.reportProgress` — `message`, `progress` and `total`, the fields an MCP host
+  receives — with the call's `callId` and `toolName`. It never enters the
+  model's input or the durable history. A message longer than
+  `AGENT_TOOL_PROGRESS_MESSAGE_MAX` (280) is cut, reports of one call closer
+  than 250 ms apart are dropped, and a report after the call's terminal
+  `tool-status` or after its attempt was abandoned is dropped; the terminal
+  status carries the final word. `reduceAgentControlEvent` keeps the last
+  report of each running call in `transientByRun[runId].tools[callId]` and
+  removes it on that call's `completed`, `failed` or `interrupted`. The runtime
+  hands its reporter to a call through the SDK tool context, beside its step
+  ledger; a tool that declares its own `contextSchema` keeps that contract and
+  reports nowhere;
 - `terminal` follows the winning terminal CAS.
 
 `loop.checkpointEveryEvents` batches ordinary stream parts (default `20`) and
@@ -787,111 +800,3 @@ Deciding *when* to compact is yours: `AgentRuntimeRunContext.contextUsage`
 carries the last step's prompt size beside the model's window, and dividing them
 is one line where the threshold is decided. The core does not own that ratio, on
 purpose — see ADR 0142 for what it publishes and what it declines to.
-
-## Observability
-
-`createAgentObservability` emits a separate operator-only `AgentRunEvent`. It
-reuses the same bounded sink lifecycle as request/tool observability without
-sending new event kinds to existing request sinks. Product events omit provider
-causes. Operator `internalCause` is also redacted by default; an operator-only sink must explicitly
-set `includeInternalCause` and own its retention policy.
-
-### What a run says it spent
-
-Usage values carry `provider-reported`, `computed`, `estimated` or `unavailable`
-provenance, **per field**. Cost additionally carries an ISO currency code;
-OpenRouter-reported cost is normalized as USD.
-
-Read the provenance before the number (→ ADR 0109):
-
-- **`provider-reported`** — the provider handed us exactly this. On
-  `step-finished`, that is what a step's figures are.
-- **`computed`** — a total, added up over steps. **Every figure on a terminal
-  event is this**, tokens included: the AI SDK's `totalUsage` is a sum it
-  performed, not a number a provider reported for the run. It is not a figure to
-  bill against unchanged.
-- **`unavailable`** — nobody reported it. Not zero.
-
-Two rules follow from that last one, and they differ by field on purpose:
-
-- **A token total with an unreported step is a floor**, labelled `computed`. A
-  token count is a diagnostic, and a floor is a useful one.
-- **A cost with an unreported step is `unavailable`, not a floor.** Money is what
-  people bill against, and "at least $1.00" reported as `$1.00` is the same class
-  of lie this whole section exists to remove. One step that did not report its
-  cost makes the run's cost unknown — not smaller. It also stays unknown: later
-  steps reporting normally cannot revive it.
-
-**A terminal event always carries `usage`.** A run that ended before the provider
-reported anything — superseded, interrupted, timed out, shut down, failed —
-carries every field `unavailable`. That is deliberately different from a run that
-spent nothing, and an omitted object could not tell you which one you had.
-
-Two costs in different currencies do not add: the sum reports `unavailable`
-rather than picking a label. The core records a currency and never converts one.
-
-`step-finished.response` identifies the provider response for that one step. The terminal event
-does not copy the last response: response identity remains per-step, while every terminal usage
-figure remains a `computed` aggregate.
-
-**A run's figure is durable, and that is where to read it when a channel loses
-it.** `AgentRun.usage` is written at every checkpoint and again with the terminal
-record, so a crashed process leaves behind what it had already spent and a
-dropped event is not a lost number:
-
-```ts
-const snapshot = await store.loadSnapshot(conversationId)
-const spent = snapshot.runs.find((run) => run.id === runId)?.usage
-```
-
-Two gaps are open and are stated rather than left to be discovered:
-
-- **Both event sinks are bounded and drop under load**, by arrival order — the
-  event carrying the money is exactly as droppable as the one carrying nothing.
-  The run record is the recovery, and this paragraph is the only place that says
-  so.
-- **`AgentRuntimeResult.metrics` is `undefined` when this executor did not win
-  the terminal race.** Read `result.run.usage` — the durable figure — rather than
-  `result.metrics`, which is the channel that can go missing.
-- **Compaction spend is invisible unless you report it.** `config.history.compact`
-  calls a model inside the turn and produces no step and no event of its own.
-  Return `usage` from `AgentCompactionResult` and it joins the run's figure;
-  omit it and the run under-reports by whatever summarising cost.
-
-What stitchkit does **not** keep is a ledger: one figure, on the run that
-produced it, never aggregated and never reconciled against a provider invoice
-(→ ADR 0110).
-
-### Reconciling with the provider's own accounting
-
-Whether a provider bills for a call that was aborted mid-flight cannot be known
-inside the process: the authoritative number arrives later, from the provider's
-accounting. **stitchkit does not accept it back** (→ ADR 0110) — a terminal run
-is an absorbing state, and a write that reached it through the conversation
-aggregate could conflict a concurrent compaction into discarding a summary it had
-just paid a model to produce.
-
-The join is yours, and `runId` is the key:
-
-```ts
-// when the run terminates — write what the runtime observed
-await ledger.record({
-  runId: terminal.run.id,
-  conversationId: terminal.run.conversationId,
-  // The durable figure, not `terminal.metrics` — that one is absent whenever
-  // this executor did not win the terminal race.
-  costUsd: terminal.run.usage?.cost?.value ?? null,        // null when `unavailable`
-  provenance: terminal.run.usage?.cost?.provenance ?? 'unavailable',
-})
-
-// later — the provider's accounting names the same generation
-await ledger.reconcile({ runId, costUsd: billed, provenance: 'provider-reported' })
-```
-
-Record the row even when the figure is `unavailable`: that row is the evidence
-that a run happened and cost something nobody has counted yet, and it is what the
-provider's later figure attaches to. A run with no row is a run you cannot
-reconcile.
-
-The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable
-outbox.

package/llms/agent-runtime.3.txt

@@ -14,6 +14,114 @@ Parts of this slice:
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
 ==============================================================================
 
+## Observability
+
+`createAgentObservability` emits a separate operator-only `AgentRunEvent`. It
+reuses the same bounded sink lifecycle as request/tool observability without
+sending new event kinds to existing request sinks. Product events omit provider
+causes. Operator `internalCause` is also redacted by default; an operator-only sink must explicitly
+set `includeInternalCause` and own its retention policy.
+
+### What a run says it spent
+
+Usage values carry `provider-reported`, `computed`, `estimated` or `unavailable`
+provenance, **per field**. Cost additionally carries an ISO currency code;
+OpenRouter-reported cost is normalized as USD.
+
+Read the provenance before the number (→ ADR 0109):
+
+- **`provider-reported`** — the provider handed us exactly this. On
+  `step-finished`, that is what a step's figures are.
+- **`computed`** — a total, added up over steps. **Every figure on a terminal
+  event is this**, tokens included: the AI SDK's `totalUsage` is a sum it
+  performed, not a number a provider reported for the run. It is not a figure to
+  bill against unchanged.
+- **`unavailable`** — nobody reported it. Not zero.
+
+Two rules follow from that last one, and they differ by field on purpose:
+
+- **A token total with an unreported step is a floor**, labelled `computed`. A
+  token count is a diagnostic, and a floor is a useful one.
+- **A cost with an unreported step is `unavailable`, not a floor.** Money is what
+  people bill against, and "at least $1.00" reported as `$1.00` is the same class
+  of lie this whole section exists to remove. One step that did not report its
+  cost makes the run's cost unknown — not smaller. It also stays unknown: later
+  steps reporting normally cannot revive it.
+
+**A terminal event always carries `usage`.** A run that ended before the provider
+reported anything — superseded, interrupted, timed out, shut down, failed —
+carries every field `unavailable`. That is deliberately different from a run that
+spent nothing, and an omitted object could not tell you which one you had.
+
+Two costs in different currencies do not add: the sum reports `unavailable`
+rather than picking a label. The core records a currency and never converts one.
+
+`step-finished.response` identifies the provider response for that one step. The terminal event
+does not copy the last response: response identity remains per-step, while every terminal usage
+figure remains a `computed` aggregate.
+
+**A run's figure is durable, and that is where to read it when a channel loses
+it.** `AgentRun.usage` is written at every checkpoint and again with the terminal
+record, so a crashed process leaves behind what it had already spent and a
+dropped event is not a lost number:
+
+```ts
+const snapshot = await store.loadSnapshot(conversationId)
+const spent = snapshot.runs.find((run) => run.id === runId)?.usage
+```
+
+Two gaps are open and are stated rather than left to be discovered:
+
+- **Both event sinks are bounded and drop under load**, by arrival order — the
+  event carrying the money is exactly as droppable as the one carrying nothing.
+  The run record is the recovery, and this paragraph is the only place that says
+  so.
+- **`AgentRuntimeResult.metrics` is `undefined` when this executor did not win
+  the terminal race.** Read `result.run.usage` — the durable figure — rather than
+  `result.metrics`, which is the channel that can go missing.
+- **Compaction spend is invisible unless you report it.** `config.history.compact`
+  calls a model inside the turn and produces no step and no event of its own.
+  Return `usage` from `AgentCompactionResult` and it joins the run's figure;
+  omit it and the run under-reports by whatever summarising cost.
+
+What stitchkit does **not** keep is a ledger: one figure, on the run that
+produced it, never aggregated and never reconciled against a provider invoice
+(→ ADR 0110).
+
+### Reconciling with the provider's own accounting
+
+Whether a provider bills for a call that was aborted mid-flight cannot be known
+inside the process: the authoritative number arrives later, from the provider's
+accounting. **stitchkit does not accept it back** (→ ADR 0110) — a terminal run
+is an absorbing state, and a write that reached it through the conversation
+aggregate could conflict a concurrent compaction into discarding a summary it had
+just paid a model to produce.
+
+The join is yours, and `runId` is the key:
+
+```ts
+// when the run terminates — write what the runtime observed
+await ledger.record({
+  runId: terminal.run.id,
+  conversationId: terminal.run.conversationId,
+  // The durable figure, not `terminal.metrics` — that one is absent whenever
+  // this executor did not win the terminal race.
+  costUsd: terminal.run.usage?.cost?.value ?? null,        // null when `unavailable`
+  provenance: terminal.run.usage?.cost?.provenance ?? 'unavailable',
+})
+
+// later — the provider's accounting names the same generation
+await ledger.reconcile({ runId, costUsd: billed, provenance: 'provider-reported' })
+```
+
+Record the row even when the figure is `unavailable`: that row is the evidence
+that a run happened and cost something nobody has counted yet, and it is what the
+provider's later figure attaches to. A run with no row is a run you cannot
+reconcile.
+
+The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable
+outbox.
+
 ## Deterministic race and adapter proof
 
 `stitchkit/agent-runtime/testing` exports `createAgentRaceBarrier`, `createAgentRaceDriver`,
@@ -391,7 +499,9 @@ Delivery exports are `AgentAdmissionEventSchema`, `AgentAttemptResetEventSchema`
 `AgentRunStateEventSchema`, `AgentRunOperationEventSchema`, `AgentTerminalEventSchema`,
 `AgentTransientDeltaEventSchema`,
 `AgentReasoningStartEventSchema`, `AgentReasoningDeltaEventSchema`,
-`AgentReasoningEndEventSchema`, `AgentToolStatusEventSchema`, `AgentRuntimeEvent`,
+`AgentReasoningEndEventSchema`, `AgentToolStatusEventSchema`, `AgentToolProgressEventSchema` (what a
+running tool reported through `ctx.reportProgress`, transient and never part of the model's input),
+`AgentRuntimeEvent`,
 `AgentRuntimeEventCursor`, `AgentRuntimeEventCursorSchema`, `AgentRuntimeCursorAdvance`,
 `advanceAgentRuntimeEventCursor`, `agentDurableEventId`, `AgentRuntimeEventSink`,
 `AgentRuntimeEventSinkConfig` and `createAgentRuntimeEventSink`. Cursor gaps require a canonical

package/llms/cli.txt

@@ -702,15 +702,27 @@ Rules worth knowing before you rely on them:
 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.
 
-If the command succeeds but its requested view cannot be built, the CLI writes
-the complete original result to stdout, using the normal JSON format (`--json`
-still selects compact output). It writes a separate structured
-`CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`, configurable
-through `exitCodes`. Its `details.operationSucceeded: true` and `retryable: false`
-distinguish a presentation refusal from a failed operation; `details.cause`
-preserves the safe reason. Recover the answer from stdout instead of repeating
-the mutation. Domain retry hints are not appended to this diagnostic. CLI
-argument errors detected before execution still exit with `2`
+If the command succeeds but its requested view cannot be built, the CLI writes a
+structured `CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`,
+configurable through `exitCodes`. Its `details.operationSucceeded: true` and
+`retryable: false` distinguish a presentation refusal from a failed operation;
+`details.cause` preserves the safe reason, such as the misspelled field and the
+fields that are there. Domain retry hints are not appended to this diagnostic.
+
+What reaches stdout depends on whether the command can be called again for its answer,
+and `details.resultOnStdout` states which case occurred:
+
+| Command | stdout | Recover the answer by |
+|---|---|---|
+| has an effect | the complete original result in the normal JSON format (`--json` still selects compact output) | reading stdout — never by repeating the mutation |
+| only reads | nothing | repeating the command with a corrected view |
+
+A managed command only reads when its tool declares `annotations.readOnlyHint: true`,
+or declares no `readOnlyHint` and its method is `GET`. `readOnlyHint: false` on a `GET`
+endpoint keeps the result on stdout. A native `defineCliCommand` declares neither fact,
+so a failed `present` always keeps the validated result on stdout.
+
+CLI argument errors detected before execution still exit with `2`
 and have no successful result to preserve.
 
 ## Named profiles

package/llms/server.2.txt

@@ -507,3 +507,51 @@ is simply never emitted, so nothing about a hidden endpoint leaks.
 const internal = openApiRoute('/internal/openapi.json', fullDoc)   // behind auth
 const publicSpec = openApiRoute('/openapi.json', publicDoc)         // curated
 ```
+
+### Security schemes — `security`
+
+A generic client reads the spec to learn how to authenticate, and a scope name
+alone does not tell it which header to send. Pass `security` to describe that in
+standard OpenAPI terms: named schemes become `components.securitySchemes`, and
+every protected operation gets a `security` requirement. It is keyed by the
+scopes your contracts already declare, so there is no second list of which
+endpoint is protected:
+
+```ts
+const publicDoc = generateOpenApiDocument({
+  info: { title: 'Public API', version: '1.0.0' },
+  services: [account],
+  includeMethod: (m) => m.meta?.public === true,
+  security: {
+    schemes: {
+      apiKey: { type: 'http', scheme: 'bearer', description: 'An account API key' },
+    },
+    // Each protected scope → the schemes that satisfy it, any one of them.
+    scopes: { account: ['apiKey'] },
+  },
+})
+```
+
+A scheme is `{ type: 'http', scheme: 'bearer' | 'basic' }` or
+`{ type: 'apiKey', in: 'header' | 'query' | 'cookie', name }` (a session cookie
+is the `cookie` form). An operation is described by the scope the auth hook
+checks it under:
+
+| The operation's scope | In the document |
+|---|---|
+| `'public'` | no `security`, no 401/403 |
+| listed in `scopes` with schemes | `security: [{ apiKey: [] }, …]` and 401/403 |
+| listed with an empty list — a custom scope whose rule is `'public'` | no `security`, no 401/403 |
+| not listed | generation throws, naming the operation |
+| none of its own | read as `defaultScope` — pass the same value as `createAuthHook({ defaultScope })` |
+
+Generation refuses a protected scope it cannot describe instead of emitting the
+operation as open — a client would otherwise call it without a credential. Only
+the operations the document advertises need a mapping: a method `includeMethod`
+filters out is never checked. A scheme `scopes` names but `schemes` does not
+declare, and an entry for `'public'`, are refused the same way.
+
+The metadata describes your policy; it does not enforce it. The auth hook is
+still the only gate, and removing `security` changes the document, never a
+401 or 403. Credential values never belong here: describe where the key goes,
+not what it is.

package/llms/server.5.txt

@@ -236,6 +236,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `OpenApiConfig` | _type_ | config for `generateOpenApiDocument` (incl. `includeMethod` — curate a public subset) — [guide](../guide/server.md#curating-the-spec--includemethod) |
 | `OpenApiDocument` | _type_ | the generated document |
 | `OpenApiInfo` | _type_ | the spec `info` block |
+| `OpenApiSecurity` | _type_ | `OpenApiConfig.security` — named schemes and the schemes each protected scope accepts — [guide](../guide/server.md#security-schemes--security) |
+| `OpenApiSecurityScheme` | _type_ | one way a caller presents its credential: HTTP bearer or basic, or an API key in a header, query or cookie |
 | `OpenApiServer` | _type_ | a spec `servers` entry |
 
 ---

package/llms/stitchkit.txt

@@ -92,13 +92,13 @@ own, recorded as an ADR.
 | `stitchkit/xlsx` | browser **and** server | evolving | a workbook from rows and typed columns, with no dependency; text never runs as a formula |
 | `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 66 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 67 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, the managed-resource conformance kit and manual time for schedules and retries |
 | `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/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 26 of the 66 minors since 0.56.2, most recently 0.121.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 26 of the 67 minors since 0.56.2, most recently 0.121.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, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -110,7 +110,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 14 of the 66 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 67 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `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 |

package/llms/tools.txt

@@ -498,7 +498,10 @@ render: async (ctx) => {
 
 `reportProgress` is present on every **tool** call — MCP, agent and CLI — so a
 handler never branches on transport, and it does nothing wherever nobody is
-listening. It is absent on the HTTP transport, which has no channel for it, so a
+listening. Under the agent runtime somebody is: each report becomes a transient
+`tool-progress` event of the run, so the person watching the agent sees the
+stage while the model still reads only the tool's result (see
+[Agent runtime → events](./agent-runtime.md)). It is absent on the HTTP transport, which has no channel for it, so a
 handler that also serves HTTP writes `ctx.reportProgress?.(…)`. It never throws and never
 rejects: a message about work must not be able to kill the work it describes, so
 a refused notification leaves the host exactly where a host that never asked for