@cuylabs/agent-core 4.9.0 → 5.0.0

package/dist/middleware/types.d.ts

@@ -0,0 +1,426 @@
+/**
+ * Middleware Types
+ *
+ * Defines the composable middleware interface for agent lifecycle hooks.
+ *
+ * Middleware is just a plain object with optional hook methods — no
+ * base classes, no discovery, no installation. Pass it in code:
+ *
+ * ```typescript
+ * const agent = createAgent({
+ *   middleware: [myLoggerMiddleware, myApprovalMiddleware],
+ * });
+ * ```
+ *
+ * Hooks run in array order for "before" operations and reverse order
+ * for "after" operations (like middleware stacks everywhere).
+ */
+import type { LanguageModel, ModelMessage, SystemModelMessage, TelemetryOptions } from "ai";
+import type { ProviderOptions } from "@ai-sdk/provider-utils";
+import type { AgentContextCompactionPhase, AgentEvent } from "../types/events.js";
+import type { PromptBuildContext, PromptSection } from "../prompt/types.js";
+import type { Message, TokenUsage } from "../types/messages.js";
+import type { RecentMessagesOptions as SessionRecentMessagesOptions } from "../sessions/manager/types.js";
+import type { ScopeSnapshot } from "../execution/scope/types.js";
+import type { StreamChunk, StreamProvider } from "../types/stream.js";
+import type { ToolContext } from "../types/tool.js";
+import type { Tool } from "../tool/tool.js";
+import type { ReasoningLevel } from "../models/reasoning/index.js";
+import type { ApprovalCorrection } from "../safety/types.js";
+import type { AgentContextFragmentBuildContext, AgentContextFragmentInput } from "../context/fragments/types.js";
+import type { ContextCompactionDecision } from "../context/window/index.js";
+import type { CompactionCutReason, CompactionEffectiveness, CompactionReason, CompactionTrigger } from "../types/compaction.js";
+/**
+ * Action returned by `beforeToolCall` — determines whether
+ * the tool call proceeds or is blocked.
+ */
+export interface ToolCallDecision {
+    /** Whether to allow or deny the tool call */
+    action: "allow" | "deny";
+    /** Reason for denial — returned to the model as the tool output */
+    reason?: string;
+    /**
+     * Structured correction metadata for denied tool calls.
+     *
+     * Hosts and runtimes can persist this even though the model still receives
+     * a string tool result.
+     */
+    correction?: ApprovalCorrection;
+    /**
+     * Rewritten tool arguments. When present, replaces the original
+     * args for the remainder of the execution pipeline (schema validation,
+     * baseline capture, and execution).
+     *
+     * Only meaningful when `action` is `"allow"`. Use this for path
+     * rewriting, sandbox prefixing, argument sanitization, or injecting
+     * default values — without the tool knowing about the transformation.
+     *
+     * @example
+     * ```typescript
+     * beforeToolCall: async (tool, args, ctx) => {
+     *   if (tool === "write_file") {
+     *     const a = args as { path: string };
+     *     return {
+     *       action: "allow",
+     *       args: { ...a, path: resolveSandboxPath(a.path) },
+     *     };
+     *   }
+     *   return { action: "allow" };
+     * },
+     * ```
+     */
+    args?: unknown;
+}
+/**
+ * Mutable model invocation payload presented to middleware before an LLM call.
+ */
+export interface ModelCallInput {
+    model: LanguageModel;
+    system: string[];
+    messages: ModelMessage[];
+    temperature?: number;
+    topP?: number;
+    maxOutputTokens?: number;
+    maxSteps?: number;
+    reasoningLevel?: ReasoningLevel;
+    telemetry?: TelemetryOptions;
+    customStreamProvider?: StreamProvider;
+    toolExecutionMode?: "auto" | "plan";
+    /**
+     * Provider-specific options passed through to `streamText()`.
+     *
+     * Middleware can set these to enable provider features like Anthropic
+     * prompt caching (`{ anthropic: { cacheControl: { type: "ephemeral" } } }`).
+     *
+     * When multiple sources set providerOptions (e.g. middleware + reasoning),
+     * they are shallow-merged before the LLM call.
+     */
+    providerOptions?: ProviderOptions;
+    /**
+     * System messages with provider-specific options.
+     *
+     * When set, these take precedence over the plain `system` strings.
+     * This allows middleware to attach per-message metadata such as
+     * Anthropic `cacheControl` breakpoints on system content.
+     *
+     * Leave undefined to use the plain `system` string array.
+     */
+    systemMessages?: SystemModelMessage[];
+}
+/**
+ * Context shared across model middleware hooks for a single step.
+ */
+export interface ModelCallContext {
+    sessionID: string;
+    turnID?: string;
+    step: number;
+    cwd: string;
+    abort: AbortSignal;
+    model: LanguageModel;
+    toolNames: string[];
+    mcpToolNames: string[];
+    scope?: ScopeSnapshot;
+}
+/**
+ * Return this from `model.input(...)` to stop an LLM call entirely.
+ */
+export interface BlockedModelCall {
+    block: true;
+    reason: string;
+}
+/** Type guard for `BlockedModelCall`. */
+export declare function isBlockedModelCall(value: ModelCallInput | BlockedModelCall): value is BlockedModelCall;
+/**
+ * Final step result exposed to model middleware after the stream is processed.
+ */
+export interface ModelCallOutput {
+    text: string;
+    usage?: TokenUsage;
+    finishReason?: string;
+}
+/**
+ * Context shared across chat lifecycle hooks for a single turn.
+ */
+export interface ChatLifecycleContext {
+    sessionId: string;
+    turnId?: string;
+    history?: HistoryAccessor;
+}
+/**
+ * Options for reading a bounded slice of recent visible chat messages.
+ */
+export type RecentMessagesOptions = Pick<SessionRecentMessagesOptions, "limit" | "roles">;
+/**
+ * Lazy chat-history accessor exposed to lifecycle middleware.
+ *
+ * The chat loop passes this accessor by reference; messages are only read and
+ * deserialized if middleware calls it.
+ */
+export interface HistoryAccessor {
+    getRecentMessages(options?: RecentMessagesOptions): Message[];
+}
+/**
+ * Extended tool result returned by `afterToolCall` middleware.
+ *
+ * Same shape as `Tool.ExecuteResult` with an optional `supplement` —
+ * extra text appended to the tool output for model visibility.
+ *
+ * Use this to inject warnings, guidance, lint results, or annotations
+ * that the model should see alongside the tool's own output, without
+ * modifying the tool's result directly.
+ *
+ * When multiple middleware add supplements, each one receives the
+ * previous supplement (if any) and can extend or replace it.
+ *
+ * @example
+ * ```typescript
+ * afterToolCall: async (tool, args, result) => {
+ *   if (tool === "write_file") {
+ *     const warnings = await lintFile(args.path);
+ *     return { ...result, supplement: warnings };
+ *   }
+ *   return result;
+ * },
+ * ```
+ */
+export interface ToolCallOutput extends Tool.ExecuteResult {
+    /**
+     * Supplementary text appended to the tool output for the model.
+     *
+     * Kept separate from `output` so the original tool result stays
+     * untouched. The executor merges this into the final output string
+     * before returning it to the model.
+     */
+    supplement?: string;
+}
+/**
+ * Shared context for middleware that observes a context compaction pass.
+ *
+ * `beforeContextCompactionCommit` receives the proposed replacement after the
+ * cut and summary are prepared, before it is committed to session history.
+ * `afterContextCompactionCommit` receives the same shape after the session has
+ * been replaced.
+ */
+export interface ContextCompactionHookContext {
+    sessionId: string;
+    turnId?: string;
+    cwd: string;
+    phase?: AgentContextCompactionPhase;
+    trigger?: CompactionTrigger;
+    reason?: CompactionReason;
+    inputTokens: number;
+    limit: number;
+    decision: ContextCompactionDecision;
+    effectiveness: CompactionEffectiveness;
+    removedMessages: readonly Message[];
+    keptMessages: readonly Message[];
+    messagesAfter: readonly Message[];
+    persistedMessages: readonly Message[];
+    removedCount: number;
+    tokensRemoved: number;
+    summarized: boolean;
+    previousSummary?: string;
+    nextSummary?: string;
+    cutIndex?: number;
+    cutReason?: CompactionCutReason;
+    tokensBefore: number;
+    tokensAfter: number;
+    abort?: AbortSignal;
+}
+/**
+ * Optional model-specific hooks grouped under `middleware.model`.
+ */
+export interface AgentModelHooks {
+    /**
+     * Review or rewrite the model request before the LLM is invoked.
+     *
+     * Return:
+     * - `undefined` to keep the current request
+     * - a `ModelCallInput` object to replace the request
+     * - `{ block: true, reason }` to cancel the model call
+     *
+     * Hooks run in middleware array order. The first block stops the call.
+     */
+    input?(input: ModelCallInput, ctx: ModelCallContext): Promise<ModelCallInput | BlockedModelCall | void>;
+    /**
+     * Review or rewrite raw stream chunks as they arrive from the model.
+     *
+     * Return:
+     * - `undefined` to keep the current chunk
+     * - a `StreamChunk` to replace it
+     * - `null` to drop it from downstream processing
+     *
+     * Hooks run in middleware array order.
+     */
+    chunk?(chunk: StreamChunk, ctx: ModelCallContext): Promise<StreamChunk | null | void>;
+    /**
+     * Review or rewrite the fully processed model result for the current step.
+     *
+     * Hooks run in reverse middleware order so outer middleware sees the final
+     * shaped result, matching `afterToolCall(...)`.
+     */
+    output?(output: ModelCallOutput, ctx: ModelCallContext): Promise<ModelCallOutput | void>;
+}
+/**
+ * Agent middleware — composable lifecycle hooks.
+ *
+ * All methods are optional. Implement only what you need.
+ *
+ * Ordering:
+ * - `beforeToolCall`: runs in array order, first "deny" wins
+ * - `afterToolCall`: runs in reverse order (innermost first)
+ * - `model.input`: runs in array order, first block wins
+ * - `model.chunk`: runs in array order on raw stream chunks
+ * - `model.output`: runs in reverse order
+ * - `promptSections`: all run, sections merged
+ * - `beforeContextCompactionCommit`: runs in array order before session history is replaced
+ * - `afterContextCompactionCommit`: runs in reverse order after session history is replaced
+ * - `onEvent`: all run synchronously, errors logged, never blocks the stream
+ * - `onChatStart` / `onChatEnd`: run in array order, awaited sequentially
+ *
+ * @example
+ * ```typescript
+ * // A simple logging middleware
+ * const logger: AgentMiddleware = {
+ *   name: "logger",
+ *   beforeToolCall: async (tool, args) => {
+ *     console.log(`→ ${tool}`, args);
+ *     return { action: "allow" };
+ *   },
+ *   afterToolCall: async (tool, args, result) => {
+ *     console.log(`← ${tool}`, result.title);
+ *     return result;
+ *   },
+ * };
+ * ```
+ */
+export interface AgentMiddleware {
+    /** Middleware name (for logging and debugging) */
+    name: string;
+    /**
+     * Optional hooks for shaping model requests, raw stream chunks,
+     * and final step outputs.
+     */
+    model?: AgentModelHooks;
+    /**
+     * Intercept a tool call before execution.
+     *
+     * Return `{ action: "allow" }` to proceed, or `{ action: "deny", reason }` to
+     * block the call. When denied, `reason` is returned to the model as the tool
+     * output so it can adjust its approach.
+     *
+     * Runs in array order. The first middleware that returns "deny" short-circuits
+     * the chain — remaining middleware and the tool itself are skipped.
+     *
+     * @param tool   - Tool name (e.g. "bash", "write_file")
+     * @param args   - Parsed tool arguments
+     * @param ctx    - Tool execution context (cwd, sessionID, host, etc.)
+     */
+    beforeToolCall?(tool: string, args: unknown, ctx: ToolContext): Promise<ToolCallDecision>;
+    /**
+     * Transform or observe a tool result after execution.
+     *
+     * Receives the result and must return a result (can be the same object
+     * or a modified copy). Runs in reverse array order so the outermost
+     * middleware sees the final transformed result.
+     *
+     * @param tool   - Tool name
+     * @param args   - Original tool arguments
+     * @param result - Tool execution result
+     * @param ctx    - Tool execution context
+     */
+    afterToolCall?(tool: string, args: unknown, result: ToolCallOutput, ctx: ToolContext): Promise<ToolCallOutput>;
+    /**
+     * Inject dynamic prompt sections at build time.
+     *
+     * Called during `PromptBuilder.build()` for each middleware. Return one
+     * or more sections to inject into the system prompt. Return `undefined`
+     * or an empty array to inject nothing.
+     *
+     * Sections follow the same priority system as static sections — use
+     * `priority` to control placement relative to base template (10),
+     * environment (20), instructions (30), custom (50), skills (70),
+     * and per-turn overrides (90).
+     *
+     * @param ctx - Build context with cwd, model, toolNames, sessionId
+     */
+    promptSections?(ctx: PromptBuildContext): PromptSection | PromptSection[] | undefined;
+    /**
+     * Inject typed model-visible context messages before each model step.
+     *
+     * Use this for runtime/session context that should be distinguishable from
+     * normal user conversation: environment snapshots, memory recall, workflow
+     * hints, or hook-added context. Returned context fragments are transient
+     * unless the caller also persists them through
+     * `SessionManager.addContextFragment(...)`.
+     */
+    contextFragments?(ctx: AgentContextFragmentBuildContext): AgentContextFragmentInput | AgentContextFragmentInput[] | undefined | Promise<AgentContextFragmentInput | AgentContextFragmentInput[] | undefined>;
+    /**
+     * Observe or persist information immediately before context compaction
+     * replaces visible session history.
+     *
+     * Use this for blocking durability work that must see removed messages before
+     * they leave the model-visible window, such as memory capture. Errors are
+     * logged and do not abort compaction.
+     */
+    beforeContextCompactionCommit?(ctx: ContextCompactionHookContext): Promise<void> | void;
+    /**
+     * Observe a completed context compaction after session history has been
+     * replaced.
+     *
+     * Use this for follow-up bookkeeping that should only happen after the
+     * compacted history is committed. Errors are logged and do not abort the turn.
+     */
+    afterContextCompactionCommit?(ctx: ContextCompactionHookContext): Promise<void> | void;
+    /**
+     * Observe agent events (read-only, non-blocking).
+     *
+     * Fires for every event emitted during `chat()`. Errors thrown by
+     * handlers are caught and logged — they never interrupt the stream.
+     *
+     * This is intentionally synchronous (void return) to prevent
+     * event observers from blocking the streaming pipeline.
+     *
+     * @param event - The agent event
+     */
+    onEvent?(event: AgentEvent): void;
+    /**
+     * Called when `chat()` starts, before the LLM stream is created.
+     *
+     * Use this for setup: initializing loggers, recording start time,
+     * resetting per-turn state, etc. Runs in array order, awaited
+     * sequentially.
+     *
+     * @param sessionId - Session identifier
+     * @param message   - The user message being sent
+     */
+    onChatStart?(sessionId: string, message: string, ctx?: ChatLifecycleContext): Promise<void>;
+    /**
+     * Called when `chat()` completes (or errors), after all events
+     * have been yielded.
+     *
+     * Use this for teardown: flushing logs, recording metrics, etc.
+     * Runs in array order, awaited sequentially. Always called, even
+     * if the stream errored.
+     *
+     * Turn-scoped tool cleanup runs after `onChatEnd`, so middleware can still
+     * inspect the just-resolved turn tool objects during this hook.
+     *
+     * @param sessionId - Session identifier
+     * @param result    - Completion info (usage stats and optional error)
+     */
+    onChatEnd?(sessionId: string, result: {
+        usage?: TokenUsage;
+        error?: Error;
+        output?: string;
+    }, ctx?: ChatLifecycleContext): Promise<void>;
+    /**
+     * Get the active OTel context for a session.
+     *
+     * Used internally by the LLM layer to wrap `streamText()` so that
+     * AI SDK spans are nested under the middleware's parent span.
+     * Only implemented by the `otelMiddleware`.
+     */
+    getOtelContext?(sessionId: string, ctx?: ChatLifecycleContext): unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/middleware/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"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"}

package/dist/models/cache/adapters.d.ts

@@ -0,0 +1,4 @@
+import type { StorageAdapter } from "./types.js";
+import type { Logger } from "../../logger/types.js";
+export declare function createCapabilityCacheAdapter(cachePath: string, logger?: Logger): StorageAdapter;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/models/cache/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../../src/models/cache/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAyHpD,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,cAAc,CAUhB"}

package/dist/models/cache/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Capability cache storage adapters and source integration.
+ */
+export { CapabilityCache, CacheCapabilitySource } from "./manager.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/models/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/models/cache/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC"}

package/dist/models/cache/manager.d.ts

@@ -0,0 +1,32 @@
+import type { CapabilitySource, ModelEntry, ResolverOptions, SourceResult } from "../types.js";
+import { SourcePriority } from "../types.js";
+import type { Logger } from "../../logger/types.js";
+export declare class CapabilityCache {
+    private adapter;
+    private memoryCache;
+    private ttlMs;
+    private loaded;
+    private readonly log;
+    constructor(options?: Partial<ResolverOptions>, logger?: Logger);
+    private load;
+    get(modelId: string, provider?: string): Promise<ModelEntry | undefined>;
+    set(entry: ModelEntry): Promise<void>;
+    setMany(entries: ModelEntry[]): Promise<void>;
+    persist(): Promise<void>;
+    clear(): Promise<void>;
+    stats(): {
+        size: number;
+        loaded: boolean;
+    };
+    getAll(): Promise<ModelEntry[]>;
+    getAllByProvider(): Promise<Record<string, ModelEntry[]>>;
+}
+export declare class CacheCapabilitySource implements CapabilitySource {
+    private cache;
+    readonly priority = SourcePriority.LocalCache;
+    readonly name = "Local Cache";
+    constructor(cache: CapabilityCache);
+    lookup(modelId: string, provider?: string): Promise<SourceResult>;
+    isAvailable(): Promise<boolean>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/models/cache/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/models/cache/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACV,eAAe,EACf,YAAY,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAA4B,cAAc,EAAE,MAAM,aAAa,CAAC;AAGvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAC;IAChB,OAAO,CAAC,WAAW,CAAsC;IACzD,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,OAAO,GAAE,OAAO,CAAC,eAAe,CAAM,EAAE,MAAM,CAAC,EAAE,MAAM;YAOrD,IAAI;IAoBZ,GAAG,CACP,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAK5B,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrC,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAcxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE;IAOpC,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAK/B,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;CAYhE;AAED,qBAAa,qBAAsB,YAAW,gBAAgB;IAIhD,OAAO,CAAC,KAAK;IAHzB,QAAQ,CAAC,QAAQ,6BAA6B;IAC9C,QAAQ,CAAC,IAAI,iBAAiB;gBAEV,KAAK,EAAE,eAAe;IAEpC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAiBjE,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAGtC"}

package/dist/models/cache/types.d.ts

@@ -0,0 +1,17 @@
+import type { ModelEntry } from "../types.js";
+export interface CacheData {
+    version: number;
+    updatedAt: string;
+    expiresAt: string;
+    models: Record<string, ModelEntry>;
+    source?: string;
+}
+export interface StorageAdapter {
+    read(): Promise<CacheData | undefined>;
+    write(data: CacheData): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare const CACHE_VERSION = 1;
+export declare function cacheKey(modelId: string, provider?: string): string;
+export declare function isExpired(data: CacheData): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/models/cache/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/models/cache/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,IAAI,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAElD"}

package/dist/models/capability-resolver.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Model Capability Resolver for @cuylabs/agent-core
+ *
+ * Main orchestrator that combines multiple capability sources:
+ * 1. User overrides (highest priority)
+ * 2. Local cache (fast, persisted)
+ * 3. Pattern matching (always available)
+ * 4. Remote API (optional, network-dependent)
+ *
+ * Designed for the Vercel AI SDK v6 ecosystem.
+ */
+import type { LanguageModel } from "ai";
+import type { ModelEntry, ModelCapabilities, ResolverOptions, ProviderCompatibility } from "./types.js";
+import { SourcePriority } from "./types.js";
+import { type NetworkStatus } from "./remote/index.js";
+import type { Logger } from "../logger/types.js";
+/**
+ * Resolution result with source information
+ */
+export interface ResolutionResult {
+    /** The resolved model entry */
+    entry: ModelEntry;
+    /** Which source provided the primary result */
+    source: SourcePriority;
+    /** Whether this is a confident match */
+    confident: boolean;
+    /** Resolution timing in ms */
+    resolveTimeMs: number;
+}
+/**
+ * Model Capability Resolver
+ *
+ * Provides a unified API for querying model capabilities with
+ * automatic fallback through multiple sources.
+ */
+export declare class ModelCapabilityResolver {
+    private options;
+    private cache;
+    private sources;
+    private initialized;
+    private initPromise;
+    private readonly log;
+    constructor(options?: Partial<ResolverOptions>, logger?: Logger);
+    /**
+     * Initialize the resolver (load cache, optionally fetch remote)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Resolve capabilities for a model
+     */
+    resolve(model: LanguageModel): Promise<ResolutionResult>;
+    /**
+     * Quick check if a model supports reasoning
+     * Uses cache/patterns only for speed
+     */
+    supportsReasoning(model: LanguageModel): Promise<boolean>;
+    /**
+     * Get capabilities for a model
+     */
+    getCapabilities(model: LanguageModel): Promise<ModelCapabilities>;
+    /**
+     * Get provider compatibility settings
+     */
+    getCompatibility(model: LanguageModel): Promise<ProviderCompatibility | undefined>;
+    /**
+     * Force refresh from remote API
+     */
+    refreshRemote(): Promise<void>;
+    /**
+     * Get current network status
+     */
+    getNetworkStatus(): NetworkStatus;
+    /**
+     * Get resolver statistics
+     */
+    getStats(): {
+        cacheSize: number;
+        cacheLoaded: boolean;
+        remoteFetchEnabled: boolean;
+        networkOnline: boolean;
+    };
+    /**
+     * Clear all cached data
+     */
+    clearCache(): Promise<void>;
+    /**
+     * List all available models
+     * Fetches from remote if cache is empty and remote is enabled
+     */
+    listModels(): Promise<ModelEntry[]>;
+    /**
+     * List all available models grouped by provider
+     */
+    listModelsByProvider(): Promise<Record<string, ModelEntry[]>>;
+}
+/**
+ * Get the default resolver instance
+ */
+export declare function getDefaultResolver(): ModelCapabilityResolver;
+/**
+ * Configure the default resolver with custom options
+ */
+export declare function configureResolver(options: Partial<ResolverOptions>): void;
+//# sourceMappingURL=capability-resolver.d.ts.map

package/dist/models/capability-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-resolver.d.ts","sourceRoot":"","sources":["../../src/models/capability-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAExC,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EAGjB,eAAe,EACf,qBAAqB,EACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAA4B,MAAM,YAAY,CAAC;AAMtE,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAOjD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,KAAK,EAAE,UAAU,CAAC;IAClB,+CAA+C;IAC/C,MAAM,EAAE,cAAc,CAAC;IACvB,wCAAwC;IACxC,SAAS,EAAE,OAAO,CAAC;IACnB,8BAA8B;IAC9B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,OAAO,GAAE,OAAO,CAAC,eAAe,CAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAoBnE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA6BjC;;OAEG;IACG,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA0D9D;;;OAGG;IACG,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAc/D;;OAEG;IACG,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAKvE;;OAEG;IACG,gBAAgB,CACpB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC;IAK7C;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAcpC;;OAEG;IACH,gBAAgB,IAAI,aAAa;IAIjC;;OAEG;IACH,QAAQ,IAAI;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,OAAO,CAAC;QACrB,kBAAkB,EAAE,OAAO,CAAC;QAC5B,aAAa,EAAE,OAAO,CAAC;KACxB;IAYD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAoBzC;;OAEG;IACG,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;CAkBpE;AAQD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,uBAAuB,CAQ5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAEzE"}

package/dist/models/identifiers.d.ts

@@ -0,0 +1,23 @@
+import type { LanguageModel } from "ai";
+/**
+ * Extract a model ID string from a LanguageModel instance.
+ */
+export declare function getModelId(model: LanguageModel): string;
+/**
+ * Extract a provider identifier from a LanguageModel instance.
+ */
+export declare function getProviderId(model: LanguageModel): string | undefined;
+/**
+ * Extract model ID from a LanguageModel.
+ *
+ * Canonical helper — use this instead of `getModelId` in consumer code.
+ */
+export declare const extractModelId: (model: LanguageModel) => string;
+/**
+ * Extract provider from a LanguageModel.
+ *
+ * Tries the model's `.provider` property first, then falls back
+ * to pattern-matching the model ID via `inferProvider`.
+ */
+export declare function extractProvider(model: LanguageModel): string | undefined;
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/models/identifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/models/identifiers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAGxC;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAMvD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAYtE;AAID;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,MAAmB,CAAC;AAE3E;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAGxE"}