@vedmalex/ai-connect 0.2.0

package/dist/types/types.d.ts

@@ -0,0 +1,1346 @@
+export type ProviderId = string;
+export type TransportKind = "api" | "acp" | "cli" | "server";
+export type RuntimeKind = "browser" | "local";
+export type RouteRuntime = "browser" | "local" | "universal";
+export type OperationKind = "text" | "image" | "file";
+export type ClientOperationName = "generate" | "stream" | "verify" | "discoverAcpModels" | "discoverModels" | "checkHealth" | "probeModels";
+export type AcpPermissionMode = "deny-all" | "approve-reads" | "approve-all";
+export type RoutingStrategy = "priority" | "round-robin" | "weighted-round-robin" | "failover";
+export type RouteHealthState = "ready" | "cooling_down" | "degraded" | "unavailable";
+export type AiConnectErrorCode = "rate_limit" | "quota_exhausted" | "invalid_credentials" | "auth_error" | "unsupported_capability" | "temporary_unavailable" | "local_harness_unavailable" | "validation_error" | "not_supported" | "aborted" | "timeout" | "fanout_limit";
+/**
+ * Why a derived abort signal fired. `caller` → user/consumer cancelled (partials discarded);
+ * `timeout` → an operation deadline elapsed. Used by `mapAbortError` to pick the terminal code.
+ */
+export type AbortReason = "caller" | "timeout";
+export type FallbackAction = "retry" | "rotate-credential" | "rotate-account" | "fallback-model" | "fallback-transport" | "fallback-provider";
+export type MessageRole = "system" | "user" | "assistant" | "tool";
+export type PortableFileKind = "path" | "remote" | "data-url" | "browser-file" | "browser-blob";
+export type ThinkingMode = "enabled" | "disabled" | "adaptive";
+export type ThinkingEffort = "low" | "medium" | "high" | "max";
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type ImageSizePreset = "1024x1024" | "1280x720" | "720x1280" | "1216x896" | "1200x1696" | "848x1200" | "600x848" | "424x600" | "597x822" | "747x1122" | "822x1122" | "897x1479" | "1122x1797" | "1536x1024" | "1024x1536" | "auto";
+export interface RouteCapabilities {
+    browserSafe: boolean;
+    localOnly: boolean;
+    requiresFilesystem: boolean;
+    requiresInstalledBinary: boolean;
+    requiresAuthenticatedSession: boolean;
+    supportsStreaming: boolean;
+    supportsToolSchema: boolean;
+    supportsToolExecution: boolean;
+    supportsClientToolExecution: boolean;
+    supportsFileUpload: boolean;
+    supportsFileOutput: boolean;
+    supportsImageInput: boolean;
+    supportsImageOutput: boolean;
+    supportsProfileVerification: boolean;
+    supportsCredentialRotation: boolean;
+    supportsAccountRotation: boolean;
+}
+/**
+ * Generalized execution-context mode (C7 / CD-10). `workspace` lets ai-connect inject its
+ * ambient ACP launch context (skills/rules/cwd); `clean` suppresses ALL ai-connect-injected
+ * ambient — only consumer messages/attachments + explicit route config (systemPrompt /
+ * defaultResponseFormat) reach the wire (INV-CLEAN-1).
+ */
+export type ContextMode = "workspace" | "clean";
+/**
+ * ACP launch context mode. Re-rooted onto {@link ContextMode} as an identity-preserving alias
+ * (R22): the underlying string-literal union is byte-identical, so every existing
+ * `=== "clean"` / `=== "workspace"` narrowing in acp.ts continues to typecheck unchanged.
+ */
+export type AcpContextMode = ContextMode;
+/**
+ * Per-route model-allowlist enforcement (C7). `strict` (default) → only `advertisedModels` may
+ * be requested; an undeclared `routeHints.model` DROPS the route (never silently billed).
+ * `shortlist` → `advertisedModels` is advisory; an undeclared model is passed through verbatim.
+ */
+export type ModelAllowlistMode = "strict" | "shortlist";
+/**
+ * How `resolveRouteRefs`/`resolveRouteSelectors` treat a selector that matches no route (C7).
+ * `error` (default) → throw (existing behaviour, byte-identical for current callers);
+ * `default` → substitute the configured default route for EACH unmatched selector (OQ-8
+ * per-unmatched substitution); `off` → silently drop the unmatched selector (degrade).
+ */
+export type UnknownSelectorPolicy = "error" | "default" | "off";
+export type AcpSkillsMode = "default" | "disabled";
+export type CliTransportPresetId = "gemini" | "qwen" | "claude" | "openclaude" | "codex";
+export type CliDiscoveryVia = "none" | "acp";
+export interface AcpLaunchOptionsInput {
+    contextMode?: AcpContextMode;
+    skillsMode?: AcpSkillsMode;
+}
+export interface AcpLaunchOptions {
+    contextMode: AcpContextMode;
+    skillsMode: AcpSkillsMode;
+}
+export interface CliDiscoveryAcpOptionsInput {
+    providerId?: string;
+    transportId?: string;
+    auth?: {
+        methodId: string;
+        params?: Record<string, unknown>;
+    };
+    launch?: AcpLaunchOptionsInput;
+}
+export interface CliDiscoveryOptionsInput {
+    via?: CliDiscoveryVia;
+    acp?: CliDiscoveryAcpOptionsInput;
+}
+export interface CliJsonLineSelectorInput {
+    path: string;
+    wherePath?: string;
+    whereEquals?: string | number | boolean;
+}
+export interface CliJsonParserInput {
+    kind: "json";
+    textPath: string;
+    errorPath?: string;
+    usagePath?: string;
+}
+export interface CliJsonlParserInput {
+    kind: "jsonl";
+    text: CliJsonLineSelectorInput;
+    error?: CliJsonLineSelectorInput;
+    usage?: CliJsonLineSelectorInput;
+}
+export type CliTransportParserInput = CliJsonParserInput | CliJsonlParserInput;
+export interface CliDiscoveryAcpOptions {
+    providerId?: string;
+    transportId?: string;
+    auth?: {
+        methodId: string;
+        params: Record<string, unknown>;
+    };
+    launch?: AcpLaunchOptions;
+}
+export interface CliDiscoveryOptions {
+    via: CliDiscoveryVia;
+    acp?: CliDiscoveryAcpOptions;
+}
+export interface CliTransportOptionsInput {
+    preset?: CliTransportPresetId;
+    argsTemplate?: string[];
+    parser?: CliTransportParserInput;
+    discovery?: CliDiscoveryOptionsInput;
+}
+export interface CliJsonLineSelector {
+    path: string;
+    wherePath?: string;
+    whereEquals?: string | number | boolean;
+}
+export interface CliJsonParser {
+    kind: "json";
+    textPath: string;
+    errorPath?: string;
+    usagePath?: string;
+}
+export interface CliJsonlParser {
+    kind: "jsonl";
+    text: CliJsonLineSelector;
+    error?: CliJsonLineSelector;
+    usage?: CliJsonLineSelector;
+}
+export type CliTransportParser = CliJsonParser | CliJsonlParser;
+export interface CliTransportOptions {
+    preset?: CliTransportPresetId;
+    argsTemplate?: string[];
+    parser?: CliTransportParser;
+    discovery?: CliDiscoveryOptions;
+}
+export interface TransportDescriptorInput {
+    kind: TransportKind;
+    id?: string;
+    command?: string;
+    baseUrl?: string;
+    cli?: CliTransportOptionsInput;
+    auth?: {
+        methodId: string;
+        params?: Record<string, unknown>;
+    };
+    launch?: AcpLaunchOptionsInput;
+}
+export interface CredentialConfigInput {
+    id?: string;
+    apiKey?: string;
+    apiKeyEnv?: string;
+    apiKeyDelimiter?: string;
+    source?: string;
+    weight?: number;
+    metadata?: Record<string, string>;
+}
+export interface VerificationConfigInput {
+    env?: string[];
+    command?: string;
+    session?: string;
+}
+export interface AccountConfigInput {
+    id?: string;
+    transport: TransportKind | TransportDescriptorInput;
+    profile?: string;
+    runtime?: RouteRuntime;
+    /**
+     * Declared models. Each entry is a bare id string (back-compat) OR a `{ id, contextWindow }`
+     * object (C4). A bare string inherits the account-level `contextWindow`; an object overrides
+     * it for that model only.
+     */
+    models: ModelInput[];
+    /** Account-level default context window inherited by string-form `models` entries (C4). */
+    contextWindow?: number;
+    credentials?: CredentialConfigInput[];
+    capabilities?: Partial<RouteCapabilities>;
+    verify?: VerificationConfigInput;
+    weight?: number;
+    priority?: number;
+    enabled?: boolean;
+    /** Model-allowlist enforcement for this account's routes (C7; default `strict`). */
+    modelAllowlistMode?: ModelAllowlistMode;
+    /**
+     * Per-route default response format injected onto a candidate ONLY when the caller did not
+     * supply `parameters.responseFormat` (C7 / R14, idempotent on retry+fallback). Preserved even
+     * in `clean` context mode (CD-15 — clean suppresses ambient, not explicit config).
+     */
+    defaultResponseFormat?: GenerateResponseFormat;
+    /**
+     * Per-route system prompt injected as a leading system message ONLY when the caller authored
+     * no system message (C7 / R14). Preserved in `clean` mode (explicit config, not ambient).
+     */
+    systemPrompt?: string;
+    /** Execution-context mode for this account's routes (C7; default `workspace`). */
+    contextMode?: ContextMode;
+}
+export interface ProviderConfigInput {
+    accounts: AccountConfigInput[];
+}
+export interface OperationRoutingInput {
+    strategy?: RoutingStrategy;
+    pool?: string[];
+}
+export interface RoutingFallbackInput {
+    on?: Partial<Record<AiConnectErrorCode, FallbackAction[]>>;
+    cooldownMs?: Partial<Record<AiConnectErrorCode, number>>;
+}
+export interface RoutingRetryInput {
+    maxAttempts?: Partial<Record<AiConnectErrorCode, number>>;
+    delayMs?: Partial<Record<AiConnectErrorCode, number>>;
+}
+/**
+ * Selector-resolution policy (C7 / OQ-8). Controls how an unmatched route selector is handled
+ * when expanding `routeHints.pool`/operation pools. Default behaviour (omitted) is `error`,
+ * preserving byte-identical semantics for every existing caller.
+ */
+export interface RouteResolutionConfigInput {
+    unknownSelector?: UnknownSelectorPolicy;
+    /**
+     * Route ref (any alias) substituted for each unmatched selector when
+     * `unknownSelector === "default"`. `defineConfig` fails fast if this does not resolve to
+     * exactly one route (INV-ROUTE — fail-fast on ambiguous/missing default).
+     */
+    defaultRouteId?: string;
+}
+export interface NormalizedRouteResolutionConfig {
+    unknownSelector: UnknownSelectorPolicy;
+    /** Resolved single route id used for `default` substitution; absent unless policy is `default`. */
+    defaultRouteId?: string;
+}
+export interface RoutingConfigInput {
+    strategy?: RoutingStrategy;
+    operations?: Partial<Record<OperationKind, string[] | OperationRoutingInput>>;
+    fallback?: RoutingFallbackInput;
+    retry?: RoutingRetryInput;
+    shuffleOnInit?: boolean;
+    resolution?: RouteResolutionConfigInput;
+}
+export interface AiConnectConfigInput {
+    providers: Record<string, ProviderConfigInput>;
+    routing?: RoutingConfigInput;
+}
+export interface PortableFile {
+    id: string;
+    kind: PortableFileKind;
+    name: string;
+    mimeType?: string;
+    size?: number;
+    source: unknown;
+}
+export interface RemoteFileReferenceInput {
+    id?: string;
+    providerFileId?: string;
+    uri?: string;
+    name?: string;
+    mimeType?: string;
+    size?: number;
+}
+export type PortableFileInput = PortableFile | RemoteFileReferenceInput | string | Blob | File;
+/**
+ * Coarse multimodal category derived from a portable file's MIME type / name.
+ * `document` covers PDFs (and any other SUPPORTED_DOCUMENT_MIME_TYPES member);
+ * `image` covers `image/*`; `text` covers text-extractable resources; everything
+ * else is `other`. (C6 — UR-003/UR-012.)
+ */
+export type PortableFileCategory = "image" | "document" | "text" | "other";
+/**
+ * The single decode product of `materializePortableFile` (C6). One pass over a
+ * portable file resolves the category + MIME type and, depending on what the
+ * source offers, populates exactly the carriers a provider builder needs:
+ * `base64` (raw, no data-url prefix) and `dataUrl` for inline images/PDFs,
+ * `uri` for remote references, `text` for text-extractable resources, and
+ * `providerFileId` when a Files-API upload has already produced one. Builders
+ * pick the carrier their wire shape requires; no builder re-decodes.
+ */
+export interface PortableFilePayload {
+    category: PortableFileCategory;
+    mimeType: string;
+    name: string;
+    base64?: string;
+    dataUrl?: string;
+    uri?: string;
+    text?: string;
+    providerFileId?: string;
+}
+export interface ToolCallInput {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface MessageInput {
+    role: MessageRole;
+    content: string;
+    toolCalls?: ToolCallInput[];
+    toolCallId?: string;
+    toolName?: string;
+    isError?: boolean;
+    data?: unknown;
+}
+export interface GenerateToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+export type GenerateToolChoice = "auto" | "required" | "none" | {
+    type: "function";
+    name: string;
+};
+export interface ClientToolContext {
+    route: NormalizedRoute;
+    request: NormalizedGenerateRequest;
+    runtime: RuntimeEnvironment;
+    toolCall: ToolCallInput;
+    messages: MessageInput[];
+    workingDirectory?: string;
+}
+export type ClientToolExecutionResult = string | {
+    content?: string;
+    data?: unknown;
+    isError?: boolean;
+};
+export interface ClientToolDefinition extends GenerateToolDefinition {
+    execute: (args: Record<string, unknown>, context: ClientToolContext) => ClientToolExecutionResult | Promise<ClientToolExecutionResult>;
+}
+export type ClientToolSelection = string | ClientToolDefinition;
+export type GenerateResponseFormat = {
+    type: "text";
+} | {
+    type: "json_object";
+} | {
+    type: "json_schema";
+    name?: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+} | {
+    type: "native";
+    value: unknown;
+};
+export interface SafetySetting {
+    category: string;
+    threshold: string;
+}
+export interface GenerateThinkingOptions {
+    mode?: ThinkingMode;
+    enabled?: boolean;
+    budgetTokens?: number;
+    effort?: ThinkingEffort;
+    includeThoughts?: boolean;
+}
+export interface GenerateParameters {
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    stop?: string | string[];
+    seed?: number;
+    candidateCount?: number;
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    responseFormat?: GenerateResponseFormat;
+    tools?: GenerateToolDefinition[];
+    toolChoice?: GenerateToolChoice;
+    parallelToolCalls?: boolean;
+    thinking?: GenerateThinkingOptions;
+    safetySettings?: SafetySetting[];
+    metadata?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
+    providerOptions?: Partial<Record<ProviderId, Record<string, unknown>>>;
+}
+export interface RouteHints {
+    pool?: string[];
+    excludeRouteIds?: string[];
+    preferredProviders?: string[];
+    requiredCapabilities?: Partial<RouteCapabilities>;
+    strategy?: RoutingStrategy;
+    /**
+     * Request-level model override (CD-8 — the SINGLE request-level model knob; there is NO
+     * `GenerateRequest.model`). On a `strict` route an undeclared model is DROPPED (never billed,
+     * INV-ROUTE-1); on a `shortlist` route it is passed through verbatim on a synthetic route copy
+     * that PRESERVES the original `route.id` (R12 — never fragments health/cursors).
+     */
+    model?: string;
+}
+/**
+ * Client-side fan-out throttle (C9 / UR-013). All fields OPTIONAL — an unset field is unbounded
+ * (normalized to {@link Number.POSITIVE_INFINITY}). `maxConcurrency` caps simultaneous in-flight
+ * calls (semaphore + FIFO fairness); `requestsPerSecond` is a `runtime.now()`-driven token bucket
+ * (deterministic, never wall-clock); `maxCalls` is a hard LIFETIME ceiling — exhausting it throws
+ * {@link AiConnectErrorCode} `fanout_limit` BEFORE route selection (INV-FANOUT-1 / R16), so it never
+ * pollutes route health.
+ */
+export interface FanoutPolicy {
+    maxConcurrency?: number;
+    requestsPerSecond?: number;
+    maxCalls?: number;
+}
+/** Normalized {@link FanoutPolicy} — every field resolved; `POSITIVE_INFINITY` means unbounded. */
+export interface NormalizedFanoutPolicy {
+    maxConcurrency: number;
+    requestsPerSecond: number;
+    maxCalls: number;
+}
+/** A live fan-out limiter instance (created by `createFanoutLimiter`). */
+export interface FanoutLimiter {
+    /**
+     * Acquire one slot, honoring concurrency + rate + the lifetime `maxCalls` ceiling. Resolves to a
+     * release function (call it exactly once, in a `finally`). Rejects with `fanout_limit` when the
+     * lifetime ceiling is exhausted. An optional `signal` rejects a queued waiter on abort.
+     */
+    acquire(signal?: AbortSignal): Promise<() => void>;
+    /** Point-in-time counters (for diagnostics / DST assertions). */
+    stats(): {
+        inFlight: number;
+        queued: number;
+        callsStarted: number;
+        maxConcurrency: number;
+        requestsPerSecond: number;
+        maxCalls: number;
+    };
+}
+/**
+ * Neutral query passed to a {@link ModelSelector} hook (C9 / UR-014). Carries the prompt surface and
+ * routing intent but NO secrets — the hook is consumer-supplied and may be LLM-backed (bs-search).
+ */
+export interface ModelSelectorInput {
+    text: string;
+    messages: MessageInput[];
+    operation: OperationKind;
+    routeHints?: RouteHints;
+}
+/**
+ * One eligible candidate offered to a {@link ModelSelector} (C9). Secret-free: `routeId` identifies
+ * the route without exposing credentials/baseUrl. Built by the router's `candidateModels()` projector.
+ * `capabilities` is the client-safe {@link PublicRouteCapabilities} subset (INV-PROJ-1) — internal
+ * routing flags (localOnly, requiresFilesystem, the requires-/rotation flags) are NEVER exposed here.
+ */
+export interface CandidateModel {
+    model: string;
+    provider: ProviderId;
+    routeId: string;
+    transportKind: TransportKind;
+    capabilities: PublicRouteCapabilities;
+}
+/**
+ * Consumer-supplied pre-routing model-selection hook (C9 / UR-014 / OQ-11). Receives the neutral
+ * {@link ModelSelectorInput} and the eligible {@link CandidateModel}s; returns a chosen model id (or
+ * `undefined` to defer to normal routing). An explicit `routeHints.model` always BEATS this hook
+ * (the hook is not even invoked). A thrown/rejected selector FAILS CLOSED to `validation_error` by
+ * default (opt `failOpen` ignores it and falls through to normal routing).
+ */
+export type ModelSelector = (question: ModelSelectorInput, candidateModels: CandidateModel[]) => string | undefined | Promise<string | undefined>;
+export interface GenerateImageOptions {
+    size?: ImageSizePreset | string;
+    rawPrompt?: boolean;
+    aspectRatio?: string;
+    quality?: string;
+    imageSize?: string;
+    style?: string;
+    sourceImage?: PortableFileInput;
+    mask?: PortableFileInput;
+    referenceImages?: PortableFileInput[];
+}
+export interface GenerateRequest {
+    operation?: OperationKind;
+    messages: MessageInput[];
+    attachments?: PortableFileInput[];
+    clientTools?: ClientToolSelection[];
+    parameters?: GenerateParameters;
+    routeHints?: RouteHints;
+    logContext?: Record<string, unknown>;
+    workingDirectory?: string;
+    image?: GenerateImageOptions;
+    /**
+     * Per-request fan-out throttle (C9). Merged per-field OVER the client-level default
+     * (`CreateClientOptions.fanout`). The per-request limiter is a request-SCOPED instance — it never
+     * mutates the shared client limiter (R15 / per-request-fanout-overrides-without-leaking).
+     */
+    fanout?: FanoutPolicy;
+}
+export interface NormalizedGenerateImageOptions extends Omit<GenerateImageOptions, "sourceImage" | "mask" | "referenceImages"> {
+    sourceImage?: PortableFile;
+    mask?: PortableFile;
+    referenceImages?: PortableFile[];
+}
+export interface NormalizedGenerateRequest extends Omit<GenerateRequest, "operation" | "attachments" | "image"> {
+    operation: OperationKind;
+    attachments: PortableFile[];
+    clientTools?: ClientToolDefinition[];
+    image?: NormalizedGenerateImageOptions;
+}
+export interface UsageModelBreakdown {
+    modelId: string;
+    name?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    reasoningTokens?: number;
+    cachedReadTokens?: number;
+}
+export interface UsageCostInfo {
+    amount: number;
+    currency?: string;
+}
+export interface UsageInfo {
+    inputTokens?: number;
+    outputTokens?: number;
+    reasoningTokens?: number;
+    totalTokens?: number;
+    cachedReadTokens?: number;
+    contextWindowUsed?: number;
+    contextWindowSize?: number;
+    durationMs?: number;
+    /**
+     * Count of successful usage-bearing model calls. Seeded as +1 per reporting
+     * call (only when usage is actually reported) and SUMMED by usage merges.
+     */
+    calls?: number;
+    cost?: UsageCostInfo;
+    modelUsage?: UsageModelBreakdown[];
+}
+export interface RouteAttempt {
+    routeId: string;
+    handlerKey: string;
+    errorCode: AiConnectErrorCode;
+    message: string;
+}
+export interface GenerateResult {
+    route: NormalizedRoute;
+    text?: string;
+    data?: unknown;
+    attachments: PortableFile[];
+    toolCalls?: ToolCallInput[];
+    usage?: UsageInfo;
+    warnings: string[];
+    attempts: RouteAttempt[];
+}
+/**
+ * Stream event union (CD-2). `delta` carries an incremental token (SSE/ACP producers, C9);
+ * `result` is the terminal success; `paused` is the terminal pause that KEEPS the accumulated
+ * partial. `delta` and `result` may interleave; `paused` and `result` are mutually-exclusive
+ * terminals. Abort, by contrast, THROWS and discards partials (it never yields `paused`).
+ */
+export type GenerateStreamEvent = {
+    type: "delta";
+    text: string;
+} | {
+    type: "result";
+    result: GenerateResult;
+} | {
+    type: "paused";
+    result: GenerateResult;
+};
+/**
+ * Caller-supplied cancellation/timeout options (CD-3, CD-6). `signal` aborts (partials
+ * discarded → `AiConnectError('aborted')`). `pauseSignal` is a SEPARATE signal: in `stream()`
+ * it stops reading and yields a terminal `{type:'paused'}` keeping partials; in `generate()`
+ * a mid-call pause degenerates to `'aborted'` (a non-streamed call cannot retain a partial).
+ * `timeoutMs` overrides the per-op tier default; `<=0`/`Infinity` disables the timer.
+ */
+export interface GenerateCallOptions {
+    signal?: AbortSignal;
+    pauseSignal?: AbortSignal;
+    timeoutMs?: number;
+}
+/** Per-operation timeout tier defaults (CD-6). */
+export interface OperationTimeoutDefaults {
+    /** generate / stream — default 120_000. */
+    generateMs?: number;
+    /** verify / discover* / checkHealth / probeModels — default 12_000. */
+    probeMs?: number;
+}
+/**
+ * The derived cancellation context threaded to handlers (CD-3, CD-4). `signal` is the MERGED
+ * signal (caller-signal ⊕ op-timeout) — handlers forward THIS into fetch/child-kill, never the
+ * raw caller signal. `pauseSignal` is passed through untouched. `reason` is set exactly once
+ * (first-writer-wins) so the client maps the thrown code deterministically.
+ */
+export interface AbortContext {
+    signal: AbortSignal;
+    pauseSignal?: AbortSignal;
+    reason?: AbortReason;
+}
+export interface VerificationIssue {
+    code: "runtime_mismatch" | "missing_env" | "missing_command" | "missing_session" | "handler_issue";
+    message: string;
+}
+export interface VerificationRouteReport {
+    routeId: string;
+    ok: boolean;
+    issues: VerificationIssue[];
+}
+export interface VerificationReport {
+    ok: boolean;
+    routes: VerificationRouteReport[];
+}
+/**
+ * Per-token / per-request pricing for a model (C4). All components OPTIONAL; a missing
+ * component is unknown (NOT zero). `parseModelPricing` populates this from a raw provider
+ * record; `detectModelFree` treats all-defined-components-=== 0 as free.
+ */
+export interface ModelPricing {
+    prompt?: number;
+    completion?: number;
+    request?: number;
+    image?: number;
+    currency?: string;
+}
+export interface AcpModelInfo {
+    modelId: string;
+    name: string;
+    description?: string;
+    canonicalModelId?: string;
+    /** Discovered context-window length (tokens). Populated from the raw model record (C4). */
+    contextLength?: number;
+    /** Whether the model is free (`:free` suffix or all-defined-pricing-components === 0) (C4). */
+    free?: boolean;
+    /** Parsed pricing block, when the provider record advertised one (C4). */
+    pricing?: ModelPricing;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A curated reference-table row keyed by a normalized model key (C4). `contextLength` is the
+ * known context window; `free`/`pricing` are optional curated facts. See `MODEL_REFERENCE`.
+ */
+export interface ModelReferenceEntry {
+    key: string;
+    contextLength: number;
+    free?: boolean;
+    pricing?: ModelPricing;
+}
+/**
+ * The resolved context window + the source it came from (C4 / INV-CTX-1). `source` records
+ * precedence: `discovered` (live) > `reference` (curated table) > `configured` (per-model
+ * config) > `default` (flat 8192). `cached` is `true` when the value was served from the
+ * client's per-(baseUrl|transportId)::model cache.
+ */
+export interface ModelContextResolution {
+    contextWindow: number;
+    source: "discovered" | "reference" | "configured" | "default";
+    model: string;
+    cached: boolean;
+}
+/**
+ * Input accepted by `AiConnectClient.resolveModelContext` (C4). Either a bare model id, or a
+ * provider+model pair with an optional `baseUrl`/`transportId` that scopes the cache key.
+ */
+export type ResolveModelContextInput = string | {
+    provider: ProviderId;
+    model: string;
+    baseUrl?: string;
+    transportId?: string;
+};
+/** A configured model entry — either a bare id or an id with a per-model context window (C4). */
+export interface ModelConfigInput {
+    id: string;
+    contextWindow?: number;
+}
+/** A model declaration in account config: a bare id string OR a `{ id, contextWindow }` (C4). */
+export type ModelInput = string | ModelConfigInput;
+/** A normalized model declaration after `normalizeModelInput` (C4). */
+export interface NormalizedModelConfig {
+    id: string;
+    contextWindow?: number;
+}
+/**
+ * Options for `AiConnectClient.resolveModelContext` (C4). `discovered` is the value learned
+ * from a live model-discovery response (highest precedence); `configured` is a per-model/route
+ * override; `defaultContextWindow` overrides the flat 8192 floor. On a cache HIT `discovered`
+ * is IGNORED (the cached value+source win — OQ-4 #25).
+ */
+export interface ResolveModelContextOptions {
+    discovered?: number;
+    configured?: number;
+    defaultContextWindow?: number;
+}
+export interface AcpModelCatalog {
+    requestedModelId?: string;
+    requestedModelAdvertised?: boolean;
+    canonicalModelId?: string;
+    resolvedModelId?: string;
+    currentModelId?: string;
+    availableModels: AcpModelInfo[];
+}
+export interface AcpModelDiscoveryError {
+    code: AiConnectErrorCode | "not_supported";
+    message: string;
+}
+export interface AcpModelDiscoveryRouteReport {
+    routeId: string;
+    provider: ProviderId;
+    handlerKey: string;
+    transportKind: TransportKind;
+    transportId: string;
+    ok: boolean;
+    requestedModelId?: string;
+    requestedModelAdvertised?: boolean;
+    canonicalModelId?: string;
+    resolvedModelId?: string;
+    currentModelId?: string;
+    availableModels: AcpModelInfo[];
+    error?: AcpModelDiscoveryError;
+}
+export interface AcpModelDiscoveryReport {
+    ok: boolean;
+    routes: AcpModelDiscoveryRouteReport[];
+}
+export interface RuntimeEnvironment {
+    kind: RuntimeKind;
+    now?: () => number;
+    getEnv?: (name: string) => string | undefined;
+    hasCommand?: (command: string) => boolean | Promise<boolean>;
+    /**
+     * Schedule a one-shot timer; returns a cancel function. Default (when omitted) is real
+     * `setTimeout` + `unref()`. Seeded DST runtimes inject a fake-clock-driven timer so abort/
+     * timeout behaviour is deterministically replayable (D6). Consumed by `deriveAbort` (C2b)
+     * and the model probe (C8) — never read wall-clock directly on an observable path.
+     */
+    setTimer?: (ms: number, cb: () => void) => () => void;
+}
+export interface WideEventRouteSummary {
+    id: string;
+    provider: ProviderId;
+    transportKind: TransportKind;
+    transportId: string;
+    runtime: RouteRuntime;
+    accountId: string;
+    credentialId: string;
+    model: string;
+    handlerKey: string;
+    profileId: string;
+    baseUrl?: string;
+}
+export interface WideEventRequestSummary {
+    messageCount: number;
+    messageRoles: MessageRole[];
+    inputChars: number;
+    attachmentCount: number;
+    attachmentKinds: PortableFileKind[];
+    attachmentNames: string[];
+    candidateRouteIds: string[];
+    clientToolCount?: number;
+    clientToolNames?: string[];
+    routeHints?: RouteHints;
+    workingDirectory?: string;
+    imageSize?: string;
+    imageAspectRatio?: string;
+    imageQuality?: string;
+    imageOutputSize?: string;
+    imageStyle?: string;
+    rawImagePrompt?: boolean;
+    imageReferenceCount?: number;
+    imageHasSourceImage?: boolean;
+    imageHasMask?: boolean;
+    parameters?: WideEventParameterSummary;
+}
+export interface WideEventVerificationRouteSummary {
+    routeId: string;
+    ok: boolean;
+    issueCodes: VerificationIssue["code"][];
+}
+export interface WideEventVerificationSummary {
+    requestedRouteIds?: string[];
+    routesChecked: number;
+    routesPassed: number;
+    routesFailed: number;
+    issueCount: number;
+    issueCodes: VerificationIssue["code"][];
+    routeReports: WideEventVerificationRouteSummary[];
+}
+export interface WideEventAcpModelDiscoveryRouteSummary {
+    routeId: string;
+    provider: ProviderId;
+    ok: boolean;
+    transportKind: TransportKind;
+    transportId: string;
+    requestedModelId?: string;
+    requestedModelAdvertised?: boolean;
+    canonicalModelId?: string;
+    resolvedModelId?: string;
+    currentModelId?: string;
+    availableModelCount: number;
+    availableModelIds: string[];
+    errorCode?: AiConnectErrorCode | "not_supported";
+    message?: string;
+}
+export interface WideEventAcpModelDiscoverySummary {
+    requestedRouteIds?: string[];
+    routesChecked: number;
+    routesPassed: number;
+    routesFailed: number;
+    routeReports: WideEventAcpModelDiscoveryRouteSummary[];
+}
+export interface WideEventHealthRouteSummary {
+    routeId: string;
+    provider: ProviderId;
+    transportKind: TransportKind;
+    ok: boolean;
+    endpointOk: boolean;
+    modelOk: boolean;
+    endpointCode?: AiConnectErrorCode | "not_supported";
+    modelCode?: AiConnectErrorCode | "not_supported";
+    modelLatencyMs?: number;
+}
+export interface WideEventHealthSummary {
+    requestedRouteIds?: string[];
+    reachabilityOnly: boolean;
+    routesChecked: number;
+    routesPassed: number;
+    routesFailed: number;
+    routeReports: WideEventHealthRouteSummary[];
+}
+export interface WideEventProbeRouteSummary {
+    routeId: string;
+    modelId: string;
+    ok: boolean;
+    broken: boolean;
+    cached: boolean;
+    code?: AiConnectErrorCode | "not_supported";
+    httpStatus?: number;
+    latencyMs?: number;
+}
+export interface WideEventProbeSummary {
+    requestedRouteIds?: string[];
+    probesIssued: number;
+    probesOk: number;
+    probesBroken: number;
+    probesCached: number;
+    routeReports: WideEventProbeRouteSummary[];
+}
+export interface WideEventAttempt {
+    index: number;
+    route: WideEventRouteSummary;
+    durationMs: number;
+    outcome: "success" | "error";
+    retryCount: number;
+    errorCode?: AiConnectErrorCode;
+    message?: string;
+    fallbackActions?: FallbackAction[];
+    transport?: WideEventTransportSummary;
+}
+export interface WideEventParameterSummary {
+    keys: string[];
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    stopCount?: number;
+    seed?: number;
+    candidateCount?: number;
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    responseFormatType?: string;
+    toolCount?: number;
+    toolChoice?: string;
+    parallelToolCalls?: boolean;
+    thinkingMode?: ThinkingMode;
+    thinkingBudgetTokens?: number;
+    thinkingEffort?: ThinkingEffort;
+    includeThoughts?: boolean;
+    safetySettingsCount?: number;
+    metadataKeys?: string[];
+    extraKeys?: string[];
+    providerOptionKeys?: Record<string, string[]>;
+}
+export interface WideEventTransportPhase {
+    name: string;
+    durationMs: number;
+}
+export interface WideEventTransportSummary {
+    protocol: string;
+    endpoint: string;
+    method: string;
+    stream: boolean;
+    bodyKeys: string[];
+    parameterKeys: string[];
+    parameters?: WideEventParameterSummary;
+    phases?: WideEventTransportPhase[];
+    cache?: {
+        enabled: boolean;
+        hit: boolean;
+    };
+}
+export interface WideEventResultSummary {
+    warningsCount: number;
+    warnings: string[];
+    attachmentCount: number;
+    attachmentKinds: PortableFileKind[];
+    attachmentNames: string[];
+    outputTextChars?: number;
+    toolCallCount?: number;
+    usage?: UsageInfo;
+}
+export interface WideEventErrorInfo {
+    code: AiConnectErrorCode | "unknown";
+    message: string;
+    routeId?: string;
+}
+export interface WideEvent {
+    timestamp: string;
+    event: "ai_connect.operation";
+    requestId: string;
+    service: string;
+    library: "ai-connect";
+    operationName: ClientOperationName;
+    operation: OperationKind | "verify" | "discover_models" | "check_health" | "probe_models";
+    runtime: RuntimeKind;
+    outcome: "success" | "error";
+    durationMs: number;
+    candidates: WideEventRouteSummary[];
+    attempts: WideEventAttempt[];
+    selectedRoute?: WideEventRouteSummary;
+    request?: WideEventRequestSummary;
+    result?: WideEventResultSummary;
+    verification?: WideEventVerificationSummary;
+    modelDiscovery?: WideEventAcpModelDiscoverySummary;
+    acpModelDiscovery?: WideEventAcpModelDiscoverySummary;
+    /** Live health-check summary (C8 / CD-9), present for `checkHealth`. */
+    health?: WideEventHealthSummary;
+    /** Model-probe summary (C8 / CD-9), present for `probeModels`/`probeModelsStream`. */
+    probe?: WideEventProbeSummary;
+    error?: WideEventErrorInfo;
+    context?: Record<string, unknown>;
+    version?: string;
+    deploymentId?: string;
+    region?: string;
+}
+export type WideEventLogger = (event: WideEvent) => void | Promise<void>;
+export interface WideEventSamplingOptions {
+    sampleRate?: number;
+    slowOperationMs?: number;
+    keepErrors?: boolean;
+    keepWarnings?: boolean;
+    keepOperations?: ClientOperationName[];
+    keepRoutes?: string[];
+    keepProviders?: string[];
+    predicate?: (event: WideEvent) => boolean | Promise<boolean>;
+}
+export interface LoggingOptions {
+    logger?: WideEventLogger;
+    sampling?: WideEventSamplingOptions;
+    service?: string;
+    version?: string;
+    deploymentId?: string;
+    region?: string;
+    baseContext?: Record<string, unknown>;
+}
+export interface NormalizedCredentialConfig {
+    id: string;
+    apiKey?: string;
+    apiKeyEnv?: string;
+    apiKeyDelimiter?: string;
+    source: string;
+    weight: number;
+    metadata: Record<string, string>;
+}
+export interface TransportDescriptor {
+    kind: TransportKind;
+    id: string;
+    command?: string;
+    baseUrl?: string;
+    cli?: CliTransportOptions;
+    auth?: {
+        methodId: string;
+        params: Record<string, unknown>;
+    };
+    launch?: AcpLaunchOptions;
+}
+export interface VerificationConfig {
+    env: string[];
+    command?: string;
+    session?: string;
+}
+export interface NormalizedAccountConfig {
+    id: string;
+    profile: string;
+    runtime: RouteRuntime;
+    transport: TransportDescriptor;
+    models: string[];
+    credentials: NormalizedCredentialConfig[];
+    capabilities: RouteCapabilities;
+    verify: VerificationConfig;
+    weight: number;
+    priority: number;
+    enabled: boolean;
+}
+export interface NormalizedProviderConfig {
+    id: string;
+    accounts: NormalizedAccountConfig[];
+}
+export interface NormalizedRoute {
+    id: string;
+    provider: ProviderId;
+    transport: TransportDescriptor;
+    profileId: string;
+    accountId: string;
+    credentialId: string;
+    model: string;
+    runtime: RouteRuntime;
+    weight: number;
+    priority: number;
+    handlerKey: string;
+    capabilities: RouteCapabilities;
+    verify: VerificationConfig;
+    credential: NormalizedCredentialConfig;
+    /** Configured context window for this route's model (C4 owns ONLY this field). */
+    contextWindow?: number;
+    /** Model-allowlist enforcement mode (C7; default `strict`). */
+    modelAllowlistMode: ModelAllowlistMode;
+    /**
+     * Models advertised by this route. In `strict` mode an undeclared `routeHints.model` drops the
+     * route; in `shortlist` mode it is advisory (verbatim passthrough). Seeded from the route's own
+     * `model` (C7); C9 may extend this from discovery.
+     */
+    advertisedModels: string[];
+    /** Per-route default response format (C7); injected when the caller omits one. */
+    defaultResponseFormat?: GenerateResponseFormat;
+    /** Per-route system prompt (C7); injected as a leading system message when the caller omits one. */
+    systemPrompt?: string;
+    /** Human-friendly label for projection/diagnostics (C7); falls back to `id` in `PublicRoute`. */
+    label?: string;
+    /** Execution-context mode (C7; default `workspace`). */
+    contextMode: ContextMode;
+}
+export interface NormalizedOperationRouting {
+    strategy: RoutingStrategy;
+    pool: string[];
+}
+export interface NormalizedFallbackPolicy {
+    on: Record<AiConnectErrorCode, FallbackAction[]>;
+    cooldownMs: Record<AiConnectErrorCode, number>;
+}
+export interface NormalizedRetryPolicy {
+    maxAttempts: Record<AiConnectErrorCode, number>;
+    delayMs: Record<AiConnectErrorCode, number>;
+}
+export interface NormalizedRoutingConfig {
+    strategy: RoutingStrategy;
+    operations: Record<OperationKind, NormalizedOperationRouting>;
+    fallback: NormalizedFallbackPolicy;
+    retry: NormalizedRetryPolicy;
+    shuffleOnInit: boolean;
+    /** Selector-resolution policy (C7); default `{ unknownSelector: "error" }`. */
+    resolution: NormalizedRouteResolutionConfig;
+}
+export interface AiConnectConfig {
+    providers: Record<string, NormalizedProviderConfig>;
+    routes: NormalizedRoute[];
+    routing: NormalizedRoutingConfig;
+}
+export interface RouteHealthSnapshot {
+    state: RouteHealthState;
+    failureCount: number;
+    cooldownUntil?: number;
+}
+export interface ListedRoute extends NormalizedRoute {
+    health: RouteHealthSnapshot;
+}
+/**
+ * Secret-free subset of {@link RouteCapabilities} safe to expose to untrusted callers (C7 /
+ * INV-PROJ-1). An EXPLICIT `Pick` — never derived by spreading a route — so a future capability
+ * flag cannot silently leak into a public projection.
+ */
+export type PublicRouteCapabilities = Pick<RouteCapabilities, "browserSafe" | "supportsStreaming" | "supportsToolSchema" | "supportsToolExecution" | "supportsClientToolExecution" | "supportsFileUpload" | "supportsFileOutput" | "supportsImageInput" | "supportsImageOutput">;
+/**
+ * Client-safe projection of a route (C7 / INV-PROJ-1). Built via EXPLICIT construction in
+ * `toPublicRoute` — NEVER by spreading a {@link NormalizedRoute} (which carries
+ * `credential`/`baseUrl`/`apiKeyEnv`/`accountId`/`handlerKey`). Contains NO secret-bearing field;
+ * `JSON.stringify(publicRoute)` must contain no configured-secret substring.
+ */
+export interface PublicRoute {
+    id: string;
+    label: string;
+    provider: ProviderId;
+    transportKind: TransportKind;
+    models: string[];
+    defaultModel: string;
+    contextWindow?: number;
+    modelAllowlistMode: ModelAllowlistMode;
+    defaultResponseFormat?: GenerateResponseFormat;
+    systemPrompt?: string;
+    capabilities: PublicRouteCapabilities;
+    health: RouteHealthState;
+}
+export interface VerificationContext {
+    route: NormalizedRoute;
+    runtime: RuntimeEnvironment;
+}
+export interface DiscoverAcpModelsContext {
+    route: NormalizedRoute;
+    runtime: RuntimeEnvironment;
+    /** Merged probe-tier cancellation signal (CD-3). C2a sole owner; consumers only read it. */
+    abort: AbortContext;
+    telemetry?: {
+        captureTransport: (summary: WideEventTransportSummary) => void;
+    };
+}
+export interface GenerateContext {
+    route: NormalizedRoute;
+    request: NormalizedGenerateRequest;
+    runtime: RuntimeEnvironment;
+    attempt: number;
+    /** Merged cancellation signal (CD-3). Handlers forward `abort.signal` into fetch/child-kill. */
+    abort: AbortContext;
+    telemetry?: {
+        captureTransport: (summary: WideEventTransportSummary) => void;
+    };
+}
+export interface RouteHandlerGenerateResult {
+    text?: string;
+    data?: unknown;
+    attachments?: PortableFileInput[];
+    toolCalls?: ToolCallInput[];
+    usage?: UsageInfo;
+    warnings?: string[];
+}
+export interface RouteHandler {
+    generate?: (context: GenerateContext) => Promise<RouteHandlerGenerateResult>;
+    stream?: (context: GenerateContext) => AsyncIterable<GenerateStreamEvent>;
+    verify?: (context: VerificationContext) => Promise<VerificationIssue[]> | VerificationIssue[];
+    discoverModels?: (context: DiscoverAcpModelsContext) => Promise<AcpModelCatalog>;
+}
+export type RouteHandlerRegistry = Record<string, RouteHandler>;
+export interface AcpSessionCacheOptions {
+    enabled?: boolean;
+    idleTtlMs?: number;
+}
+export interface AcpClientOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    commands?: Record<string, string>;
+    launch?: AcpLaunchOptionsInput;
+    permissionMode?: AcpPermissionMode;
+    timeoutMs?: number;
+    sessionCache?: boolean | AcpSessionCacheOptions;
+    maxConcurrentConnections?: number;
+}
+export interface CliClientOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    commands?: Record<string, string>;
+    timeoutMs?: number;
+}
+export interface ServerClientOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    commands?: Record<string, string>;
+    timeoutMs?: number;
+    startupTimeoutMs?: number;
+    fetch?: FetchLike;
+}
+export interface CreateClientOptions {
+    runtime?: RuntimeEnvironment;
+    handlers?: RouteHandlerRegistry;
+    clientTools?: ClientToolDefinition[];
+    fetch?: FetchLike;
+    acp?: AcpClientOptions;
+    cli?: CliClientOptions;
+    server?: ServerClientOptions;
+    logging?: LoggingOptions;
+    dispose?: () => Promise<void>;
+    /** Per-operation timeout tier defaults (CD-6); merged into the derived abort signal. */
+    timeouts?: OperationTimeoutDefaults;
+    /**
+     * Client-level fan-out throttle default (C9 / UR-013). A per-request `GenerateRequest.fanout`
+     * merges per-field OVER this. Unset ⇒ unbounded.
+     */
+    fanout?: FanoutPolicy;
+    /**
+     * Client-scoped routing hooks (C9 / UR-014). `modelSelector` is a consumer-supplied pre-routing
+     * model picker (OQ-11); `failOpen` (default `false`) flips a throwing selector from the
+     * fail-closed `validation_error` default to silently falling through to normal routing.
+     */
+    routeHints?: {
+        modelSelector?: ModelSelector;
+        failOpen?: boolean;
+    };
+}
+export interface VerifyTarget {
+    routes?: string[];
+    logContext?: Record<string, unknown>;
+}
+export interface DiscoverAcpModelsTarget {
+    routes?: string[];
+    logContext?: Record<string, unknown>;
+}
+export interface DiscoverModelsTarget {
+    routes?: string[];
+    transports?: TransportKind[];
+    logContext?: Record<string, unknown>;
+}
+export type ModelInfo = AcpModelInfo;
+export type ModelCatalog = AcpModelCatalog;
+export type ModelDiscoveryError = AcpModelDiscoveryError;
+export type ModelDiscoveryRouteReport = AcpModelDiscoveryRouteReport;
+export type ModelDiscoveryReport = AcpModelDiscoveryReport;
+/**
+ * Outcome of one health-check stage. `ok` is the stage verdict; `detail` is a human-readable
+ * note (e.g. `'skipped: endpoint unreachable'` when Stage-1 short-circuited Stage-2). `httpStatus`
+ * carries the raw status (via {@link AiConnectError} `details.httpStatus`, CD-7) when known.
+ */
+export interface HealthStageResult {
+    ok: boolean;
+    detail: string;
+    code?: AiConnectErrorCode | "not_supported";
+    httpStatus?: number;
+}
+/** A model-ping stage result; `latencyMs` is the measured ping round-trip (fake-clock derived). */
+export interface HealthModelStageResult extends HealthStageResult {
+    latencyMs?: number;
+}
+export interface RouteHealthReport {
+    routeId: string;
+    provider: ProviderId;
+    handlerKey: string;
+    transportKind: TransportKind;
+    transportId: string;
+    modelId: string;
+    ok: boolean;
+    endpoint: HealthStageResult;
+    model: HealthModelStageResult;
+}
+export interface HealthReport {
+    ok: boolean;
+    routes: RouteHealthReport[];
+}
+export interface CheckHealthTarget {
+    routes?: string[];
+    transports?: TransportKind[];
+    /** Run Stage-1 (reachability) only; skip the Stage-2 chat ping. Cheap default for hot paths. */
+    reachabilityOnly?: boolean;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    logContext?: Record<string, unknown>;
+}
+/**
+ * Result of probing one route::model tuple (UR-008). `broken` is HTTP-status-driven for api
+ * transports (INV-PROBE-1: `400 ≤ httpStatus < 500 ∧ httpStatus ≠ 429`); everything else
+ * (429 / 5xx / status-less transport errors) is transient (`broken:false`). `cached:true`
+ * marks a TTL-cache hit (no live ping issued).
+ */
+export interface ProbeModelResult {
+    routeId: string;
+    modelId: string;
+    ok: boolean;
+    broken: boolean;
+    detail: string;
+    latencyMs?: number;
+    code?: AiConnectErrorCode | "not_supported";
+    httpStatus?: number;
+    cached?: boolean;
+}
+export interface ProbeModelsTarget {
+    routes?: string[];
+    transports?: TransportKind[];
+    models?: string[];
+    logContext?: Record<string, unknown>;
+}
+export interface ProbeModelsOptions {
+    signal?: AbortSignal;
+    /** Bounded fan-out concurrency (default {@link PROBE_DEFAULT_CONCURRENCY} = 4). */
+    concurrency?: number;
+    /** Per-probe timeout in ms (default {@link PROBE_DEFAULT_TIMEOUT_MS} = 8000). */
+    timeoutMs?: number;
+    /** TTL for the per-(route::sorted-models) cache (default {@link PROBE_DEFAULT_TTL_MS} = 300000). */
+    cacheTtlMs?: number;
+    /** Ignore any cached entry and re-probe (still rewrites the cache). */
+    forceRefresh?: boolean;
+    logContext?: Record<string, unknown>;
+}
+export interface AiConnectClient {
+    readonly config: AiConnectConfig;
+    readonly runtime: RuntimeEnvironment;
+    listRoutes(filter?: {
+        operation?: OperationKind;
+    }): ListedRoute[];
+    /**
+     * Secret-free projection of routes (C7 / INV-PROJ-1) for untrusted surfaces (UI/agent
+     * discovery). Returns {@link PublicRoute}s built by explicit construction — never carries
+     * credentials/baseUrl/handler keys. Stable under route-health changes except the `health`
+     * field itself.
+     */
+    listPublicRoutes(filter?: {
+        operation?: OperationKind;
+        provider?: ProviderId;
+    }): PublicRoute[];
+    /**
+     * Project the currently-eligible routes into secret-free {@link CandidateModel}s (C9 / UR-014) —
+     * the same list offered to a {@link ModelSelector}. Reuses the router's `candidateModels()`
+     * projector + the runtime/health filters.
+     */
+    listCandidateModels(filter?: {
+        operation?: OperationKind;
+        provider?: ProviderId;
+    }): CandidateModel[];
+    prepareFile(input: PortableFileInput): PortableFile;
+    verify(target?: VerifyTarget, opts?: Pick<GenerateCallOptions, "signal" | "timeoutMs">): Promise<VerificationReport>;
+    discoverModels(target?: DiscoverModelsTarget, opts?: Pick<GenerateCallOptions, "signal" | "timeoutMs">): Promise<ModelDiscoveryReport>;
+    discoverAcpModels(target?: DiscoverAcpModelsTarget, opts?: Pick<GenerateCallOptions, "signal" | "timeoutMs">): Promise<AcpModelDiscoveryReport>;
+    generate(request: GenerateRequest, opts?: GenerateCallOptions): Promise<GenerateResult>;
+    stream(request: GenerateRequest, opts?: GenerateCallOptions): AsyncIterable<GenerateStreamEvent>;
+    /**
+     * Resolve the effective context window for a model (C4 / INV-CTX-1). Synchronous, no I/O.
+     * Precedence: discovered > reference (curated table) > configured > default(8192). Results
+     * are cached per-(baseUrl|transportId)::model; a cache hit returns the same value+source with
+     * `cached:true` and IGNORES `options.discovered`.
+     */
+    resolveModelContext(input: ResolveModelContextInput, options?: ResolveModelContextOptions): ModelContextResolution;
+    /**
+     * Live two-stage health-check (C8 / UR-008). Stage-1 probes endpoint reachability (api GET
+     * /models via `discoverModels`; acp/cli/server session via `verify`); Stage-2 issues a minimal
+     * bounded chat ping (max-1-token) capturing `latencyMs`. A Stage-1 failure short-circuits
+     * Stage-2 with detail `'skipped: endpoint unreachable'`. READ-ONLY re router health (INV-PROBE-1):
+     * never calls `recordFailure`/`recordSuccess`.
+     */
+    checkHealth(target?: CheckHealthTarget): Promise<HealthReport>;
+    /**
+     * Probe route::model tuples for broken-vs-transient classification (C8 / UR-008 / INV-PROBE-1)
+     * with a per-(route::sorted-models) TTL cache (default 5min), bounded concurrency (default 4),
+     * and a per-probe timeout (default 8s) scheduled via the derived-abort `runtime.setTimer` seam.
+     * Honors `opts.signal` mid-fan-out. READ-ONLY re router health.
+     */
+    probeModels(target?: ProbeModelsTarget, opts?: ProbeModelsOptions): Promise<ProbeModelResult[]>;
+    /** Streaming variant of {@link probeModels}: yields each {@link ProbeModelResult} as it settles. */
+    probeModelsStream(target?: ProbeModelsTarget, opts?: ProbeModelsOptions): AsyncIterable<ProbeModelResult>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map