botinabox 2.9.1 → 2.9.2

package/dist/core/chat/session-key.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SessionKey — structured key for chat sessions.
+ * Story 4.3
+ */
+export declare class SessionKey {
+    readonly agentId: string;
+    readonly channel: string;
+    readonly scope: string;
+    constructor(agentId: string, channel: string, scope: string);
+    toString(): string;
+    toJSON(): {
+        agentId: string;
+        channel: string;
+        scope: string;
+    };
+    static fromString(key: string): SessionKey;
+    /**
+     * Build a session key from structured parameters.
+     *
+     * @param agentId      - The agent identifier
+     * @param channel      - The channel identifier
+     * @param chatType     - 'dm' or 'group'
+     * @param peerId       - The peer/user ID
+     * @param dmScope      - DM scoping strategy
+     *   - 'main'               → single session per agent+channel regardless of peer
+     *   - 'per-peer'           → one session per (agent, peer)
+     *   - 'per-channel-peer'   → one session per (agent, channel, peer)
+     */
+    static build(agentId: string, channel: string, chatType: "dm" | "group", peerId: string, dmScope: "main" | "per-peer" | "per-channel-peer"): SessionKey;
+}

package/dist/core/chat/session-manager.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ChatSessionManager — wraps orchestrator SessionManager with SessionKey-based lookup.
+ * Story 4.3
+ */
+import type { DataStore } from "../data/data-store.js";
+import { SessionKey } from "./session-key.js";
+export declare class ChatSessionManager {
+    private readonly inner;
+    constructor(db: DataStore);
+    save(key: SessionKey, params: Record<string, unknown>): Promise<string>;
+    load(key: SessionKey): Promise<Record<string, unknown> | undefined>;
+    clear(key: SessionKey): Promise<void>;
+    shouldClear(session: Record<string, unknown>, opts: {
+        maxRuns?: number;
+        maxAgeHours?: number;
+    }): Promise<boolean>;
+}

package/dist/core/chat/text-chunker.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Text chunker — splits long text into chunks at natural boundaries.
+ * Story 4.4
+ */
+/**
+ * Split text into chunks of at most maxLen characters.
+ * Splits at paragraph boundaries first, then sentence, then word, then hard-cuts.
+ */
+export declare function chunkText(text: string, maxLen: number): string[];

package/dist/core/chat/triage-router.d.ts

@@ -0,0 +1,75 @@
+/**
+ * TriageRouter — content-based routing with deterministic-first resolution.
+ * Story 6.3
+ *
+ * Replaces the simple channel→agent binding with intelligent routing:
+ * 1. Keyword/regex rules evaluated first (deterministic, ~4ms)
+ * 2. LLM classification only for ambiguous messages (async, ~2-4s)
+ * 3. Ownership chain logged for every routing decision
+ *
+ * Key constraint: specialists return to triage, never to another specialist.
+ */
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+import type { InboundMessage } from './types.js';
+export interface RoutingRule {
+    /** Target agent slug */
+    agentSlug: string;
+    /** Keywords that trigger this rule (case-insensitive) */
+    keywords?: string[];
+    /** Regex patterns that trigger this rule */
+    patterns?: string[];
+    /** Priority — lower number wins ties. Default: 50 */
+    priority?: number;
+}
+export interface RoutingDecision {
+    timestamp: string;
+    source: string;
+    target: string;
+    reason: string;
+    method: 'deterministic' | 'llm';
+    messageId?: string;
+    channel?: string;
+}
+export interface TriageRouterConfig {
+    /** Static routing rules evaluated deterministically */
+    rules: RoutingRule[];
+    /** Fallback agent if no rule matches and LLM is unavailable */
+    fallbackAgent?: string;
+    /** Whether to use LLM for ambiguous messages. Default: true */
+    llmFallback?: boolean;
+    /** Log decisions to the database. Default: true */
+    persist?: boolean;
+}
+export declare class TriageRouter {
+    private db;
+    private hooks;
+    private readonly rules;
+    private readonly fallbackAgent?;
+    private readonly llmFallback;
+    private readonly persist;
+    private readonly compiledRules;
+    constructor(db: DataStore, hooks: HookBus, config: TriageRouterConfig);
+    /**
+     * Route an inbound message to the best agent.
+     * Returns the agent slug and the routing decision.
+     */
+    route(msg: InboundMessage): Promise<{
+        agentSlug: string | undefined;
+        decision: RoutingDecision;
+    }>;
+    /**
+     * Query the ownership chain for a given message or channel.
+     */
+    getDecisionHistory(filter?: {
+        channel?: string;
+        limit?: number;
+    }): Promise<RoutingDecision[]>;
+    /**
+     * LLM classification — emits a hook for external LLM integration.
+     * Returns agent slug + reason, or undefined if LLM is unavailable.
+     */
+    private classifyWithLLM;
+    private buildDecision;
+    private logDecision;
+}

package/dist/core/chat/types.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Chat types — re-exports from @botinabox/shared channel types.
+ * Story 4.1
+ */
+export type { ChatType, FormattingMode, ChannelCapabilities, ChannelMeta, InboundMessage, Attachment, OutboundPayload, SendResult, HealthStatus, ChannelConfig, ChannelAdapter, } from "../../shared/index.js";

package/dist/core/config/defaults.d.ts

@@ -0,0 +1,2 @@
+import type { BotConfig } from "../../shared/index.js";
+export declare const DEFAULT_CONFIG: BotConfig;

package/dist/core/config/index.d.ts

@@ -0,0 +1,6 @@
+export { loadConfig, getConfig, initConfig, _resetConfig } from "./loader.js";
+export type { ConfigLoadError, ConfigLoadResult } from "./loader.js";
+export { interpolateEnv } from "./interpolate.js";
+export { validateConfig } from "./schema.js";
+export type { SchemaError } from "./schema.js";
+export { DEFAULT_CONFIG } from "./defaults.js";

package/dist/core/config/interpolate.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Interpolate ${ENV_VAR} references in YAML string values.
+ * Recursively walks objects and arrays.
+ */
+export declare function interpolateEnv(value: unknown, env?: Record<string, string | undefined>): unknown;

package/dist/core/config/loader.d.ts

@@ -0,0 +1,24 @@
+import type { BotConfig } from "../../shared/index.js";
+export interface ConfigLoadError {
+    field: string;
+    message: string;
+}
+export interface ConfigLoadResult {
+    config: BotConfig;
+    errors: ConfigLoadError[];
+}
+/**
+ * Load and merge config from file, with env var interpolation and runtime overrides.
+ * Merge order: defaults < config file < runtime overrides
+ */
+export declare function loadConfig(opts?: {
+    configPath?: string;
+    overrides?: Partial<BotConfig>;
+    env?: Record<string, string | undefined>;
+}): ConfigLoadResult;
+/** Get the loaded config singleton. Auto-initializes with defaults if not loaded. */
+export declare function getConfig(): BotConfig;
+/** Initialize the config singleton. Returns errors if any. */
+export declare function initConfig(opts?: Parameters<typeof loadConfig>[0]): ConfigLoadError[];
+/** Reset the singleton (for testing) */
+export declare function _resetConfig(): void;

package/dist/core/config/schema.d.ts

@@ -0,0 +1,5 @@
+export interface SchemaError {
+    path: string;
+    message: string;
+}
+export declare function validateConfig(config: unknown): SchemaError[];

package/dist/core/data/context-builder.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SystemContextBuilder — loads entity data from the database and formats
+ * it as markdown for injection into LLM system prompts.
+ *
+ * Used by both the ChatPipeline (ack layer) and ExecutionEngine (agent layer)
+ * to give LLMs awareness of the system state.
+ */
+import type { DataStore } from './data-store.js';
+export interface SystemContextOptions {
+    /** Include users. Default: true */
+    users?: boolean;
+    /** Include agents. Default: true */
+    agents?: boolean;
+    /** Include projects. Default: true */
+    projects?: boolean;
+    /** Include clients. Default: true */
+    clients?: boolean;
+    /** Include files. Default: true */
+    files?: boolean;
+    /** Include org. Default: true */
+    org?: boolean;
+}
+/**
+ * Build a markdown-formatted system context string from the database.
+ * Queries users, agents, projects, clients, files, and org.
+ */
+export declare function buildSystemContext(db: DataStore, options?: SystemContextOptions): Promise<string>;

package/dist/core/data/core-entity-contexts.d.ts

@@ -0,0 +1,14 @@
+import type { DataStore } from "./data-store.js";
+/**
+ * Define default entity context rendering for botinabox core tables.
+ * Call after defineCoreTables() and before or after init().
+ *
+ * Renders:
+ * - agents/ — per-agent context (AGENT.md, PROJECTS.md if agent_project exists)
+ * - users/  — per-user context (USER.md) — protected
+ * - skills/ — per-skill context (SKILL.md)
+ *
+ * Apps can override by calling db.defineEntityContext() with the same table name
+ * BEFORE calling defineCoreEntityContexts().
+ */
+export declare function defineCoreEntityContexts(db: DataStore): void;

package/dist/core/data/core-migrations.d.ts

@@ -0,0 +1,5 @@
+/** Initial migration set for core tables */
+export declare const CORE_MIGRATIONS: Array<{
+    version: string;
+    sql: string;
+}>;

package/dist/core/data/core-schema.d.ts

@@ -0,0 +1,6 @@
+import type { DataStore } from "./data-store.js";
+/**
+ * Define all 18 core tables on a DataStore instance.
+ * Call before db.init().
+ */
+export declare function defineCoreTables(db: DataStore): void;

package/dist/core/data/data-store.d.ts

@@ -0,0 +1,67 @@
+import type { HookBus } from '../hooks/hook-bus.js';
+import type { EntityContextDef, PkLookup, QueryOptions, Row, SeedItem, TableDefinition, TableInfoRow } from './types.js';
+export declare class DataStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thin wrapper around Lattice that provides the botinabox DataStore API.
+ *
+ * Delegates all data operations to the latticesql package. Application-level
+ * events (task.created, run.completed, etc.) remain on the HookBus — they are
+ * emitted by orchestrator modules, not the data layer.
+ */
+export declare class DataStore {
+    private lattice;
+    private readonly hooks;
+    private readonly outputDir;
+    private _initialized;
+    private readonly deferredStatements;
+    constructor(opts: {
+        dbPath: string;
+        outputDir?: string;
+        wal?: boolean;
+        hooks?: HookBus;
+    });
+    /**
+     * Register a table definition. Must be called before init().
+     *
+     * tableConstraints may contain both inline constraints (FOREIGN KEY, UNIQUE)
+     * and standalone SQL statements (CREATE INDEX). Standalone statements are
+     * deferred and executed after init() creates the tables.
+     */
+    define(name: string, def: TableDefinition): void;
+    /**
+     * Register an entity context definition for per-entity file rendering.
+     */
+    defineEntityContext(name: string, def: EntityContextDef): void;
+    init(opts?: {
+        migrations?: Array<{
+            version: string;
+            sql: string;
+        }>;
+    }): Promise<void>;
+    private assertInitialized;
+    insert(table: string, row: Row): Promise<Row>;
+    upsert(table: string, row: Row): Promise<Row>;
+    update(table: string, pk: PkLookup, changes: Row): Promise<Row>;
+    delete(table: string, pk: PkLookup): Promise<void>;
+    /**
+     * Get a single row by primary key.
+     * Returns undefined if not found (Lattice returns null).
+     */
+    get(table: string, pk: PkLookup): Promise<Row | undefined>;
+    query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    count(table: string, opts?: QueryOptions): Promise<number>;
+    link(junctionTable: string, row: Row): Promise<void>;
+    unlink(junctionTable: string, row: Row): Promise<void>;
+    migrate(migrations: Array<{
+        version: string;
+        sql: string;
+    }>): Promise<void>;
+    seed(items: SeedItem[]): Promise<void>;
+    render(): Promise<void>;
+    reconcile(): Promise<void>;
+    tableInfo(table: string): TableInfoRow[];
+    close(): void;
+    on(event: string, handler: (context: Record<string, unknown>) => void): void;
+}

package/dist/core/data/domain-entity-contexts.d.ts

@@ -0,0 +1,35 @@
+import type { DataStore } from "./data-store.js";
+/**
+ * Options for domain entity context generation.
+ * Match the options used in defineDomainTables().
+ */
+export interface DomainEntityContextOptions {
+    clients?: boolean;
+    repositories?: boolean;
+    files?: boolean;
+    channels?: boolean;
+    rules?: boolean;
+    /** Column used as directory name for each entity type. Default: 'id'. */
+    orgSlugColumn?: string;
+    projectSlugColumn?: string;
+    clientSlugColumn?: string;
+    fileSlugColumn?: string;
+    channelSlugColumn?: string;
+}
+/**
+ * Define entity context rendering for standard domain tables.
+ * Call after defineDomainTables() and defineCoreTables().
+ *
+ * Renders per-entity directories with context files for:
+ * org, project, + optional client, file, channel entities.
+ * Also adds PROJECTS.md, RULES.md, SKILLS.md, REPOS.md to agent context.
+ *
+ * @example
+ * ```ts
+ * defineCoreTables(db);
+ * defineDomainTables(db);
+ * defineCoreEntityContexts(db);    // agents, users, skills
+ * defineDomainEntityContexts(db);  // org, project, client, file, channel
+ * ```
+ */
+export declare function defineDomainEntityContexts(db: DataStore, options?: DomainEntityContextOptions): void;

package/dist/core/data/domain-schema.d.ts

@@ -0,0 +1,36 @@
+import type { DataStore } from "./data-store.js";
+/**
+ * Options for domain table generation.
+ * Enable/disable optional tables based on your app's needs.
+ */
+export interface DomainSchemaOptions {
+    /** Include client + invoice tables (default: true) */
+    clients?: boolean;
+    /** Include repository table (default: true) */
+    repositories?: boolean;
+    /** Include file table (default: true) */
+    files?: boolean;
+    /** Include channel table (default: true) */
+    channels?: boolean;
+    /** Include rule table + junction tables (default: true) */
+    rules?: boolean;
+    /** Include event audit log (default: true) */
+    events?: boolean;
+    /** Include cross-domain junction tables (default: true) */
+    junctions?: boolean;
+}
+/**
+ * Define standard domain tables that most multi-agent apps need.
+ * Call after defineCoreTables() and before db.init().
+ *
+ * Provides: org, project, + optional client, invoice, repository,
+ * file, channel, rule, event tables with appropriate junction tables.
+ *
+ * @example
+ * ```ts
+ * defineCoreTables(db);
+ * defineDomainTables(db);          // all tables
+ * defineDomainTables(db, { clients: false }); // skip client/invoice
+ * ```
+ */
+export declare function defineDomainTables(db: DataStore, options?: DomainSchemaOptions): void;

package/dist/core/data/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './data-store.js';
+export * from './core-schema.js';
+export * from './core-migrations.js';
+export * from './core-entity-contexts.js';
+export * from './domain-schema.js';
+export * from './domain-entity-contexts.js';
+export * from './context-builder.js';

package/dist/core/data/types.d.ts

@@ -0,0 +1,111 @@
+export interface TableDefinition {
+    columns: Record<string, string>;
+    primaryKey?: string | string[];
+    tableConstraints?: string[];
+    relations?: Record<string, RelationDef>;
+    render?: string | ((rows: Row[]) => string);
+    outputFile?: string;
+    filter?: (rows: Row[]) => Row[];
+}
+export interface RelationDef {
+    type: 'belongsTo' | 'hasMany';
+    table: string;
+    foreignKey: string;
+    references?: string;
+}
+export interface EntityContextDef {
+    table: string;
+    directory: string;
+    slugColumn: string;
+    files: Record<string, EntityFileSpec>;
+    indexFile?: string;
+    /** Custom index render function. If omitted, a default listing is generated. */
+    indexRender?: (rows: Row[]) => string;
+    protectedFiles?: string[];
+    /** When true, this entity's data is never rendered into other entities' context files. */
+    protected?: boolean;
+    /** Enable at-rest encryption. Requires encryptionKey in Lattice options. */
+    encrypted?: boolean | {
+        columns: string[];
+    };
+}
+export interface EntityFileSpec {
+    source: EntitySource;
+    render: string | ((rows: Row[]) => string);
+    junctionColumns?: string[];
+    omitIfEmpty?: boolean;
+}
+export type EntitySource = {
+    type: 'self';
+} | {
+    type: 'hasMany';
+    table: string;
+    foreignKey: string;
+    filters?: Filter[];
+    softDelete?: boolean;
+    orderBy?: string;
+    limit?: number;
+} | {
+    type: 'manyToMany';
+    junctionTable: string;
+    localKey: string;
+    remoteKey: string;
+    remoteTable: string;
+    filters?: Filter[];
+    softDelete?: boolean;
+    orderBy?: string;
+    limit?: number;
+} | {
+    type: 'belongsTo';
+    table: string;
+    foreignKey: string;
+} | {
+    type: 'enriched';
+    include: Record<string, EntitySource>;
+} | {
+    type: 'custom';
+    resolve: (row: Row, adapter: SqliteAdapter) => Row[];
+};
+export interface Filter {
+    col: string;
+    op: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'in' | 'isNull' | 'isNotNull';
+    val?: unknown;
+}
+export interface QueryOptions {
+    where?: Record<string, unknown>;
+    filters?: Filter[];
+    orderBy?: string | Array<{
+        col: string;
+        dir: 'asc' | 'desc';
+    }>;
+    orderDir?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+export type Row = Record<string, unknown>;
+export type PkLookup = string | Record<string, unknown>;
+export interface SqliteAdapter {
+    run(sql: string, params?: unknown[]): import('better-sqlite3').RunResult;
+    get<T = Row>(sql: string, params?: unknown[]): T | undefined;
+    all<T = Row>(sql: string, params?: unknown[]): T[];
+    tableInfo(table: string): TableInfoRow[];
+    invalidateTableCache(table: string): void;
+}
+export interface TableInfoRow {
+    cid: number;
+    name: string;
+    type: string;
+    notnull: number;
+    dflt_value: unknown;
+    pk: number;
+}
+export interface SeedItem {
+    table: string;
+    rows: Row[];
+    naturalKey?: string | string[];
+    junctions?: Array<{
+        table: string;
+        items: Array<Row>;
+    }>;
+    softDeleteMissing?: boolean;
+}

package/dist/core/hooks/hook-bus.d.ts

@@ -0,0 +1,24 @@
+import type { HookHandler, HookOptions, Unsubscribe } from "./types.js";
+/**
+ * Priority-ordered event bus for decoupled inter-layer communication.
+ * Story 1.1 — handlers run in priority order, errors are isolated,
+ * and registrations are unsubscribable.
+ */
+export declare class HookBus {
+    private readonly registrations;
+    private nextId;
+    register(event: string, handler: HookHandler, opts?: HookOptions): Unsubscribe;
+    emit(event: string, context: Record<string, unknown>): Promise<void>;
+    /**
+     * Emit an event and collect handler errors instead of swallowing them.
+     * Handlers still run in priority order and one handler's error does not
+     * block subsequent handlers. Returns the array of errors (empty = success).
+     */
+    emitCollectingErrors(event: string, context: Record<string, unknown>): Promise<Error[]>;
+    /** Emit synchronously (use only when async is not needed) */
+    emitSync(event: string, context: Record<string, unknown>): void;
+    hasListeners(event: string): boolean;
+    listRegistered(): string[];
+    /** Remove all handlers for an event, or all handlers if no event given */
+    clear(event?: string): void;
+}

package/dist/core/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { HookBus } from "./hook-bus.js";
+export type { HookHandler, HookOptions, HookRegistration, Unsubscribe } from "./types.js";

package/dist/core/hooks/types.d.ts

@@ -0,0 +1,19 @@
+export type HookHandler = (context: Record<string, unknown>) => Promise<void> | void;
+export type Unsubscribe = () => void;
+export interface HookOptions {
+    /** 0–100, default 50. Lower = runs first. */
+    priority?: number;
+    /** Auto-unsubscribe after first invocation. */
+    once?: boolean;
+    /** Only fire if context matches all filter key/value pairs. */
+    filter?: Record<string, unknown>;
+}
+export interface HookRegistration {
+    event: string;
+    handler: HookHandler;
+    priority: number;
+    once: boolean;
+    filter?: Record<string, unknown>;
+    /** Internal auto-increment for stable sort within same priority */
+    id: number;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./hooks/index.js";
+export * from "./config/index.js";
+export * from "./llm/index.js";
+export * from "./chat/index.js";

package/dist/core/llm/auto-discovery.d.ts

@@ -0,0 +1,11 @@
+import type { LLMProvider } from "./types.js";
+type Importer = (packageName: string) => Promise<unknown>;
+/**
+ * Scans nodeModulesPath/@botinabox/{pkg}/package.json for each package in the scope.
+ * If pkg.botinabox?.type === 'provider', dynamically imports the package
+ * and returns the discovered LLMProvider instances.
+ *
+ * The optional importer parameter allows injection for testing.
+ */
+export declare function discoverProviders(nodeModulesPath: string, importer?: Importer): Promise<LLMProvider[]>;
+export {};

package/dist/core/llm/cost-tracker.d.ts

@@ -0,0 +1,6 @@
+import type { HookBus } from "../hooks/hook-bus.js";
+import type { DataStore } from "../data/data-store.js";
+import type { ModelInfo } from "./types.js";
+export declare function setupCostTracker(hooks: HookBus, db: DataStore, opts?: {
+    modelCatalog?: ModelInfo[];
+}): void;

package/dist/core/llm/default-llm-call.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Default LLM call function — ready-to-use wrapper around the Anthropic SDK.
+ *
+ * Handles model routing (fast → Haiku, default → Sonnet), message formatting,
+ * and response extraction. Apps can use this directly or provide their own.
+ */
+import type { ChatResponderConfig } from '../chat/chat-responder.js';
+export interface DefaultLLMCallConfig {
+    /** Fast model ID (for acks, interpretation). Default: claude-haiku-4-5-20251001 */
+    fastModel?: string;
+    /** Standard model ID (for execution). Default: claude-sonnet-4-20250514 */
+    defaultModel?: string;
+}
+/**
+ * Create a default LLM call function using the Anthropic SDK.
+ *
+ * @param anthropicClient - An initialized Anthropic client instance
+ * @param config - Optional model configuration
+ */
+export declare function createDefaultLLMCall(anthropicClient: {
+    messages: {
+        create: (params: Record<string, unknown>) => Promise<{
+            content: Array<{
+                type: string;
+                text?: string;
+            }>;
+            model: string;
+            stop_reason: string;
+            usage: {
+                input_tokens: number;
+                output_tokens: number;
+            };
+        }>;
+    };
+}, config?: DefaultLLMCallConfig): ChatResponderConfig['llmCall'];

package/dist/core/llm/index.d.ts

@@ -0,0 +1,6 @@
+export { ProviderRegistry } from "./provider-registry.js";
+export { ModelRouter } from "./model-router.js";
+export { discoverProviders } from "./auto-discovery.js";
+export type { LLMProvider, ModelInfo, ResolvedModel, ChatParams, ChatResult, ChatMessage, ContentBlock, TokenUsage, ToolDefinition, ToolUse, } from "./types.js";
+export { createDefaultLLMCall } from "./default-llm-call.js";
+export type { DefaultLLMCallConfig } from "./default-llm-call.js";

package/dist/core/llm/model-router.d.ts

@@ -0,0 +1,25 @@
+import type { ModelConfig } from "../../shared/index.js";
+import type { ModelInfo, ResolvedModel } from "./types.js";
+import type { ProviderRegistry } from "./provider-registry.js";
+export declare class ModelRouter {
+    private readonly registry;
+    private readonly config;
+    constructor(registry: ProviderRegistry, config: ModelConfig);
+    /**
+     * Resolve a model ID or alias to a ResolvedModel.
+     * 1. Look up alias in config.aliases (or use as-is)
+     * 2. Search all registered providers for a model with that id
+     */
+    resolve(modelIdOrAlias: string): ResolvedModel | undefined;
+    /**
+     * Try primary model, then each in config.fallbackChain.
+     * Throws if none found.
+     */
+    resolveWithFallback(modelIdOrAlias: string): ResolvedModel;
+    /**
+     * Use config.routing[purpose] ?? config.default, then resolveWithFallback.
+     */
+    resolveForPurpose(purpose: string): ResolvedModel;
+    /** Returns all models from all registered providers. */
+    listAvailable(): ModelInfo[];
+}