@xlaunch/llm 0.2.0-beta.1

package/lib/types/error.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Harness error base with a stable machine-routable code and chained cause.
+ * Package errors extend it so tool results and replay can retain failure class.
+ * @module @xlaunch/llm/error
+ */
+/**
+ * Base class for all harness errors. Carries a `code` (stable, programmatic —
+ * e.g. `NO_ADAPTER`, `INVALID_ARGS`, `INVARIANT`) distinct from the
+ * human-readable `message`, and supports `cause` chaining via the standard
+ * `ErrorOptions`. `name` defaults to the subclass constructor name.
+ */
+export declare class HarnessError extends Error {
+    /** Stable machine-routable failure class (e.g. `RATE_LIMIT`); route on this, never by parsing `message`. */
+    readonly code: string;
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+/** Canonical provider-neutral code for a model request rejected because its context window was exceeded. */
+export declare const CONTEXT_WINDOW_EXCEEDED_CODE = "CONTEXT_WINDOW_EXCEEDED";
+/** Canonical provider-neutral code for an exhausted account quota or balance. */
+export declare const QUOTA_EXCEEDED_CODE = "QUOTA";
+/**
+ * Canonical provider-neutral code for a response that completed normally but
+ * carried no content blocks at all. Providers occasionally emit a degenerate
+ * completion (a terminal stop with zero output); adapters classify it as this
+ * failure instead of yielding an empty assistant message, because an empty
+ * message silently ends the turn with nothing for the user or the loop to act
+ * on. The attempt produced nothing durable, so retry policy treats it as safe
+ * to repeat.
+ */
+export declare const EMPTY_RESPONSE_CODE = "EMPTY_RESPONSE";
+/**
+ * Canonical provider-neutral code for a credential that was supplied but
+ * cannot be used — malformed rather than absent. Distinct from
+ * `MISSING_CREDENTIAL` because the fix differs: correct the stored value
+ * rather than supply one. Deliberately outside the default retryable set —
+ * a malformed credential fails identically on every attempt.
+ */
+export declare const INVALID_CREDENTIAL_CODE = "INVALID_CREDENTIAL";
+/**
+ * Recognize the context-overflow wording used by OpenAI-compatible providers
+ * and library adapters. Adapters pass all available provider code, type, and
+ * message text so both thrown and in-band delivery styles share one classifier.
+ * @param detail - provider error code/type/message text joined into one string.
+ * @returns true when the detail identifies a request exceeding the model context window.
+ */
+export declare function isContextWindowExceededError(detail: string): boolean;
+/**
+ * Recognize provider wording that identifies an exhausted account quota rather
+ * than a transient request-rate limit.
+ * @param detail - provider error code/type/message text joined into one string.
+ * @returns true only for terminal quota, balance, credit, budget, or usage-limit wording.
+ */
+export declare function isQuotaExceededError(detail: string): boolean;
+/**
+ * Render a thrown value with its full `cause` chain and AggregateError
+ * members, so transport wrappers like undici's `TypeError: fetch failed`
+ * surface the underlying failure instead of masking it. Plain structured
+ * failures render their own data-backed `message`. Diagnostic-surface
+ * rendering only (messages, notices, logs) — never parse the result; route on
+ * {@link HarnessError.code}.
+ * @param value - the caught value (`unknown` in catch clauses).
+ * @returns the outermost message first, each cause appended with `: ` (skipped
+ * when it repeats the wrapper message verbatim), and AggregateError members
+ * bracketed and `; `-joined.
+ */
+export declare function errorChain(value: unknown): string;
+/**
+ * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at runtime boundaries).
+ * @param value - the caught value (`unknown` in catch clauses).
+ * @returns true only for real instances; duck-typed or cross-realm errors do not narrow.
+ */
+export declare function isHarnessError(value: unknown): value is HarnessError;
+//# sourceMappingURL=error.d.ts.map

package/lib/types/error.js

@@ -0,0 +1,145 @@
+/**
+ * Harness error base with a stable machine-routable code and chained cause.
+ * Package errors extend it so tool results and replay can retain failure class.
+ * @module @xlaunch/llm/error
+ */
+/**
+ * Base class for all harness errors. Carries a `code` (stable, programmatic —
+ * e.g. `NO_ADAPTER`, `INVALID_ARGS`, `INVARIANT`) distinct from the
+ * human-readable `message`, and supports `cause` chaining via the standard
+ * `ErrorOptions`. `name` defaults to the subclass constructor name.
+ */
+export class HarnessError extends Error {
+    /** Stable machine-routable failure class (e.g. `RATE_LIMIT`); route on this, never by parsing `message`. */
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = new.target.name;
+    }
+}
+/** Canonical provider-neutral code for a model request rejected because its context window was exceeded. */
+export const CONTEXT_WINDOW_EXCEEDED_CODE = 'CONTEXT_WINDOW_EXCEEDED';
+/** Canonical provider-neutral code for an exhausted account quota or balance. */
+export const QUOTA_EXCEEDED_CODE = 'QUOTA';
+/**
+ * Canonical provider-neutral code for a response that completed normally but
+ * carried no content blocks at all. Providers occasionally emit a degenerate
+ * completion (a terminal stop with zero output); adapters classify it as this
+ * failure instead of yielding an empty assistant message, because an empty
+ * message silently ends the turn with nothing for the user or the loop to act
+ * on. The attempt produced nothing durable, so retry policy treats it as safe
+ * to repeat.
+ */
+export const EMPTY_RESPONSE_CODE = 'EMPTY_RESPONSE';
+/**
+ * Canonical provider-neutral code for a credential that was supplied but
+ * cannot be used — malformed rather than absent. Distinct from
+ * `MISSING_CREDENTIAL` because the fix differs: correct the stored value
+ * rather than supply one. Deliberately outside the default retryable set —
+ * a malformed credential fails identically on every attempt.
+ */
+export const INVALID_CREDENTIAL_CODE = 'INVALID_CREDENTIAL';
+/** Structured codes and plain phrases that explicitly name a context bound being exceeded. */
+const STRUCTURED_CONTEXT_OVERFLOW = new RegExp(String.raw `(?:^|[^a-z0-9])context[\s_-](?:length|window)[\s_-]`
+    + String.raw `(?:exceed(?:ed|s)?|overflow(?:ed)?|limit[\s_-]exceeded)(?:$|[^a-z0-9])`, 'i');
+/** Request-size wording that ties "too large" directly to model context capacity. */
+const TOO_LARGE_FOR_CONTEXT = new RegExp(String.raw `\b(?:request|prompt|input|messages?)\s+(?:is\s+|are\s+)?`
+    + String.raw `too\s+(?:large|long)\s+for\s+(?:(?:this|the)\s+)?`
+    + String.raw `(?:model(?:'s)?\s+)?context(?:\s+window)?\b`, 'i');
+/** "Exceeds" wording is safe only when its object is explicitly the model context. */
+const EXCEEDS_MODEL_CONTEXT = new RegExp(String.raw `\b(?:input|prompt|request|messages?)\b.{0,40}`
+    + String.raw `\b(?:exceed(?:s|ed)?|overflows?|is\s+larger\s+than)\b.{0,40}`
+    + String.raw `\b(?:the\s+)?(?:model(?:'s)?\s+)?context(?:\s+(?:length|window))?\b`, 'i');
+/**
+ * Recognize the context-overflow wording used by OpenAI-compatible providers
+ * and library adapters. Adapters pass all available provider code, type, and
+ * message text so both thrown and in-band delivery styles share one classifier.
+ * @param detail - provider error code/type/message text joined into one string.
+ * @returns true when the detail identifies a request exceeding the model context window.
+ */
+export function isContextWindowExceededError(detail) {
+    return STRUCTURED_CONTEXT_OVERFLOW.test(detail)
+        || /\b(?:maximum|max)(?:\s+(?:allowed|supported))?\s+context\s+(?:length|window)\b/i.test(detail)
+        || TOO_LARGE_FOR_CONTEXT.test(detail)
+        || /\b(?:input|prompt|request)\s+(?:is\s+)?too\s+(?:long|large)\s+for\s+(?:this|the)\s+model\b/i.test(detail)
+        || EXCEEDS_MODEL_CONTEXT.test(detail);
+}
+/**
+ * Recognize provider wording that identifies an exhausted account quota rather
+ * than a transient request-rate limit.
+ * @param detail - provider error code/type/message text joined into one string.
+ * @returns true only for terminal quota, balance, credit, budget, or usage-limit wording.
+ */
+export function isQuotaExceededError(detail) {
+    return /\binsufficient[\s_-]+(?:quota|balance|credits?)\b/i.test(detail)
+        || /\b(?:quota|usage[\s_-]+limit)[\s_-]+(?:exceeded|exhausted|reached)\b/i.test(detail)
+        || /\bexceed(?:ed|s)?[\s_-]+(?:(?:your|the)[\s_-]+)?(?:current[\s_-]+)?quota\b/i.test(detail)
+        || /\b(?:balance|credits?)[\s_-]+(?:exhausted|depleted)\b/i.test(detail)
+        || /\bout[\s_-]+of[\s_-]+(?:credits?|budget)\b/i.test(detail);
+}
+/**
+ * Render a thrown value with its full `cause` chain and AggregateError
+ * members, so transport wrappers like undici's `TypeError: fetch failed`
+ * surface the underlying failure instead of masking it. Plain structured
+ * failures render their own data-backed `message`. Diagnostic-surface
+ * rendering only (messages, notices, logs) — never parse the result; route on
+ * {@link HarnessError.code}.
+ * @param value - the caught value (`unknown` in catch clauses).
+ * @returns the outermost message first, each cause appended with `: ` (skipped
+ * when it repeats the wrapper message verbatim), and AggregateError members
+ * bracketed and `; `-joined.
+ */
+export function errorChain(value) {
+    // Tracks the active recursion path (entries removed on exit), so only true
+    // cycles are flagged and a diamond-shared cause still renders in full.
+    const path = new Set();
+    const render = (current) => {
+        if (path.has(current))
+            return '<circular cause>';
+        path.add(current);
+        try {
+            if (!(current instanceof Error)) {
+                if (typeof current === 'object' && current !== null) {
+                    const descriptor = Object.getOwnPropertyDescriptor(current, 'message');
+                    if (descriptor !== undefined && 'value' in descriptor && typeof descriptor.value === 'string') {
+                        return descriptor.value;
+                    }
+                }
+                return String(current);
+            }
+            const message = current.message === '' ? current.name : current.message;
+            const members = current instanceof AggregateError && current.errors.length > 0
+                ? ` [${current.errors.map(render).join('; ')}]`
+                : '';
+            const causeText = current.cause === undefined || current.cause === null
+                ? ''
+                : render(current.cause);
+            // Wrappers like `new HarnessError(String(value), code, { cause: value })`
+            // repeat their cause verbatim; rendering it again would only add noise.
+            const cause = causeText === '' || causeText === message ? '' : `: ${causeText}`;
+            return `${message}${members}${cause}`;
+        }
+        catch {
+            // Only hostile coercion or hostile accessors (a throwing toString /
+            // Symbol.toPrimitive on a non-Error, or a throwing message/name/cause/
+            // errors getter on an Error subclass): this renderer feeds UI notices
+            // and logs, so nothing may escape. Inner frames catch their own throws,
+            // so only the hostile node collapses, not the whole chain.
+            return '<unrenderable value>';
+        }
+        finally {
+            path.delete(current);
+        }
+    };
+    return render(value);
+}
+/**
+ * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at runtime boundaries).
+ * @param value - the caught value (`unknown` in catch clauses).
+ * @returns true only for real instances; duck-typed or cross-realm errors do not narrow.
+ */
+export function isHarnessError(value) {
+    return value instanceof HarnessError;
+}
+//# sourceMappingURL=error.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,408 @@
+/**
+ * LLM service: adapter registry with a waterfall-interceptable streaming call
+ * API. Exports the `LlmRuntime` default, the abstract `LlmAdapter` for
+ * provider backends, and `BlockAssembler` for chunk assembly.
+ *
+ * @module @xlaunch/llm
+ */
+import { Context } from '@xlaunch/cordis';
+import { TypertRemoteService } from '@xlaunch/typert-protocol';
+import type { GenerateOptions, LlmConfigurableProvider, LlmDiscoveredModel, LlmFailure, LlmImageRequestPricing, LlmModelContext, LlmModelDiscoveryRequest, LlmModelInfo, LlmResolvedModelInfo, LlmProviderInfo, ModelModality, StreamChunk } from './types.ts';
+import type { ResolvedRetryPolicy } from './retry-policy.ts';
+import type { ProviderRequestId } from './brand.ts';
+import type { LlmCallConfig, LlmCallConfigAdapterDefaults } from './call-config.ts';
+import { HarnessError } from './error.ts';
+import type { FileAttachmentRef } from '@xlaunch/attachment';
+export * from './attribution.ts';
+export * from './brand.ts';
+export * from './error.ts';
+export * from './api-key.ts';
+export * from './types.ts';
+export * from './content.ts';
+export * from './assistant-stream.ts';
+export * from './message.ts';
+export * from './retry-policy.ts';
+export { BlockAssembler } from './assembler.ts';
+export { callConfigEquals, isAgentLoopRequest, markAgentLoopRequest } from './call-config.ts';
+export type { LlmCallConfig, LlmCallConfigAdapterDefaults } from './call-config.ts';
+declare module '@xlaunch/cordis' {
+    interface Context {
+        llm: LlmRuntime;
+    }
+    interface Events {
+        /**
+         * 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.
+         * @param options - 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.
+         * @mode waterfall
+         */
+        'llm/stream'(this: LlmRuntime, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>;
+    }
+}
+/** Structured provider facts and cause accepted by {@link LlmError}. */
+export interface LlmErrorOptions extends ErrorOptions {
+    /** Valid HTTP status observed at the provider boundary. */
+    status?: number;
+    /** Positive finite provider-requested delay in milliseconds. */
+    providerRetryAfterMs?: number;
+    /** Non-empty opaque provider request id. */
+    requestId?: ProviderRequestId;
+}
+/**
+ * Typed error for LLM-related failures. Extends {@link HarnessError}, so the
+ * `code` string (e.g. `AUTH`, `RATE_LIMIT`, `NO_ADAPTER`) is shared taxonomy.
+ */
+export declare class LlmError extends HarnessError {
+    /** Serializable facts retained beside this live Error. */
+    readonly failure: LlmFailure;
+    /**
+     * @param message - non-empty human-readable failure summary.
+     * @param code - non-empty stable provider-neutral machine code.
+     * @param options - optional cause and validated serializable provider facts.
+     */
+    constructor(message: string, code: string, options?: LlmErrorOptions);
+}
+/**
+ * Accept one supplied credential, or refuse it as unusable.
+ *
+ * A stored key arrives from the credentials seam, a `.env` line, or a shell
+ * export, all of which pick up surrounding whitespace, so trimming is silent.
+ * Anything else fails here rather than inside `fetch`, whose ByteString
+ * refusal names a UTF-16 code point instead of the setting to change. The key
+ * never enters the message: `ref` names where to fix it, and echoing any part
+ * of a secret into a log or a UI is the failure this diagnosis avoids.
+ *
+ * Lives beside {@link LlmError} rather than in `./api-key.ts` so the predicate
+ * module stays dependency-free; every adapter shares this one diagnosis instead
+ * of keeping near-identical local copies.
+ * @param raw - the credential exactly as supplied.
+ * @param pkg - the refusing package name, prefixed to the diagnostic.
+ * @param ref - the credential reference the value resolved through.
+ * @returns the trimmed, usable key.
+ */
+export declare function assertUsableApiKey(raw: string, pkg: string, ref: string): string;
+/** One model call whose config and adapter registration were resolved together. */
+export interface PreparedLlmCall {
+    /** Detached, deep-frozen config with any adapter-owned default materialized. */
+    readonly config: LlmCallConfig;
+    /** Immutable retry policy captured with the adapter registration. */
+    readonly retryPolicy: ResolvedRetryPolicy;
+    /** Detached context metadata resolved with the registration-bound call. */
+    readonly context?: LlmModelContext;
+    /** Exact model modalities captured with the adapter dispatch generation. */
+    readonly inputModalities?: readonly ModelModality[];
+    /** Config fields materialized by the captured adapter rather than proposed by the caller. */
+    readonly adapterDefaults: LlmCallConfigAdapterDefaults;
+    /**
+     * Dispatch this call once through the registration captured during
+     * preparation. The request's call-config fields must match {@link config};
+     * reuse or mismatch fails with `INVALID_PREPARED_CALL`.
+     * @param options - fully assembled request carrying the prepared config.
+     * @returns the chunk stream, including the `llm/stream` waterfall.
+     */
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/** One adapter-owned model-resolution generation bound to its eventual stream call. */
+export interface PreparedAdapterCall {
+    /** Exact model metadata from the same adapter generation as {@link stream}. */
+    readonly model: LlmResolvedModelInfo;
+    /** Dispatch through that generation without re-reading dynamic connection facts. */
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/**
+ * Provider-wire adapter for the harness message and stream vocabulary. Register implementations
+ * with `ctx.llm.registerAdapter(providers, adapter)`. Every provider HTTP request must include
+ * `attributionHeaders()`; prove the headers are added in the wire request or library header hook. The
+ * library-backed gateway adapter meets this contract through gateway's header hook.
+ */
+export declare abstract class LlmAdapter {
+    /**
+     * Describe one provider route owned by this adapter.
+     * @param provider - a route passed to `registerAdapter()` for this instance.
+     * @returns detached display metadata whose id must equal `provider`.
+     */
+    providerInfo(provider: string): LlmProviderInfo;
+    /**
+     * Return the provider-owned retry policy captured with this route.
+     * @param _provider - a route passed to `registerAdapter()` for this instance.
+     * @returns a resolved policy, or `undefined` to use the normal defaults.
+     */
+    providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined;
+    /**
+     * Resolve provider-side request-image pricing for one exact model route.
+     * The default declares none, so consumers fall back to their own neutral
+     * estimate. Implementations must answer synchronously without I/O; the
+     * token meter resolves this per measurement.
+     * @param _provider - a route passed to `registerAdapter()` for this instance.
+     * @param _model - exact model id passed to {@link GenerateOptions.model}.
+     * @returns route-owned image pricing, or `undefined` when the route declares none.
+     */
+    imageRequestPricing(_provider: string, _model: string): LlmImageRequestPricing | undefined;
+    /**
+     * List models this adapter can currently advertise for one owned provider.
+     * The result is advisory: an adapter may accept unlisted model ids, and
+     * consumers must not turn absence into request rejection.
+     * @param _provider - one provider route owned by this adapter.
+     * @returns discoverable models in adapter-preferred order.
+     */
+    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    /**
+     * Resolve all metadata available for one exact model. This query is
+     * independent of the advisory catalog and does not validate request routing.
+     * @param provider - one provider route owned by this adapter.
+     * @param model - exact model id passed to {@link GenerateOptions.model}.
+     * @param _signal - cancellation for this exact-model lookup; asynchronous
+     *   implementations must settle promptly after it aborts.
+     * @returns provider/model identity plus any context, call-default, and reasoning metadata.
+     */
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    /**
+     * Bind exact model metadata and the eventual request dispatch to one adapter generation.
+     * Dynamic adapters override this so settings changes between preparation and
+     * dispatch cannot combine one generation's capabilities with another's endpoint.
+     * @param provider - registered provider route.
+     * @param model - exact model id.
+     * @param signal - cancellation for model resolution.
+     * @returns model metadata and a one-generation stream entry point.
+     */
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    /**
+     * Stream one model call as raw chunks. The only required method.
+     * @param options - the fully-assembled request; implementations must honor `options.signal`.
+     * @returns the chunk stream, obeying the adapter contract documented on `StreamChunk`.
+     */
+    abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/**
+ * What {@link LlmRuntime.registerAdapter} returns: the disposer, plus an
+ * atomic route replacement for the same adapter instance.
+ */
+export interface AdapterRegistrationHandle {
+    /** Release every route this registration currently holds. */
+    (): void;
+    /**
+     * Replace this registration's routes with `providers`, keeping the same
+     * adapter instance. The candidate set is validated in full first — a
+     * conflict with another adapter, an invalid name, or bad provider metadata
+     * throws and leaves the current routes untouched — and the swap itself is
+     * one synchronous section, so no request can observe a gap. An empty array
+     * is legal here (a settings section that emptied holds zero routes while
+     * staying registered), unlike an empty initial registration.
+     *
+     * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
+     * has been released: its routes are gone and its disposer has already run,
+     * so anything registered afterwards would have no owner left to release it.
+     * @param providers - the complete next route set for this registration.
+     */
+    replace(providers: string[]): void;
+}
+/**
+ * A live configurable-provider registration, disposable and atomically
+ * replaceable — the directory counterpart of {@link AdapterRegistrationHandle}.
+ */
+export interface DirectoryRegistrationHandle {
+    /** Withdraw every entry this registration currently holds. */
+    (): void;
+    /**
+     * Replace this registration's entries with `entries`. The candidate set is
+     * validated in full first — an entry another registration already declares,
+     * a duplicate within the set, or invalid metadata throws and leaves the
+     * current entries untouched — and the swap is one synchronous section, so no
+     * reader observes a gap. An empty array is legal here, unlike an empty
+     * initial registration.
+     *
+     * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
+     * has been disposed.
+     */
+    replace(entries: readonly LlmConfigurableProvider[]): void;
+}
+/**
+ * The abstract `llm` service: an adapter registry plus a streaming model-call
+ * API, interceptable via the `llm/stream` waterfall.
+ */
+export declare class LlmRuntime extends TypertRemoteService {
+    private adapters;
+    private directory;
+    private discoveries;
+    constructor(ctx: Context);
+    /** Notify topology observers without letting one broken listener veto the commit. */
+    private emitAdaptersUpdated;
+    /** Contained-listener diagnostic shared by the sync and async failure paths. */
+    private warnAdaptersListenerFailure;
+    /**
+     * Register an adapter for the given provider routes. Throws `LlmError` with code
+     * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).
+     * Disposed with the fiber.
+     * @param providers - every provider route this adapter should serve.
+     * @param adapter - the adapter that streams calls for those providers.
+     * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
+     */
+    registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle;
+    /**
+     * Validate one candidate route set for `adapter`, treating routes this
+     * registration already holds as available. Nothing is mutated: a rejected
+     * candidate leaves the registry exactly as it was.
+     */
+    private prepareRoutes;
+    /**
+     * Swap this registration's routes for the prepared ones in one synchronous
+     * section, so no observer can see the registry between the release and the
+     * re-registration. The route set's one mutation point is also where
+     * `llm/adapters-updated` is published, so a `replace` announces itself
+     * exactly like a first registration.
+     */
+    private commitRoutes;
+    /**
+     * Describe provider routes with a registered adapter.
+     * @returns detached provider metadata in registration order.
+     */
+    listProviders(): LlmProviderInfo[];
+    /**
+     * Declare provider routes an adapter plugin can activate through
+     * configuration. Registration is all-or-nothing: an empty list, invalid
+     * entry, or a provider already declared by any registration throws
+     * `LlmError` without registering the rest. Disposed with the fiber.
+     * @param entries - every configurable provider this plugin owns.
+     * @returns a handle that withdraws all of them, and can atomically replace them.
+     */
+    registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle;
+    /**
+     * List every declared configurable provider, registered or dormant.
+     * @returns detached directory entries in declaration order.
+     */
+    listConfigurableProviders(): LlmConfigurableProvider[];
+    /**
+     * Offer to interrogate provider endpoints on behalf of the settings
+     * namespace this plugin owns. The namespace is the key because that is what
+     * a configuration surface already holds from the configurable-provider
+     * directory, and because a provider being *added* has no route to name yet.
+     * Disposed with the fiber.
+     * @param settingsNs - the namespace whose profiles this discovery serves.
+     * @param discover - interrogates one endpoint and must honor the supplied signal.
+     * @returns the disposer that withdraws the offer.
+     */
+    registerModelDiscovery(settingsNs: string, discover: (request: LlmModelDiscoveryRequest, signal?: AbortSignal) => Promise<readonly LlmDiscoveredModel[]>): () => void;
+    /**
+     * Interrogate one provider endpoint for the models it advertises. The
+     * request describes a draft, not a stored route, so nothing here reads or
+     * writes settings or credentials — the caller owns both, and the reply is
+     * candidate metadata a surface may offer for adoption.
+     * @param settingsNs - namespace whose registered discovery serves this draft.
+     * @param request - the endpoint, protocol, and one-shot credential to use.
+     * @param signal - caller cancellation.
+     * @returns the advertised models, deduplicated in endpoint order.
+     */
+    discoverModels(settingsNs: string, request: LlmModelDiscoveryRequest, signal?: AbortSignal): Promise<LlmDiscoveredModel[]>;
+    /**
+     * Remote adapter for one draft provider interrogation.
+     * @param settingsNs - namespace whose registered discovery serves this draft.
+     * @param request - endpoint, protocol, and one-shot credential to use.
+     * @param signal - caller cancellation supplied by the Remote carrier.
+     * @returns advertised models in endpoint order.
+     * @throws RemoteError with `llm/model-discovery-rejected` when discovery refuses or fails.
+     */
+    remoteDiscoverModels(settingsNs: string, request: LlmModelDiscoveryRequest, signal: AbortSignal): Promise<LlmDiscoveredModel[]>;
+    /**
+     * Resolve the retry policy captured when one provider route was registered.
+     * @param provider - registered provider route to inspect.
+     * @returns the provider-owned policy, with normal defaults already resolved.
+     */
+    providerRetryPolicy(provider: string): ResolvedRetryPolicy;
+    /**
+     * Resolve provider-side request-image pricing for one exact route, or
+     * `undefined` when the provider is unregistered or declares none. Unknown
+     * providers degrade to `undefined` rather than throwing because callers
+     * price durable history whose route may no longer be mounted.
+     * @param provider - provider route named by a request header.
+     * @param model - exact model id named by the same header.
+     * @returns the owning adapter's image pricing for the route, when declared.
+     */
+    imageRequestPricing(provider: string, model: string): LlmImageRequestPricing | undefined;
+    /**
+     * Resolve the exact text one durable file occurrence contributes to every
+     * provider request in the current execution environment.
+     * @param ref - durable verbatim file reference from model history.
+     * @returns the same deterministic handle text used at adapter dispatch.
+     */
+    fileRequestText(ref: FileAttachmentRef): string;
+    /** Detach typed adapter-owned modality metadata. */
+    private detachedModalities;
+    /**
+     * Discover models advertised by one registered provider. Catalog membership
+     * is advisory and never changes routing or request validation.
+     * @param provider - registered provider route to inspect.
+     * @returns detached model metadata in adapter-preferred order.
+     */
+    listModels(provider: string): Promise<LlmModelInfo[]>;
+    /**
+     * Resolve and validate all metadata from the adapter that owns one exact
+     * route. The result is detached from adapter-owned objects; catalog
+     * membership remains advisory and does not control request routing.
+     * @param provider - registered provider route to inspect.
+     * @param model - exact model id passed to the adapter.
+     * @param signal - optional cancellation for adapter-owned asynchronous lookup.
+     * @returns exact model identity plus available context and reasoning metadata.
+     */
+    resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    private resolveModelInfoFor;
+    /** Validate and detach one adapter-returned exact model result. */
+    private normalizeModelInfo;
+    /**
+     * Validate a conversation call config against its exact model capability and
+     * materialize adapter-configured defaults. Unsupported explicit efforts
+     * reject before provider I/O; no clamping or aliasing is performed. This
+     * standalone query does not bind a later dispatch; use {@link prepareCall}
+     * when logging and streaming must share one adapter registration.
+     * @param config - provider/model route and optional request controls.
+     * @param signal - optional cancellation for adapter-owned capability lookup.
+     * @returns a detached config only when a default must be materialized.
+     */
+    resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>;
+    private resolveCallFor;
+    /** Validate request controls against one already-bound exact model result. */
+    private resolveCallWithInfo;
+    /**
+     * Resolve one call under its current adapter registration. The returned
+     * one-shot handle keeps that registration across header logging and dispatch,
+     * so HMR cannot combine one adapter's capability result with another adapter.
+     * @param config - provider/model route and optional request controls.
+     * @param signal - optional cancellation for adapter-owned capability lookup.
+     * @returns a prepared config and its registration-bound stream entry point.
+     */
+    prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>;
+    private registration;
+    /** Remove replay state whose historical route is owned by another adapter. */
+    private forAdapter;
+    /**
+     * Resolve the current execution-world read path of one durable file
+     * reference through the mounted attachment and filesystem providers.
+     */
+    private fileReadPath;
+    /**
+     * Final adapter boundary. Adapter selection, dispatch, iterator construction,
+     * and iteration failures become one terminal failure chunk. Middleware and
+     * downstream consumer failures remain thrown plugin or consumer errors.
+     */
+    private adapterStream;
+    /**
+     * Stream one model call as raw chunks (token-level deltas). Replay state is
+     * retained only when the same adapter instance owns its historical provider
+     * and the target provider. Final adapter selection remains fixed through
+     * asynchronous exact-model resolution and dispatch. Adapter selection,
+     * dispatch, and iteration failures become terminal `error` or `aborted`
+     * finish chunks; middleware, nested-call, cleanup, and consumer failures
+     * remain thrown.
+     * @param options - the full request; `options.provider` selects the adapter.
+     * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
+     */
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    private streamWithRegistration;
+}
+export default LlmRuntime;
+//# sourceMappingURL=index.d.ts.map