@wrongstack/core 0.284.1 → 0.286.0

package/dist/models/llm-selector.d.ts

@@ -0,0 +1,47 @@
+import type { Message } from '../types/messages.js';
+import type { Provider } from '../types/provider.js';
+import type { MessageSelector, SelectorResult } from '../types/selector.js';
+export interface LLMSelectorOptions {
+    /** Provider used for the selector LLM call. Required. */
+    provider: Provider;
+    /** Model for the selector. Defaults to the provider's default model. */
+    model?: string | undefined;
+    /**
+     * Maximum tokens to keep in context (target budget).
+     * Selector will aim to keep total content below this.
+     */
+    maxContextTokens?: number | undefined;
+    /**
+     * Prompt instructing the selector how to behave.
+     * Should guide the LLM on importance tiers and output format.
+     */
+    systemPrompt?: string | undefined;
+    /**
+     * Maximum output tokens for the selector LLM call.
+     * Controls both the JSON response budget and the token reservation for the
+     * history text budget calculation (default: 1024).
+     */
+    maxOutputTokens?: number | undefined;
+}
+/**
+ * LLM-powered message selector. Calls a sub-LLM to analyze the
+ * message history and produce a keep/collapse plan — more surgical
+ * than fixed-window rules.
+ */
+export declare class LLMSelector implements MessageSelector {
+    private readonly provider;
+    private readonly model;
+    private readonly maxContextTokens;
+    private readonly systemPrompt;
+    private readonly maxOutputTokens;
+    constructor(opts: LLMSelectorOptions);
+    select(messages: Message[], maxToKeep: number): Promise<SelectorResult>;
+    private fallbackSelect;
+    /**
+     * Parse and validate the raw LLM output into a SelectorResult.
+     * Falls back to recency-based selection if the LLM output is malformed,
+     * out-of-bounds, or internally inconsistent.
+     */
+    private parseSelectorOutput;
+}
+//# sourceMappingURL=llm-selector.d.ts.map

package/dist/models/llm-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-selector.d.ts","sourceRoot":"","sources":["../../src/models/llm-selector.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAW,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE5E,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,QAAQ,EAAE,QAAQ,CAAC;IACnB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAuCD;;;;GAIG;AACH,qBAAa,WAAY,YAAW,eAAe;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEzC,YAAY,IAAI,EAAE,kBAAkB,EAcnC;IAEK,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAwD5E;IAED,OAAO,CAAC,cAAc;IAiCtB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;CAiF5B"}

package/dist/models/mode-store.d.ts

@@ -0,0 +1,22 @@
+import type { Mode, ModeConfig, ModeStore } from '../types/mode.js';
+export declare class DefaultModeStore implements ModeStore {
+    private activeModeId;
+    private modes;
+    private configDir;
+    constructor(config: ModeConfig);
+    getActiveMode(): Promise<Mode | null>;
+    setActiveMode(modeId: string | null): Promise<void>;
+    listModes(): Promise<Mode[]>;
+    getMode(modeId: string): Promise<Mode | null>;
+    addMode(mode: Mode): Promise<void>;
+    removeMode(modeId: string): Promise<void>;
+    private loadActiveMode;
+    private saveActiveMode;
+}
+export interface ModeLoaderOptions {
+    projectModesDir?: string | undefined;
+    userModesDir?: string | undefined;
+}
+export declare function loadProjectModes(modesDir: string): Promise<Mode[]>;
+export declare function loadUserModes(modesDir: string): Promise<Mode[]>;
+//# sourceMappingURL=mode-store.d.ts.map

package/dist/models/mode-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-store.d.ts","sourceRoot":"","sources":["../../src/models/mode-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAgB,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlF,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAS;IAE1B,YAAY,MAAM,EAAE,UAAU,EAG7B;IAEK,aAAa,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAM1C;IAEK,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxD;IAEK,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAEjC;IAEK,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAElD;IAEK,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvC;IAEK,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9C;YAEa,cAAc;YAWd,cAAc;CAc7B;AAED,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAuBxE;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAarE"}

package/dist/models/model-intelligence.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Model Intelligence — knowledge base of model capabilities, strengths,
+ * and task-type suitability. Powers automatic agent → model routing.
+ *
+ * Each entry records:
+ *   - Known strengths (what this model family excels at)
+ *   - Known weaknesses (what it struggles with)
+ *   - Best-for task types (coding, planning, security, docs, etc.)
+ *   - Cost tier (budget / standard / premium)
+ *
+ * This is a curated dataset updated as new models release. Falls back
+ * gracefully for unknown models.
+ */
+export interface ModelProfile {
+    /** Provider id (e.g. "anthropic", "openai"). */
+    provider: string;
+    /** Model id regex — matches partial ids for a model family. */
+    pattern: RegExp;
+    /** Human-readable model family name. */
+    family: string;
+    /** What this model is particularly good at. */
+    strengths: string[];
+    /** Known limitations. */
+    weaknesses?: string[];
+    /** Task types this model is the best choice for. Ordered by preference. */
+    bestFor: TaskType[];
+    /** Task types to avoid with this model (use a different one). */
+    avoidFor?: TaskType[];
+    /** Approximate cost tier. */
+    costTier: 'budget' | 'standard' | 'premium';
+    /** Approximate speed tier (relative to other models). */
+    speedTier: 'fast' | 'normal' | 'slow';
+    /** Minimum recommended context window. */
+    minContext?: number;
+}
+/** Task categories that map to agent roles. */
+export type TaskType = 'coding' | 'planning' | 'security' | 'docs' | 'testing' | 'refactoring' | 'debugging' | 'data' | 'frontend' | 'backend' | 'review' | 'lightweight' | 'general';
+/** Known model profiles. Patterns are tried in order; first match wins. */
+export declare const MODEL_PROFILES: ModelProfile[];
+/** Map task types to the agent roles that handle them. */
+export declare const TASK_TO_ROLE: Record<TaskType, string[]>;
+/**
+ * Infer the most likely task type from a task description and target role.
+ * Uses keyword matching; falls back to the role's primary task type.
+ */
+export declare function inferTaskType(description: string, role?: string): TaskType;
+/**
+ * Find the best matching model profile for a given provider + model id.
+ */
+export declare function findModelProfile(provider: string, modelId: string): ModelProfile | undefined;
+/**
+ * Score a model for a given task type. Higher = better fit.
+ * Returns 0-100.
+ */
+export declare function scoreModelForTask(profile: ModelProfile | undefined, taskType: TaskType): number;
+//# sourceMappingURL=model-intelligence.d.ts.map

package/dist/models/model-intelligence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-intelligence.d.ts","sourceRoot":"","sources":["../../src/models/model-intelligence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,2EAA2E;IAC3E,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;IACtB,6BAA6B;IAC7B,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,yDAAyD;IACzD,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+CAA+C;AAC/C,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,UAAU,GACV,UAAU,GACV,MAAM,GACN,SAAS,GACT,aAAa,GACb,WAAW,GACX,MAAM,GACN,UAAU,GACV,SAAS,GACT,QAAQ,GACR,aAAa,GACb,SAAS,CAAC;AAEd,2EAA2E;AAC3E,eAAO,MAAM,cAAc,EAAE,YAAY,EAuGxC,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,CAcnD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CA8B1E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAO5F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAyB/F"}

package/dist/models/model-router.d.ts

@@ -0,0 +1,100 @@
+/**
+ * ModelRouter — intelligent model selection for subagent delegation.
+ *
+ * Combines:
+ *   1. User-configured model matrix (/setmodel overrides)
+ *   2. Model intelligence profiles (strengths/weaknesses per model family)
+ *   3. Provider availability (which models have API keys configured)
+ *   4. Per-model cost tracking
+ *
+ * Usage:
+ *   const router = new ModelRouter({ matrix, config, profiles: MODEL_PROFILES });
+ *   const pick = router.pickForTask('security-scanner', 'Audit the auth module');
+ *   // → { provider: 'anthropic', model: 'matched-model', reason: 'best-for security' }
+ */
+import type { ModelMatrixEntry, ProviderConfig } from '../types/config.js';
+export interface ModelIntelligenceEntry {
+    provider: string;
+    pattern: RegExp;
+    family: string;
+    strengths: string[];
+    weaknesses?: string[];
+    bestFor: string[];
+    avoidFor?: string[];
+    costTier: 'budget' | 'standard' | 'premium';
+    speedTier: 'fast' | 'normal' | 'slow';
+    minContext?: number;
+}
+export interface RouterConfig {
+    /** User-configured model matrix (from /setmodel). */
+    matrix?: Record<string, ModelMatrixEntry> | undefined;
+    /** Provider configurations (to check API key availability). */
+    config: {
+        provider: string;
+        model: string;
+        providers?: Record<string, ProviderConfig>;
+    };
+    /** Known model intelligence profiles. */
+    profiles?: ModelIntelligenceEntry[] | undefined;
+}
+export interface ModelPick {
+    provider: string;
+    model: string;
+    /** Why this model was chosen. */
+    reason: string;
+    /** Whether this came from the user's matrix (true) or auto-detected (false). */
+    fromMatrix: boolean;
+}
+export interface RouterCosts {
+    /** Cumulative cost per provider/model key. */
+    byModel: Record<string, {
+        cost: number;
+        tokens: {
+            input: number;
+            output: number;
+        };
+        calls: number;
+    }>;
+    /** Grand total. */
+    totalCost: number;
+}
+export declare class ModelRouter {
+    private profiles;
+    private matrix;
+    private config;
+    private costs;
+    constructor(opts: RouterConfig);
+    /** Look up the model matrix resolution for a role (role → phase → * → leader). */
+    private resolveMatrix;
+    /** Simplified phase lookup for common roles. */
+    private roleToPhase;
+    /**
+     * Pick the best model for a task.
+     *
+     * Priority:
+     *   1. User's /setmodel matrix entry for this role (explicit override)
+     *   2. Best-matching model from intelligence profiles
+     *   3. Leader model (fallback)
+     */
+    pickForTask(role: string, description: string): ModelPick;
+    /** Infer task category from description keywords + role. */
+    private inferCategory;
+    /** Find the best available model for a task category. */
+    private findBestModel;
+    /** Check if a provider has an API key configured. */
+    private hasKey;
+    /** Get the configured model list for a provider. */
+    private getProviderModels;
+    /** Record cost for a model. */
+    recordCost(provider: string, model: string, cost: number, tokens?: {
+        input: number;
+        output: number;
+    }): void;
+    /** Get cumulative costs. */
+    getCosts(): RouterCosts;
+    /** Reset cost tracking. */
+    resetCosts(): void;
+    /** List all available providers with their best model for each task category. */
+    suggestMatrix(): Record<string, ModelPick>;
+}
+//# sourceMappingURL=model-router.d.ts.map

package/dist/models/model-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-router.d.ts","sourceRoot":"","sources":["../../src/models/model-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE3E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,CAAC;IACtD,+DAA+D;IAC/D,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;KAC5C,CAAC;IACF,yCAAyC;IACzC,QAAQ,CAAC,EAAE,sBAAsB,EAAE,GAAG,SAAS,CAAC;CACjD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CACb,MAAM,EACN;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAC3E,CAAC;IACF,mBAAmB;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAqID,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,KAAK,CAA8C;IAE3D,YAAY,IAAI,EAAE,YAAY,EAI7B;IAED,kFAAkF;IAClF,OAAO,CAAC,aAAa;IAWrB,gDAAgD;IAChD,OAAO,CAAC,WAAW;IAwCnB;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,CA2BxD;IAED,4DAA4D;IAC5D,OAAO,CAAC,aAAa;IA6BrB,yDAAyD;IACzD,OAAO,CAAC,aAAa;IA8BrB,qDAAqD;IACrD,OAAO,CAAC,MAAM;IAQd,oDAAoD;IACpD,OAAO,CAAC,iBAAiB;IAKzB,+BAA+B;IAC/B,UAAU,CACR,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GACzC,IAAI,CAWN;IAED,4BAA4B;IAC5B,QAAQ,IAAI,WAAW,CAEtB;IAED,2BAA2B;IAC3B,UAAU,IAAI,IAAI,CAEjB;IAED,iFAAiF;IACjF,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CA6BzC;CACF"}

package/dist/models/models-registry.d.ts

@@ -0,0 +1,106 @@
+import type { ModelsDevPayload, ModelsRegistry, ResolvedModel, ResolvedProvider, WireFamily } from '../types/models-registry.js';
+export interface DefaultModelsRegistryOptions {
+    cacheFile: string;
+    url?: string | undefined;
+    ttlSeconds?: number | undefined;
+    fetchImpl?: typeof fetch | undefined;
+    /** Pre-seeded payload — useful for offline scenarios and tests. */
+    seed?: ModelsDevPayload | undefined;
+    /**
+     * Maximum age in seconds for stale cache fallback when network fails.
+     * Defaults to 7 days. Set to `Infinity` for full offline resilience
+     * (risk: deprecated models, wrong pricing). Set to `0` to disable
+     * stale fallback entirely.
+     */
+    maxStaleAgeSeconds?: number | undefined;
+    /**
+     * Timeout in milliseconds for the models.dev network fetch. When exceeded,
+     * the fetch is aborted and cache/stale fallback is used instead.
+     * Defaults to 15 seconds. Set to `0` to disable (infinite wait).
+     */
+    refreshTimeoutMs?: number | undefined;
+    /**
+     * Curated override payload deep-merged ON TOP of the models.dev base via
+     * `mergeModelsPayload` — adds providers/models the base lacks and overrides
+     * fields it gets wrong. Resolution order (first non-empty wins): this
+     * in-memory `overlay` → `overlayUrl` (fetched, cached) → `overlayFile`
+     * (bundled, read from disk). A missing/broken overlay degrades to `{}` and
+     * never throws, so the base alone still works.
+     */
+    overlay?: ModelsDevPayload | undefined;
+    /** GitHub-raw (or any) URL serving the curated overlay `providers.json`. */
+    overlayUrl?: string | undefined;
+    /** Path to the bundled overlay `providers.json` (offline floor). */
+    overlayFile?: string | undefined;
+    /** Cache file for the fetched `overlayUrl`. Defaults next to `cacheFile`. */
+    overlayCacheFile?: string | undefined;
+}
+export declare function classifyFamily(npm: string | undefined): WireFamily;
+export declare class DefaultModelsRegistry implements ModelsRegistry {
+    /** Merged (base + overlay) payload — what every reader sees. */
+    private payload?;
+    /** Memoised overlay payload (in-memory / fetched / file). */
+    private overlayPayload?;
+    /**
+     * Extra providers injected at runtime via `mergeOverlay()` — e.g. an
+     * openai-compatible server (omniroute, LiteLLM, …) auto-discovered from its
+     * `/v1/models` endpoint at boot. Applied LAST (on top of base + curated
+     * overlay) and re-applied across `refresh()` so the discovered catalog
+     * survives a models.dev refetch.
+     */
+    private extraOverlay?;
+    private fetchedAt?;
+    private readonly cacheFile;
+    private readonly url;
+    private readonly ttlMs;
+    private readonly fetchImpl;
+    private readonly seed?;
+    private readonly maxStaleAgeMs;
+    private readonly refreshTimeoutMs;
+    private readonly overlay?;
+    private readonly overlayUrl?;
+    private readonly overlayFile?;
+    private readonly overlayCacheFile?;
+    constructor(opts: DefaultModelsRegistryOptions);
+    load(opts?: {
+        force?: boolean | undefined;
+    }): Promise<ModelsDevPayload>;
+    /**
+     * Merge an additional provider payload on top of the resolved catalog. Used
+     * for runtime-discovered openai-compatible providers. Remembered so it is
+     * re-applied across `refresh()`. A no-op for an empty payload.
+     */
+    mergeOverlay(payload: ModelsDevPayload): void;
+    private withExtraOverlay;
+    /**
+     * Load the models.dev base payload: fresh cache → network → stale cache.
+     * On total failure, degrade to `{}` (so a non-empty overlay still drives
+     * the catalog) rather than throwing — unless there's no curated overlay to
+     * fall back on, in which case the original error propagates so pure-
+     * models.dev setups still surface the problem.
+     */
+    private loadBase;
+    /** Fetch + cache the models.dev base. Throws on failure (used by `refresh`). */
+    private refreshBase;
+    /**
+     * Resolve the curated overlay, memoised. Order: in-memory `overlay` →
+     * fetched `overlayUrl` (cached, same TTL/stale rules) → `overlayFile` on
+     * disk. Never throws — a missing/broken overlay yields `{}`.
+     */
+    private loadOverlay;
+    private loadOverlayFromUrl;
+    private readOverlayFile;
+    refresh(): Promise<ModelsDevPayload>;
+    listProviders(): Promise<ResolvedProvider[]>;
+    getProvider(id: string): Promise<ResolvedProvider | undefined>;
+    getModel(providerId: string, modelId: string): Promise<ResolvedModel | undefined>;
+    suggestModel(providerId: string): Promise<string | undefined>;
+    ageSeconds(): Promise<number>;
+    private resolveProvider;
+    private isFresh;
+    private isWithinMaxStaleAge;
+    private readCacheAt;
+    /** Used by `wstack models refresh` to expose where the cache lives. */
+    cacheLocation(): string;
+}
+//# sourceMappingURL=models-registry.d.ts.map

package/dist/models/models-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models-registry.d.ts","sourceRoot":"","sources":["../../src/models/models-registry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAEhB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,UAAU,EACX,MAAM,6BAA6B,CAAC;AAkBrC,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,KAAK,GAAG,SAAS,CAAC;IACrC,mEAAmE;IACnE,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpC;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACvC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAmCD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAGlE;AAOD,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAC,CAA+B;IAC/C,6DAA6D;IAC7D,OAAO,CAAC,cAAc,CAAC,CAA+B;IACtD;;;;;;OAMG;IACH,OAAO,CAAC,YAAY,CAAC,CAA+B;IACpD,OAAO,CAAC,SAAS,CAAC,CAAmB;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAqB;IAEvD,YAAY,IAAI,EAAE,4BAA4B,EAkB7C;IAEK,IAAI,CAAC,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAehF;IAED;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAM5C;IAED,OAAO,CAAC,gBAAgB;IAIxB;;;;;;OAMG;YACW,QAAQ;IAuCtB,gFAAgF;YAClE,WAAW;IAwCzB;;;;OAIG;YACW,WAAW;YAiBX,kBAAkB;YA4ClB,eAAe;IAUvB,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAOzC;IAEK,aAAa,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAGjD;IAEK,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAInE;IAEK,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAmBtF;IAEK,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CASlE;IAEK,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAOlC;IAED,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,mBAAmB;YAIb,WAAW;IASzB,uEAAuE;IACvE,aAAa,IAAI,MAAM,CAEtB;CACF"}

package/dist/models/provider-model-resolve.d.ts

@@ -0,0 +1,69 @@
+import type { ModelsDevModel, ResolvedProvider } from '../types/models-registry.js';
+/**
+ * A model descriptor shaped for the WebUI `provider.models` message. All
+ * metadata fields are optional because OAuth / subscription providers that
+ * models.dev doesn't list contribute only a bare id.
+ */
+export interface ProviderModelDescriptor {
+    id: string;
+    name: string;
+    /** One-line capability blurb, when known (e.g. the Codex subscription models). */
+    description?: string | undefined;
+    releaseDate?: string | undefined;
+    contextWindow?: number | undefined;
+    inputCost?: number | undefined;
+    outputCost?: number | undefined;
+    capabilities: string[];
+}
+/** Map a models.dev catalog model to the WebUI descriptor shape. */
+export declare function describeCatalogModel(m: ModelsDevModel): ProviderModelDescriptor;
+/**
+ * Resolve the model list to offer for a provider, merging a saved-config
+ * allowlist with optional models.dev catalog metadata.
+ *
+ * The result is a **union** of all available sources — the saved allowlist
+ * (if any), the catalog models (base + curated overlay), the sibling
+ * catalog models (e.g. `openai` for `openai-codex`), and the offline Codex
+ * catalog (when `providerHint === 'openai-codex'`). Each source is
+ * deduplicated by model id; the saved allowlist ids appear first so the
+ * user's explicit preferences float to the top.
+ *
+ * Priority:
+ *  1. The saved `models` allowlist (if non-empty) — enriched with catalog
+ *     metadata or the offline Codex catalog name+description when a same-id
+ *     entry exists. These ids always come first in the result.
+ *  2. Catalog models (base + layered `providers.json` overlay) not already
+ *     in the saved list — this ensures the curated overlay is *never* hidden
+ *     by a stale saved model list. An empty `[]` saved list (not `undefined`)
+ *     still shows the full catalog.
+ *  3. Sibling catalog models (when `siblingCatalog` is provided) — e.g. the
+ *     `openai` models from models.dev for `openai-codex` subscribers. Merged
+ *     only when the sibling is a different provider from the primary catalog.
+ *  4. Offline Codex catalog (`CODEX_MODELS`) for `openai-codex` — fallback
+ *     when both saved list and catalog are empty/unavailable. This guarantees
+ *     ChatGPT sign-in users always see the canonical model list even fully
+ *     offline.
+ *  5. Otherwise an empty list — *never* an error. A provider the user saved
+ *     that is neither in the catalog, the curated overlay, nor the offline
+ *     Codex catalog simply has no suggestions yet; callers must not raise a
+ *     toast for that case (doing so produced the "not found in catalog"
+ *     notification flood when the WebUI model switcher lazy-loaded every
+ *     saved provider).
+ */
+export declare function resolveProviderModelList(savedModels: string[] | undefined, catalog: ResolvedProvider | undefined, 
+/**
+ * Provider id / wire family the list is being resolved for. Lets the
+ * resolver fall back to a known offline catalog (currently the ChatGPT
+ * `openai-codex` models) when the saved allowlist is empty AND the
+ * models.dev catalog is unavailable — so deleting the models from config
+ * never leaves the provider showing zero models.
+ */
+providerHint?: string | undefined, 
+/**
+ * Optional sibling catalog — e.g. the `openai` catalog when resolving
+ * `openai-codex` models. Merged alongside the primary `catalog` so users
+ * of subscription/OAuth providers also see the wire-family models they
+ * may have access to (OpenAI models for ChatGPT Codex subscribers).
+ */
+siblingCatalog?: ResolvedProvider | undefined): ProviderModelDescriptor[];
+//# sourceMappingURL=provider-model-resolve.d.ts.map

package/dist/models/provider-model-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-model-resolve.d.ts","sourceRoot":"","sources":["../../src/models/provider-model-resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGpF;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,cAAc,GAAG,uBAAuB,CAgB/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,EACjC,OAAO,EAAE,gBAAgB,GAAG,SAAS;AACrC;;;;;;GAMG;AACH,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS;AACjC;;;;;GAKG;AACH,cAAc,CAAC,EAAE,gBAAgB,GAAG,SAAS,GAC5C,uBAAuB,EAAE,CA4D3B"}

package/dist/observability/event-bridge.d.ts

@@ -0,0 +1,10 @@
+import type { EventBus } from '../kernel/events.js';
+import type { MetricsSink } from '../types/observability.js';
+/**
+ * Subscribes a MetricsSink to the EventBus. Returns an unsubscribe function
+ * that detaches all listeners. This is the single integration point between
+ * the agent's event stream and the observability layer — no metric calls
+ * leak into core call sites.
+ */
+export declare function wireMetricsToEvents(events: EventBus, sink: MetricsSink): () => void;
+//# sourceMappingURL=event-bridge.d.ts.map

package/dist/observability/event-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bridge.d.ts","sourceRoot":"","sources":["../../src/observability/event-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,IAAI,CA0DnF"}

package/dist/observability/health.d.ts

@@ -0,0 +1,18 @@
+import type { AggregateHealth, HealthCheck, HealthRegistry } from '../types/observability.js';
+/**
+ * Aggregates registered health checks. Worst status wins — one unhealthy check
+ * makes the whole system unhealthy. Use timeouts so a slow probe can't stall
+ * the response.
+ */
+export declare class DefaultHealthRegistry implements HealthRegistry {
+    private checks;
+    private readonly timeoutMs;
+    constructor(opts?: {
+        timeoutMs?: number | undefined;
+    });
+    register(check: HealthCheck): void;
+    unregister(name: string): void;
+    run(): Promise<AggregateHealth>;
+    private runOne;
+}
+//# sourceMappingURL=health.d.ts.map

package/dist/observability/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/observability/health.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EAEX,cAAc,EAEf,MAAM,2BAA2B,CAAC;AAQnC;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAO,EAExD;IAED,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAEjC;IAED,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE7B;IAEK,GAAG,IAAI,OAAO,CAAC,eAAe,CAAC,CAcpC;YAEa,MAAM;CAgBrB"}