@vostride/agent-qa-model 0.0.0-stage → 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,272 @@
+import { LanguageModelV3 } from '@ai-sdk/provider';
+import { ModelProfile, ModelCapabilities, ModelProviderId, MaskFn } from '@vostride/agent-qa-schema';
+export { ModelAuthDeclaration, ModelCapabilities, ModelProfile, ModelProviderId } from '@vostride/agent-qa-schema';
+import { ModelMessage, LanguageModelUsage, LanguageModelMiddleware } from 'ai';
+
+type ResolvedModelAuth = {
+    kind: 'api-key';
+    apiKey: string;
+} | {
+    kind: 'bearer-token';
+    token: string;
+} | {
+    kind: 'auth-fetch';
+    modelAdapter: 'openai-responses' | 'anthropic-messages';
+    fetch: typeof globalThis.fetch;
+} | {
+    kind: 'none';
+};
+interface Transport {
+    baseURL?: string;
+    headers?: Record<string, string>;
+    apiKey?: string;
+    authToken?: string;
+    fetch?: typeof globalThis.fetch;
+    providerOptions?: ModelProfile['providerOptions'];
+}
+declare function deriveTransport(profile: ModelProfile, auth: ResolvedModelAuth): Transport;
+
+declare function anthropicCompatible(transport: Transport, modelId: string): LanguageModelV3;
+declare function anthropicSubscription(transport: Transport, modelId: string): LanguageModelV3;
+
+type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue | undefined;
+};
+type ProviderOptions = Record<string, Record<string, JSONValue | undefined>> | undefined;
+interface ProviderOptionsConfig {
+    provider?: string;
+    modelAdapter?: 'openai-responses' | 'anthropic-messages';
+    fetch?: typeof globalThis.fetch;
+}
+declare function openaiCompatible(transport: Transport, modelId: string): LanguageModelV3;
+declare function openaiSubscription(transport: Transport, modelId: string): LanguageModelV3;
+declare function getProviderOptions(config: ProviderOptionsConfig): ProviderOptions;
+
+type AdapterBody = (transport: Transport, modelId: string) => LanguageModelV3;
+
+declare function gemini(transport: Transport, modelId: string): LanguageModelV3;
+
+type LogEntry = {
+    source: string;
+    level?: string;
+    message: string;
+};
+/**
+ * Compact a log-shaped burst into a deterministic, bounded string (D-13/D-15).
+ * Groups typed `{source, level, message}` entries by `source::level::normalized`,
+ * counts each class, and renders it with the first ≤5 raw samples seen (monotonic:
+ * once a class has 5 samples, growing the burst never changes which 5 are shown;
+ * the onset occurrence is always retained). Classes render in sorted-key order.
+ */
+declare function compactLogs(entries: LogEntry[]): string;
+/**
+ * Bound a single structured value for prompt inclusion (D-14). Safe-stringifies the
+ * value verbatim (variable tokens preserved — the planner may need them exactly) and,
+ * only if it exceeds `BLOB_CEILING`, slices and appends the visible truncation marker.
+ * `undefined` in ⇒ `undefined` out. Never throws on cyclic input (V5).
+ */
+declare function guardBlob(value: unknown): string | undefined;
+/**
+ * The composed pre-prompt guard for one tool-output value (CTXB-06): a burst of
+ * log-shaped entries (console `{level, text}` / network `{url, method, status}` /
+ * generic `{source?, level?, message}`) routes through {@link compactLogs};
+ * anything else through {@link guardBlob}. Compacted output is still bounded by
+ * the blob ceiling so a burst of all-distinct classes cannot flood the prompt.
+ */
+declare function guardToolOutput(value: unknown): string | undefined;
+
+declare function parseRealWindow(error: unknown): number | undefined;
+declare function isContextOverflow(error: unknown): boolean;
+
+/**
+ * Caller-supplied degrade controls (D-07/D-09). Policy-free: no default/safety margin is
+ * baked here — Phase 355 supplies the concrete budget and pin predicate.
+ *
+ * - `budget` — the token ceiling the degraded prompt must fit under.
+ * - `pin` — a caller pin predicate; a message matching it is never evicted or truncated.
+ *   The substrate stays tier-ignorant (355 pins its tiers explicitly).
+ * - `estimate` — the estimator the damage loop re-runs after each eviction. Optional so
+ *   `degrade` stays a standalone-testable pure function; the Plan-03 factory passes its own.
+ */
+interface DegradeOptions {
+    budget: number;
+    pin?: (message: ModelMessage, index: number) => boolean;
+    estimate?: (messages: ModelMessage[]) => number;
+}
+/**
+ * Discriminated degrade result (D-09). `ok:true` carries the fitted messages; `ok:false`
+ * is the structured cannot-fit outcome returned when system + final + pinned content alone
+ * exceeds the budget — degrade never throws and never violates a pin, returning the
+ * best-effort hygiene-reduced messages instead.
+ */
+type DegradeOutcome = {
+    ok: true;
+    messages: ModelMessage[];
+} | {
+    ok: false;
+    reason: 'pinned-content-exceeds-budget';
+    messages: ModelMessage[];
+};
+/**
+ * The instance shape returned by the Plan-03 factory and consumed through the runner's
+ * provider-neutral port (D-05). Prompt tokens only; the substrate is policy-free.
+ */
+interface TokenAccounting {
+    estimate(messages: ModelMessage[]): number;
+    recordUsage(usage: LanguageModelUsage, messages: ModelMessage[]): void;
+    getCeilings(): {
+        contextWindow: number;
+        maxOutput: number;
+    };
+    degrade(messages: ModelMessage[], options: DegradeOptions): DegradeOutcome;
+}
+/**
+ * Factory construction options (Plan 03).
+ *
+ * - `getCapabilities` — the D-04 lazy ceilings thunk (composes v46 `resolveCapabilities`),
+ *   read on every estimate/degrade so a mid-run overflow-learned window shrink applies next turn.
+ * - `perImageTokens` — the D-12 injectable flat per-image constant (test/chat-layer tuning).
+ */
+interface TokenAccountingOptions {
+    getCapabilities: () => ModelCapabilities;
+    perImageTokens?: number;
+}
+
+declare function createTokenAccounting(options: TokenAccountingOptions): TokenAccounting;
+
+interface FamilyEntry {
+    match: readonly string[];
+    caps: ModelCapabilities;
+}
+declare const UNKNOWN_FLOOR: ModelCapabilities;
+declare const FAMILIES: readonly FamilyEntry[];
+declare function matchFamily(model: string): ModelCapabilities | undefined;
+
+declare const overrideStore: Map<string, number>;
+declare function capabilityKey(provider: string, model: string): string;
+declare function getObservedWindow(key: string): number | undefined;
+
+declare function resolveCapabilities(profile: ModelProfile): ModelCapabilities;
+
+interface CatalogEntry {
+    id: string;
+    label: string;
+    vision: boolean;
+    notes?: string;
+}
+declare const MODEL_CATALOG: Record<ModelProviderId, CatalogEntry[]>;
+declare function getModelCatalog(): Record<ModelProviderId, CatalogEntry[]>;
+
+interface FetchLiveModelsOptions {
+    baseURL: string;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    ttlMs?: number;
+}
+declare function fetchLiveModels(opts: FetchLiveModelsOptions): Promise<CatalogEntry[]>;
+declare function mergeCatalog(staticEntries: CatalogEntry[], live: CatalogEntry[]): CatalogEntry[];
+
+declare const toolSchemaMiddleware: LanguageModelMiddleware;
+
+declare function capabilityUpdateMiddleware(profile: ModelProfile): LanguageModelMiddleware;
+
+interface DebugLoggingOptions {
+    /** Force enable/disable. When omitted, resolves from the `AGENT_QA_DEBUG_LLM` env flag. */
+    enabled?: boolean;
+    /** Line sink. Defaults to stderr. Injected by tests as a spy. */
+    sink?: (line: string) => void;
+}
+declare function debugLoggingMiddleware(options?: DebugLoggingOptions): LanguageModelMiddleware;
+
+declare function dropEmptyMessagesMiddleware(): LanguageModelMiddleware;
+
+declare function deriveExamplesMiddleware(): LanguageModelMiddleware;
+
+declare function extractJsonStrategy(text: string): string;
+
+declare function repairMiddleware(): LanguageModelMiddleware;
+
+interface RetryMiddlewareOptions {
+    maxRetries?: number;
+    initialDelayInMs?: number;
+    backoffFactor?: number;
+}
+declare function retryMiddleware({ maxRetries, initialDelayInMs, backoffFactor, }?: RetryMiddlewareOptions): LanguageModelMiddleware;
+
+declare function stripUnsupportedParamsMiddleware(params: readonly string[]): LanguageModelMiddleware;
+
+type ProviderAuthMode = 'api-key' | 'bearer-token' | 'subscription' | 'none';
+interface ProviderDescriptor {
+    id: string;
+    label: string;
+    adapter: AdapterBody;
+    needsBaseURL: boolean;
+    authModes: ProviderAuthMode[];
+    subscription?: boolean;
+    credentialOptional?: boolean;
+    modelAdapter?: 'openai-responses' | 'anthropic-messages';
+    baseURLPlaceholder?: string;
+    defaultModel?: string;
+    unsupportedParams?: readonly string[];
+}
+declare function registerProvider(descriptor: ProviderDescriptor): void;
+declare function getProvider(id: string): ProviderDescriptor | undefined;
+declare function listProviders(): ProviderDescriptor[];
+declare function clearProviderRegistry(): void;
+
+/** Neutral facts for one completed provider dispatch. Missing facts are omitted. */
+interface ModelCallReport {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    respondingModelId?: string;
+}
+type ModelCallEvent = {
+    kind: 'start';
+} | {
+    kind: 'success';
+    report: ModelCallReport;
+} | {
+    kind: 'failure';
+};
+declare const MODEL_CALL_EVENT_KINDS: readonly ["start", "success", "failure"];
+/** An explicit assertion that raw usage and response metadata retain this wire origin. */
+type ModelCallReportOrigin = 'openai-chat' | 'openai-responses' | 'anthropic-messages' | 'gemini';
+declare const MODEL_CALL_REPORT_ORIGINS: readonly ["openai-chat", "openai-responses", "anthropic-messages", "gemini"];
+interface ModelCallObservation {
+    /** Legacy notification, invoked once per dispatch, without provider data. */
+    onProviderCall?: () => void;
+    /** No prompts, credentials, response bodies or error text cross this callback. */
+    onCall?: (event: ModelCallEvent) => void;
+}
+
+interface ModelProviderOverrides {
+    languageModels?: Record<string, LanguageModelV3>;
+    /** Trusted custom/override adapter assertion; omitted means no cache/model authority. */
+    providerReportOrigin?: ModelCallReportOrigin;
+}
+declare function createModel(profile: ModelProfile, auth: ResolvedModelAuth, mask: MaskFn, overrides?: ModelProviderOverrides, observation?: ModelCallObservation): LanguageModelV3;
+
+declare function validateProfile(profile: ModelProfile): void;
+
+interface VisionSizingConfig {
+    screenshotSize?: number;
+    effectiveResolution?: number;
+}
+declare function resolveVisionConfig(servicesVision: VisionSizingConfig | undefined): VisionSizingConfig;
+
+interface VisionGate {
+    attachImage: boolean;
+    captureMode: 'full' | 'textOnly';
+    promptNote: string;
+}
+/** 439 D-19: the configured `vision` when set, otherwise what the capability table says. */
+declare function visionFromConfig(configured: boolean | undefined, capabilities: {
+    vision: boolean;
+}): boolean;
+declare function resolveVisionGate(model: {
+    vision: boolean;
+}): VisionGate;
+
+export { type AdapterBody, type CatalogEntry, type DebugLoggingOptions, type DegradeOptions, type DegradeOutcome, FAMILIES, type LogEntry, MODEL_CALL_EVENT_KINDS, MODEL_CALL_REPORT_ORIGINS, MODEL_CATALOG, type ModelCallEvent, type ModelCallObservation, type ModelCallReport, type ModelCallReportOrigin, type ModelProviderOverrides, type ProviderAuthMode, type ProviderDescriptor, type ResolvedModelAuth, type TokenAccounting, type TokenAccountingOptions, type Transport, UNKNOWN_FLOOR, type VisionGate, type VisionSizingConfig, anthropicCompatible, anthropicSubscription, capabilityKey, capabilityUpdateMiddleware, clearProviderRegistry, compactLogs, createModel, createTokenAccounting, debugLoggingMiddleware, deriveExamplesMiddleware, deriveTransport, dropEmptyMessagesMiddleware, extractJsonStrategy, fetchLiveModels, gemini, getModelCatalog, getObservedWindow, getProvider, getProviderOptions, guardBlob, guardToolOutput, isContextOverflow as isContextLengthOverflow, isContextOverflow, listProviders, matchFamily, mergeCatalog, openaiCompatible, openaiSubscription, overrideStore, parseRealWindow, registerProvider, repairMiddleware, resolveCapabilities, resolveVisionConfig, resolveVisionGate, retryMiddleware, stripUnsupportedParamsMiddleware, toolSchemaMiddleware, validateProfile, visionFromConfig };