@xlaunch/llm 0.2.0-beta.1

package/lib/invariant.js

@@ -0,0 +1,84 @@
+//#region lib/types/invariant.js
+/** Package-owned LLM stream-protocol invariants. @module @xlaunch/llm/invariant */
+const PACKAGE_NAME = "@xlaunch/llm";
+/** Cordis companion plugin name. */
+const name = "llm-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Require one chunk index to be a non-negative safe integer. */
+function validateIndex(index, fail) {
+	if (!Number.isSafeInteger(index) || index < 0) fail(`LLM stream block index must be a non-negative safe integer, got ${index}`);
+}
+/** Require a delta to address an open block of its matching type. */
+function validateDelta(open, index, expected, fail) {
+	validateIndex(index, fail);
+	const actual = open.get(index);
+	if (actual !== expected) fail(`${expected} delta at index ${index} requires an open ${expected} block, got ${String(actual)}`);
+}
+/** Wrap one provider stream and enforce its grammar as chunks are consumed. */
+async function* validateStream(source, fail) {
+	const open = /* @__PURE__ */ new Map();
+	let usageSeen = false;
+	let finished = false;
+	for await (const chunk of source) {
+		if (finished) fail(`LLM stream emitted ${chunk.type} after terminal finish`);
+		switch (chunk.type) {
+			case "block-start":
+				validateIndex(chunk.index, fail);
+				if (open.has(chunk.index)) fail(`LLM stream repeated block-start index ${chunk.index}`);
+				open.set(chunk.index, chunk.blockType);
+				break;
+			case "text-delta":
+				validateDelta(open, chunk.index, "text", fail);
+				break;
+			case "reasoning-delta":
+				validateDelta(open, chunk.index, "reasoning", fail);
+				break;
+			case "tool-call-delta":
+				validateDelta(open, chunk.index, "tool-call", fail);
+				break;
+			case "block-end": {
+				validateIndex(chunk.index, fail);
+				const blockType = open.get(chunk.index);
+				if (blockType === void 0) fail(`LLM stream block-end index ${chunk.index} has no open block`);
+				if (chunk.block.type !== blockType) fail(`LLM stream block-end index ${chunk.index} closes ${chunk.block.type}, expected ${blockType}`);
+				open.delete(chunk.index);
+				break;
+			}
+			case "usage":
+				if (usageSeen) fail("LLM stream emitted usage more than once");
+				usageSeen = true;
+				break;
+			case "finish":
+				if (open.size > 0 && chunk.reason.kind !== "error" && chunk.reason.kind !== "aborted") fail(`LLM stream finished with ${open.size} open block(s)`);
+				finished = true;
+				break;
+		}
+		yield chunk;
+	}
+	if (!finished) fail("LLM stream ended without a terminal finish chunk");
+}
+/** Install validation around every provider stream. */
+const install = (ctx, fail) => {
+	ctx.on("llm/stream", (_options, next) => validateStream(next(), fail), {
+		global: true,
+		prepend: true
+	});
+	ctx.on("llm/adapters-updated", () => {
+		const llm = ctx.get("llm");
+		if (llm === void 0) return;
+		for (const provider of llm.listProviders()) try {
+			llm.providerRetryPolicy(provider.id);
+		} catch {
+			fail(`llm/adapters-updated fired while provider "${provider.id}" has no readable registration`);
+		}
+	}, { global: true });
+};
+/**
+* Register the LLM invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/typert.host.d.ts

@@ -0,0 +1,3 @@
+/* Generated by @xlaunch/typert-generator from FaceModel — do not edit. */
+
+export declare const TYPERT: unknown

package/lib/typert.host.js

@@ -0,0 +1,547 @@
+/* Generated by @xlaunch/typert-generator from FaceModel — do not edit. */
+import { z } from 'zod'
+
+const _xlaunch_llm_llm_discoverModels_parameter_0$schema = z.string()
+const _xlaunch_llm_llm_discoverModels_parameter_1$schema = z.object({
+  'provider': z.string().optional(),
+  'baseURL': z.string().optional(),
+  'api': z.string().optional(),
+  'apiKey': z.string().optional(),
+})
+const _xlaunch_llm_llm_discoverModels_result$schema = z.array(z.object({
+  'id': z.string(),
+  'name': z.string().optional(),
+  'contextWindow': z.number().optional(),
+  'maxTokens': z.number().optional(),
+}))
+const _xlaunch_llm_llm_listConfigurableProviders_result$schema = z.array(z.object({
+  'provider': z.string(),
+  'displayName': z.string(),
+  'settingsNs': z.string(),
+  'settingsPath': z.array(z.string()),
+  'declared': z.boolean().optional(),
+}))
+const _xlaunch_llm_llm_listProviders_result$schema = z.array(z.object({
+  'id': z.string(),
+  'name': z.string(),
+}))
+
+export const TYPERT = {
+  package: '@xlaunch/llm',
+  face: 'host',
+  schemas: [
+  ],
+  invocations: [
+    {
+      id: '@xlaunch/llm#llm/discoverModels',
+      service: 'llm',
+      namespace: 'llm',
+      method: 'discoverModels',
+      implementation: 'remoteDiscoverModels',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'settingsNs',
+          wire: 'settingsNs',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@xlaunch/llm#llm/discoverModels:settingsNs',
+            schema: _xlaunch_llm_llm_discoverModels_parameter_0$schema,
+          },
+        },
+        {
+          name: 'request',
+          wire: 'request',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@xlaunch/llm/types#LlmModelDiscoveryRequest',
+            schema: _xlaunch_llm_llm_discoverModels_parameter_1$schema,
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@xlaunch/llm#llm/discoverModels:result',
+        schema: _xlaunch_llm_llm_discoverModels_result$schema,
+      },
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":625,"column":9},
+    },
+    {
+      id: '@xlaunch/llm#llm/listConfigurableProviders',
+      service: 'llm',
+      namespace: 'llm',
+      method: 'listConfigurableProviders',
+      invocation: { kind: 'direct' },
+      parameters: [
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@xlaunch/llm#llm/listConfigurableProviders:result',
+        schema: _xlaunch_llm_llm_listConfigurableProviders_result$schema,
+      },
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":538,"column":3},
+    },
+    {
+      id: '@xlaunch/llm#llm/listProviders',
+      service: 'llm',
+      namespace: 'llm',
+      method: 'listProviders',
+      invocation: { kind: 'direct' },
+      parameters: [
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@xlaunch/llm#llm/listProviders:result',
+        schema: _xlaunch_llm_llm_listProviders_result$schema,
+      },
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":466,"column":3},
+    },
+  ],
+  model: {
+    "services": [
+      {
+        "description": "The abstract `llm` service: an adapter registry plus a streaming model-call API, interceptable via the `llm/stream` waterfall.",
+        "summary": "The abstract `llm` service: an adapter registry plus a streaming model-call API, interceptable via the `llm/stream` waterfall.",
+        "tags": [],
+        "jsDoc": "/**\n * The abstract `llm` service: an adapter registry plus a streaming model-call\n * API, interceptable via the `llm/stream` waterfall.\n */",
+        "key": "llm",
+        "exportName": "LlmRuntime",
+        "members": [
+          {
+            "kind": "method",
+            "name": "registerAdapter",
+            "signature": "registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle",
+            "summary": "Register an adapter for the given provider routes.",
+            "jsDoc": "/**\n * Register an adapter for the given provider routes. Throws `LlmError` with code\n * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).\n * Disposed with the fiber.\n * @param providers - every provider route this adapter should serve.\n * @param adapter - the adapter that streams calls for those providers.\n * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "listProviders",
+            "signature": "@Remote listProviders(): LlmProviderInfo[]",
+            "summary": "Describe provider routes with a registered adapter.",
+            "jsDoc": "/**\n * Describe provider routes with a registered adapter.\n * @returns detached provider metadata in registration order.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "registerConfigurableProviders",
+            "signature": "registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle",
+            "summary": "Declare provider routes an adapter plugin can activate through configuration.",
+            "jsDoc": "/**\n * Declare provider routes an adapter plugin can activate through\n * configuration. Registration is all-or-nothing: an empty list, invalid\n * entry, or a provider already declared by any registration throws\n * `LlmError` without registering the rest. Disposed with the fiber.\n * @param entries - every configurable provider this plugin owns.\n * @returns a handle that withdraws all of them, and can atomically replace them.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "listConfigurableProviders",
+            "signature": "@Remote listConfigurableProviders(): LlmConfigurableProvider[]",
+            "summary": "List every declared configurable provider, registered or dormant.",
+            "jsDoc": "/**\n * List every declared configurable provider, registered or dormant.\n * @returns detached directory entries in declaration order.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "registerModelDiscovery",
+            "signature": "registerModelDiscovery( settingsNs: string, discover: ( request: LlmModelDiscoveryRequest, signal?: AbortSignal, ) => Promise<readonly LlmDiscoveredModel[]>, ): () => void",
+            "summary": "Offer to interrogate provider endpoints on behalf of the settings namespace this plugin owns.",
+            "jsDoc": "/**\n * Offer to interrogate provider endpoints on behalf of the settings\n * namespace this plugin owns. The namespace is the key because that is what\n * a configuration surface already holds from the configurable-provider\n * directory, and because a provider being *added* has no route to name yet.\n * Disposed with the fiber.\n * @param settingsNs - the namespace whose profiles this discovery serves.\n * @param discover - interrogates one endpoint and must honor the supplied signal.\n * @returns the disposer that withdraws the offer.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "discoverModels",
+            "signature": "async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, signal?: AbortSignal, ): Promise<LlmDiscoveredModel[]>",
+            "summary": "Interrogate one provider endpoint for the models it advertises.",
+            "jsDoc": "/**\n * Interrogate one provider endpoint for the models it advertises. The\n * request describes a draft, not a stored route, so nothing here reads or\n * writes settings or credentials — the caller owns both, and the reply is\n * candidate metadata a surface may offer for adoption.\n * @param settingsNs - namespace whose registered discovery serves this draft.\n * @param request - the endpoint, protocol, and one-shot credential to use.\n * @param signal - caller cancellation.\n * @returns the advertised models, deduplicated in endpoint order.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "remoteDiscoverModels",
+            "signature": "@Remote('discoverModels') async remoteDiscoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, signal: AbortSignal, ): Promise<LlmDiscoveredModel[]>",
+            "summary": "Remote adapter for one draft provider interrogation.",
+            "jsDoc": "/**\n * Remote adapter for one draft provider interrogation.\n * @param settingsNs - namespace whose registered discovery serves this draft.\n * @param request - endpoint, protocol, and one-shot credential to use.\n * @param signal - caller cancellation supplied by the Remote carrier.\n * @returns advertised models in endpoint order.\n * @throws RemoteError with `llm/model-discovery-rejected` when discovery refuses or fails.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "providerRetryPolicy",
+            "signature": "providerRetryPolicy(provider: string): ResolvedRetryPolicy",
+            "summary": "Resolve the retry policy captured when one provider route was registered.",
+            "jsDoc": "/**\n * Resolve the retry policy captured when one provider route was registered.\n * @param provider - registered provider route to inspect.\n * @returns the provider-owned policy, with normal defaults already resolved.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "imageRequestPricing",
+            "signature": "imageRequestPricing(provider: string, model: string): LlmImageRequestPricing | undefined",
+            "summary": "Resolve provider-side request-image pricing for one exact route, or `undefined` when the provider is unregistered or declares none.",
+            "jsDoc": "/**\n * Resolve provider-side request-image pricing for one exact route, or\n * `undefined` when the provider is unregistered or declares none. Unknown\n * providers degrade to `undefined` rather than throwing because callers\n * price durable history whose route may no longer be mounted.\n * @param provider - provider route named by a request header.\n * @param model - exact model id named by the same header.\n * @returns the owning adapter's image pricing for the route, when declared.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "fileRequestText",
+            "signature": "fileRequestText(ref: FileAttachmentRef): string",
+            "summary": "Resolve the exact text one durable file occurrence contributes to every provider request in the current execution environment.",
+            "jsDoc": "/**\n * Resolve the exact text one durable file occurrence contributes to every\n * provider request in the current execution environment.\n * @param ref - durable verbatim file reference from model history.\n * @returns the same deterministic handle text used at adapter dispatch.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "listModels",
+            "signature": "async listModels(provider: string): Promise<LlmModelInfo[]>",
+            "summary": "Discover models advertised by one registered provider.",
+            "jsDoc": "/**\n * Discover models advertised by one registered provider. Catalog membership\n * is advisory and never changes routing or request validation.\n * @param provider - registered provider route to inspect.\n * @returns detached model metadata in adapter-preferred order.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "resolveModelInfo",
+            "signature": "async resolveModelInfo( provider: string, model: string, signal?: AbortSignal, ): Promise<LlmResolvedModelInfo>",
+            "summary": "Resolve and validate all metadata from the adapter that owns one exact route.",
+            "jsDoc": "/**\n * Resolve and validate all metadata from the adapter that owns one exact\n * route. The result is detached from adapter-owned objects; catalog\n * membership remains advisory and does not control request routing.\n * @param provider - registered provider route to inspect.\n * @param model - exact model id passed to the adapter.\n * @param signal - optional cancellation for adapter-owned asynchronous lookup.\n * @returns exact model identity plus available context and reasoning metadata.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "resolveCallConfig",
+            "signature": "async resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>",
+            "summary": "Validate a conversation call config against its exact model capability and materialize adapter-configured defaults.",
+            "jsDoc": "/**\n * Validate a conversation call config against its exact model capability and\n * materialize adapter-configured defaults. Unsupported explicit efforts\n * reject before provider I/O; no clamping or aliasing is performed. This\n * standalone query does not bind a later dispatch; use {@link prepareCall}\n * when logging and streaming must share one adapter registration.\n * @param config - provider/model route and optional request controls.\n * @param signal - optional cancellation for adapter-owned capability lookup.\n * @returns a detached config only when a default must be materialized.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "prepareCall",
+            "signature": "async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>",
+            "summary": "Resolve one call under its current adapter registration.",
+            "jsDoc": "/**\n * Resolve one call under its current adapter registration. The returned\n * one-shot handle keeps that registration across header logging and dispatch,\n * so HMR cannot combine one adapter's capability result with another adapter.\n * @param config - provider/model route and optional request controls.\n * @param signal - optional cancellation for adapter-owned capability lookup.\n * @returns a prepared config and its registration-bound stream entry point.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "stream",
+            "signature": "stream(options: GenerateOptions): AsyncIterable<StreamChunk>",
+            "summary": "Stream one model call as raw chunks (token-level deltas).",
+            "jsDoc": "/**\n * Stream one model call as raw chunks (token-level deltas). Replay state is\n * retained only when the same adapter instance owns its historical provider\n * and the target provider. Final adapter selection remains fixed through\n * asynchronous exact-model resolution and dispatch. Adapter selection,\n * dispatch, and iteration failures become terminal `error` or `aborted`\n * finish chunks; middleware, nested-call, cleanup, and consumer failures\n * remain thrown.\n * @param options - the full request; `options.provider` selects the adapter.\n * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.\n */"
+          }
+        ],
+        "types": [
+          {
+            "name": "AdapterRegistrationHandle",
+            "declaration": "export interface AdapterRegistrationHandle {\n    (): void;\n    replace(providers: string[]): void;\n}"
+          },
+          {
+            "name": "AgentInstructionChange",
+            "declaration": "export interface AgentInstructionChange {\n    action: 'set' | 'replace' | 'remove';\n    scope: string;\n    path: string;\n    digest?: string;\n}"
+          },
+          {
+            "name": "AgentInstructionSource",
+            "declaration": "export interface AgentInstructionSource {\n    kind: 'agent-instructions';\n    form: 'instructions';\n    baseline?: true;\n    baselineIdentity?: string;\n    changes: AgentInstructionChange[];\n}"
+          },
+          {
+            "name": "AgentMessageSource",
+            "declaration": "export interface AgentMessageSource {\n    readonly kind: 'agent-message';\n    readonly form: 'relay';\n    readonly senderSessionId: SessionId;\n}"
+          },
+          {
+            "name": "AssistantProvenance",
+            "declaration": "export interface AssistantProvenance {\n    provider: string;\n    model: string;\n    replayState?: unknown;\n}"
+          },
+          {
+            "name": "AttachmentId",
+            "declaration": "export type AttachmentId = Branded<'AttachmentId'>;"
+          },
+          {
+            "name": "Branded",
+            "declaration": "export type Branded<B extends string> = string & { readonly [BRAND]: B; };"
+          },
+          {
+            "name": "BrandedNumber",
+            "declaration": "export type BrandedNumber<B extends string> = number & { readonly [BRAND]: B; };"
+          },
+          {
+            "name": "ContentBlock",
+            "declaration": "export type ContentBlock = ContentBlockMap[ContentBlockType];"
+          },
+          {
+            "name": "ContentBlockMap",
+            "declaration": "export interface ContentBlockMap {\n    text: TextBlock;\n    reasoning: ReasoningBlock;\n    image: ImageBlock;\n    file: FileBlock;\n    'tool-call': ToolCallBlock;\n    'tool-result': ToolResultBlock;\n}"
+          },
+          {
+            "name": "ContentBlockType",
+            "declaration": "export type ContentBlockType = keyof ContentBlockMap;"
+          },
+          {
+            "name": "ContextFormed",
+            "declaration": "export type ContextFormed = { readonly form?: never; } | { readonly form: 'instructions'; } | { readonly form: 'catalog'; } | { readonly form: 'snapshot'; readonly sections: readonly ContextSnapshotSection[]; } | { readonly form: 'notice'; readonly summary: string; } | { readonly form: 'relay'; } | { readonly form: 'recall'; };"
+          },
+          {
+            "name": "ContextSnapshotSection",
+            "declaration": "export interface ContextSnapshotSection {\n    readonly name: string;\n    readonly text: string;\n}"
+          },
+          {
+            "name": "DirectoryRegistrationHandle",
+            "declaration": "export interface DirectoryRegistrationHandle {\n    (): void;\n    replace(entries: readonly LlmConfigurableProvider[]): void;\n}"
+          },
+          {
+            "name": "FileAttachmentRef",
+            "declaration": "export interface FileAttachmentRef {\n    attachmentId: AttachmentId;\n    name: string;\n    bytes: number;\n}"
+          },
+          {
+            "name": "FileBlock",
+            "declaration": "export interface FileBlock {\n    type: 'file';\n    attachment: FileAttachmentRef;\n}"
+          },
+          {
+            "name": "FinishReason",
+            "declaration": "export type FinishReason = FinishReasonMap[keyof FinishReasonMap];"
+          },
+          {
+            "name": "FinishReasonMap",
+            "declaration": "export interface FinishReasonMap {\n    stop: { kind: 'stop'; };\n    'tool-calls': { kind: 'tool-calls'; };\n    'max-tokens': { kind: 'max-tokens'; };\n    aborted: { kind: 'aborted'; failure: LlmFailure; };\n    error: { kind: 'error'; failure: LlmFailure; };\n}"
+          },
+          {
+            "name": "GenerateOptions",
+            "declaration": "export interface GenerateOptions {\n    provider: string;\n    model: string;\n    reasoningEffort?: ReasoningEffortId;\n    messages: Message[];\n    system?: string;\n    tools?: ToolSchema[];\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n    signal?: AbortSignal;\n    sessionId?: Branded<'SessionId'>;\n    purpose?: 'compaction' | 'session-title';\n}"
+          },
+          {
+            "name": "GoalId",
+            "declaration": "export type GoalId = Branded<'GoalId'>;"
+          },
+          {
+            "name": "GoalMessageSource",
+            "declaration": "export interface GoalMessageSource {\n    readonly kind: 'goal';\n    readonly goalId: GoalId;\n    readonly revision: number;\n    readonly round: number;\n}"
+          },
+          {
+            "name": "ImageAttachmentRef",
+            "declaration": "export interface ImageAttachmentRef {\n    attachmentId: AttachmentId;\n    mediaType: ImageMediaType;\n    bytes: number;\n    width: number;\n    height: number;\n    name?: string;\n    originalDimensions?: { width: number; height: number; };\n}"
+          },
+          {
+            "name": "ImageBlock",
+            "declaration": "export interface ImageBlock {\n    type: 'image';\n    attachment: ImageAttachmentRef;\n}"
+          },
+          {
+            "name": "ImageMediaType",
+            "declaration": "export type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';"
+          },
+          {
+            "name": "LlmAdapter",
+            "declaration": "export abstract class LlmAdapter {\n    providerInfo(provider: string): LlmProviderInfo;\n    providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined;\n    imageRequestPricing(_provider: string, _model: string): LlmImageRequestPricing | undefined;\n    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;\n    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;\n    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;\n    abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>;\n}"
+          },
+          {
+            "name": "LlmCallConfig",
+            "declaration": "export interface LlmCallConfig {\n    provider: string;\n    model: string;\n    reasoningEffort?: ReasoningEffortId;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}"
+          },
+          {
+            "name": "LlmCallConfigAdapterDefaults",
+            "declaration": "export interface LlmCallConfigAdapterDefaults {\n    reasoningEffort?: true;\n    maxTokens?: true;\n}"
+          },
+          {
+            "name": "LlmConfigurableProvider",
+            "declaration": "export interface LlmConfigurableProvider {\n    provider: string;\n    displayName: string;\n    settingsNs: string;\n    settingsPath: readonly string[];\n    declared?: boolean;\n}"
+          },
+          {
+            "name": "LlmDiscoveredModel",
+            "declaration": "export interface LlmDiscoveredModel {\n    id: string;\n    name?: string;\n    contextWindow?: number;\n    maxTokens?: number;\n}"
+          },
+          {
+            "name": "LlmFailure",
+            "declaration": "export interface LlmFailure {\n    readonly message: string;\n    readonly code: string;\n    readonly status?: number;\n    readonly providerRetryAfterMs?: number;\n    readonly requestId?: ProviderRequestId;\n}"
+          },
+          {
+            "name": "LlmImageRequestPrice",
+            "declaration": "export interface LlmImageRequestPrice {\n    visualTokens: number;\n    text: string;\n}"
+          },
+          {
+            "name": "LlmImageRequestPricing",
+            "declaration": "export interface LlmImageRequestPricing {\n    priceImages(images: readonly ImageAttachmentRef[]): readonly LlmImageRequestPrice[];\n}"
+          },
+          {
+            "name": "LlmModelContext",
+            "declaration": "export interface LlmModelContext {\n    contextWindow: number;\n}"
+          },
+          {
+            "name": "LlmModelDiscoveryRequest",
+            "declaration": "export interface LlmModelDiscoveryRequest {\n    provider?: string;\n    baseURL?: string;\n    api?: string;\n    apiKey?: string;\n}"
+          },
+          {
+            "name": "LlmModelInfo",
+            "declaration": "export interface LlmModelInfo {\n    provider: string;\n    id: string;\n    name: string;\n    description?: string;\n    inputModalities?: readonly ModelModality[];\n}"
+          },
+          {
+            "name": "LlmModelReasoningInfo",
+            "declaration": "export interface LlmModelReasoningInfo {\n    efforts: readonly LlmReasoningEffortInfo[];\n    defaultEffort?: ReasoningEffortId;\n}"
+          },
+          {
+            "name": "LlmProviderInfo",
+            "declaration": "export interface LlmProviderInfo {\n    id: string;\n    name: string;\n}"
+          },
+          {
+            "name": "LlmReasoningEffortInfo",
+            "declaration": "export interface LlmReasoningEffortInfo {\n    id: ReasoningEffortId;\n    name: string;\n    description?: string;\n}"
+          },
+          {
+            "name": "LlmResolvedModelInfo",
+            "declaration": "export interface LlmResolvedModelInfo extends LlmModelInfo {\n    context?: LlmModelContext;\n    defaultMaxTokens?: number;\n    reasoning?: LlmModelReasoningInfo;\n}"
+          },
+          {
+            "name": "Message",
+            "declaration": "export interface Message {\n    readonly id: MessageId;\n    readonly role: 'system' | 'user' | 'assistant';\n    readonly content: ContentBlock[];\n    readonly source: MessageSource;\n}"
+          },
+          {
+            "name": "MessageId",
+            "declaration": "export type MessageId = Branded<'MessageId'>;"
+          },
+          {
+            "name": "MessageSource",
+            "declaration": "export type MessageSource = MessageSourceMap[keyof MessageSourceMap];"
+          },
+          {
+            "name": "MessageSourceMap",
+            "declaration": "export interface MessageSourceMap {\n    user: { kind: 'user'; };\n    plugin: { kind: 'plugin'; plugin: string; } & ContextFormed;\n    model: ModelMessageSource;\n    tool: ToolMessageSource;\n    'agent-message': AgentMessageSource;\n    'subagent-settled': SubagentSettledMessageSource;\n    'agent-instructions': AgentInstructionSource;\n    'user-rpc': { kind: 'user'; rpcId: SessionRequestId; clientTimeZone?: string; };\n    'skill-invocation': SkillInvocationSource;\n    goal: GoalMessageSource;\n    'session-reference': SessionReferenceSource;\n}"
+          },
+          {
+            "name": "ModelMessageSource",
+            "declaration": "export interface ModelMessageSource extends AssistantProvenance {\n    kind: 'model';\n}"
+          },
+          {
+            "name": "ModelModality",
+            "declaration": "export type ModelModality = ModelModalityMap[keyof ModelModalityMap];"
+          },
+          {
+            "name": "ModelModalityMap",
+            "declaration": "export interface ModelModalityMap {\n    text: 'text';\n    image: 'image';\n}"
+          },
+          {
+            "name": "OptionalSessionSeq",
+            "declaration": "export type OptionalSessionSeq = SessionSeq | null;"
+          },
+          {
+            "name": "PreparedAdapterCall",
+            "declaration": "export interface PreparedAdapterCall {\n    readonly model: LlmResolvedModelInfo;\n    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;\n}"
+          },
+          {
+            "name": "PreparedLlmCall",
+            "declaration": "export interface PreparedLlmCall {\n    readonly config: LlmCallConfig;\n    readonly retryPolicy: ResolvedRetryPolicy;\n    readonly context?: LlmModelContext;\n    readonly inputModalities?: readonly ModelModality[];\n    readonly adapterDefaults: LlmCallConfigAdapterDefaults;\n    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;\n}"
+          },
+          {
+            "name": "ProviderRequestId",
+            "declaration": "export type ProviderRequestId = Branded<'ProviderRequestId'>;"
+          },
+          {
+            "name": "ReasoningBlock",
+            "declaration": "export interface ReasoningBlock {\n    type: 'reasoning';\n    text: string;\n}"
+          },
+          {
+            "name": "ReasoningEffortId",
+            "declaration": "export type ReasoningEffortId = Branded<'ReasoningEffortId'>;"
+          },
+          {
+            "name": "ReplayEnvelope",
+            "declaration": "export interface ReplayEnvelope {\n    response: unknown;\n    blocks?: readonly unknown[];\n}"
+          },
+          {
+            "name": "ResolvedAlwaysRetryPolicy",
+            "declaration": "export interface ResolvedAlwaysRetryPolicy extends ResolvedRetryBackoff {\n    readonly mode: 'always';\n}"
+          },
+          {
+            "name": "ResolvedNormalRetryPolicy",
+            "declaration": "export interface ResolvedNormalRetryPolicy extends ResolvedRetryBackoff {\n    readonly mode: 'normal';\n    readonly maxRetries: number;\n    readonly retryableCodes: readonly string[];\n}"
+          },
+          {
+            "name": "ResolvedRetryBackoff",
+            "declaration": "export interface ResolvedRetryBackoff {\n    readonly initialDelayMs: number;\n    readonly maxDelayMs: number;\n    readonly jitterRatio: number;\n}"
+          },
+          {
+            "name": "ResolvedRetryPolicy",
+            "declaration": "export type ResolvedRetryPolicy = ResolvedNormalRetryPolicy | ResolvedAlwaysRetryPolicy;"
+          },
+          {
+            "name": "SessionId",
+            "declaration": "export type SessionId = Branded<'SessionId'>;"
+          },
+          {
+            "name": "SessionReferenceSource",
+            "declaration": "export interface SessionReferenceSource {\n    kind: 'session-reference';\n    form: 'recall';\n    version: 1;\n    references: { sessionId: string; label: string; capturedFormatVersion?: number; capturedThroughSeq: OptionalSessionSeq; compacted: boolean; originalMessages: number; retainedMessages: number; omittedMessages: number; omittedBytes: number; truncated: boolean; inputIndex: number; }[];\n}"
+          },
+          {
+            "name": "SessionRequestId",
+            "declaration": "export type SessionRequestId = Branded<'session-request-id'>;"
+          },
+          {
+            "name": "SessionSeq",
+            "declaration": "export type SessionSeq = BrandedNumber<'SessionSeq'>;"
+          },
+          {
+            "name": "SkillInvocationSource",
+            "declaration": "export interface SkillInvocationSource {\n    readonly kind: 'skill-invocation';\n    readonly name: string;\n    readonly form: 'instructions';\n}"
+          },
+          {
+            "name": "StreamChunk",
+            "declaration": "export type StreamChunk = { type: 'block-start'; index: number; blockType: ContentBlockType; } | { type: 'text-delta'; index: number; text: string; } | { type: 'reasoning-delta'; index: number; text: string; } | { type: 'tool-call-delta'; index: number; id: ToolCallId; name?: string; argumentsDelta: string; } | { type: 'block-end'; index: number; block: ContentBlock; } | { type: 'usage'; usage: TokenUsage; } | { type: 'finish'; reason: FinishReason; replayState?: ReplayEnvelope; };"
+          },
+          {
+            "name": "SubagentSettledMessageSource",
+            "declaration": "export interface SubagentSettledMessageSource {\n    readonly kind: 'subagent-settled';\n    readonly form: 'notice';\n    readonly summary: string;\n    readonly senderSessionId: SessionId;\n}"
+          },
+          {
+            "name": "TextBlock",
+            "declaration": "export interface TextBlock {\n    type: 'text';\n    text: string;\n}"
+          },
+          {
+            "name": "TokenUsage",
+            "declaration": "export interface TokenUsage {\n    inputTokens: number;\n    outputTokens: number;\n    totalTokens?: number;\n    cacheReadTokens?: number;\n    cacheWriteTokens?: number;\n    reasoningTokens?: number;\n}"
+          },
+          {
+            "name": "ToolCallBlock",
+            "declaration": "export interface ToolCallBlock {\n    type: 'tool-call';\n    id: ToolCallId;\n    name: string;\n    arguments: string;\n}"
+          },
+          {
+            "name": "ToolCallId",
+            "declaration": "export type ToolCallId = Branded<'ToolCallId'>;"
+          },
+          {
+            "name": "ToolMessageSource",
+            "declaration": "export interface ToolMessageSource {\n    kind: 'tool';\n    callId: ToolCallId;\n}"
+          },
+          {
+            "name": "ToolResultBlock",
+            "declaration": "export interface ToolResultBlock {\n    type: 'tool-result';\n    toolCallId: ToolCallId;\n    content: ContentBlock[];\n    isError?: boolean;\n}"
+          },
+          {
+            "name": "ToolSchema",
+            "declaration": "export interface ToolSchema {\n    name: string;\n    description: string;\n    parameters: Record<string, unknown>;\n}"
+          }
+        ]
+      }
+    ],
+    "events": [
+      {
+        "description": "The provider topology changed: an adapter registered or unregistered routes, or the configurable-provider directory gained or lost entries. This payload-free registry notification fires at each commit point (including registration disposal); consumers re-read `listProviders()`, `listModels()`, or `listConfigurableProviders()` for the new state. Observer failures are contained and cannot veto the registry mutation.",
+        "summary": "The provider topology changed: an adapter registered or unregistered routes, or the configurable-provider directory gained or lost entries.",
+        "tags": [
+          {
+            "name": "mode",
+            "comment": "emit",
+            "text": "@mode emit"
+          }
+        ],
+        "jsDoc": "/**\n * The provider topology changed: an adapter registered or unregistered\n * routes, or the configurable-provider directory gained or lost entries.\n * This payload-free registry notification fires at each commit point\n * (including registration disposal); consumers re-read `listProviders()`,\n * `listModels()`, or `listConfigurableProviders()` for the new state.\n * Observer failures are contained and cannot veto the registry mutation.\n * @mode emit\n */",
+        "name": "llm/adapters-updated",
+        "mode": "emit",
+        "signature": "'llm/adapters-updated'(): void"
+      },
+      {
+        "description": "Waterfall around every streaming model call (retry, replay, routing). Bound to the {@link LlmRuntime}; call `next()` to reach the resolved adapter's stream, or yield your own chunks to short-circuit.",
+        "summary": "Waterfall around every streaming model call (retry, replay, routing).",
+        "tags": [
+          {
+            "name": "param",
+            "argument": "options",
+            "comment": "- the full request. A LOOP-built request carries the process-local {@link markAgentLoopRequest} identity and arrives deep-frozen (mutation throws): its content is a pure function of the session log (the reconstructability Agent Note), so listeners read it, never rewrite it. Hand-built calls do not carry that marker; their messages already obey the immutable creation contract.",
+            "text": "@param options - the full request. A LOOP-built request carries the\n     *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen\n     *   (mutation throws): its content is a pure function of the session log (the\n     *   reconstructability Agent Note), so listeners read it, never rewrite it.\n     *   Hand-built calls do not carry that marker; their messages already obey\n     *   the immutable creation contract.\n     *"
+          },
+          {
+            "name": "mode",
+            "comment": "waterfall",
+            "text": "@mode waterfall"
+          }
+        ],
+        "jsDoc": "/**\n * Waterfall around every streaming model call (retry, replay, routing).\n * Bound to the {@link LlmRuntime}; call `next()` to reach the resolved\n * adapter's stream, or yield your own chunks to short-circuit.\n * @param options - the full request. A LOOP-built request carries the\n *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen\n *   (mutation throws): its content is a pure function of the session log (the\n *   reconstructability Agent Note), so listeners read it, never rewrite it.\n *   Hand-built calls do not carry that marker; their messages already obey\n *   the immutable creation contract.\n * @mode waterfall\n */",
+        "name": "llm/stream",
+        "mode": "waterfall",
+        "signature": "'llm/stream'(this: LlmRuntime, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>"
+      }
+    ],
+    "objects": []
+  },
+}