ai-runtime-engine 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Public entry point for ai-runtime.
+ *
+ *   import { AI } from 'ai-runtime-engine';
+ *   const ai = new AI(config).registerProvider(myProvider);
+ *   const result = await ai.run({ task: 'generate-playwright-tests', input: ticket });
+ */
+export { AI } from './plugin/ai.js';
+export type { AIOptions, ProviderInfo } from './plugin/ai.js';
+export type { AIProvider } from './providers/provider.js';
+export { MockProvider } from './providers/mock/mockProvider.js';
+export type { MockProviderConfig } from './providers/mock/mockProvider.js';
+export { makeModel } from './providers/mock/scenarios.js';
+export type { MakeModelInput, MockBehavior } from './providers/mock/scenarios.js';
+export { HttpProvider } from './providers/httpProvider.js';
+export type { HttpProviderConfig } from './providers/httpProvider.js';
+export { buildProvider } from './providers/factory.js';
+export type { BuildOptions } from './providers/factory.js';
+export type { FetchLike } from './providers/httpClient.js';
+export { PROVIDER_DEFAULTS } from './config/providerDefaults.js';
+export { resolveModelMetadata } from './discovery/modelCatalog.js';
+export { registerWire } from './providers/wire/registry.js';
+export type { WireModule, WireShape } from './providers/wire/types.js';
+export { AIError, isRetryable, statusToCategory, toAIError } from './core/fallback/errors.js';
+export { capabilitySatisfies, emptyProfile, getCapability, mergeProfiles, profileFromDeclared, rankOf, } from './core/capabilities/evidence.js';
+export { AGENT_CAPABILITIES, INPUT_MODALITIES, INTELLIGENCE_SKILLS, OUTPUT_MODALITIES, } from './core/capabilities/taxonomy.js';
+export { BUILTIN_TASKS } from './core/registry/builtinTasks.js';
+export { DEFAULT_WEIGHTS, resolveConfig } from './config/defaults.js';
+export type { ResolvedConfig } from './config/defaults.js';
+export { loadConfig, findConfigFile } from './config/load.js';
+export { parseConfig } from './config/schema.js';
+export { HealthMonitor } from './core/health/monitor.js';
+export { isRoutableState } from './core/health/health.js';
+export { validate } from './core/validation/validator.js';
+export { PerformanceStore } from './learning/performanceStore.js';
+export type { ObservedPerf } from './learning/performanceStore.js';
+export { CapabilityOverlay } from './core/capabilities/overlay.js';
+export { BudgetTracker } from './core/policies/budget.js';
+export { probeModel, ALL_PROBES } from './probing/probe.js';
+export type { ProbeName, ProbeReport, ProbeResult } from './probing/probe.js';
+export { runVerification } from './verification/verify.js';
+export type { VerificationReport } from './types.js';
+export { analyzeOpenApi, analyzeOpenApiFile } from './discovery/openapi.js';
+export type { OpenApiAnalysis } from './discovery/openapi.js';
+export { benchmark } from './benchmark/benchmark.js';
+export type { BenchResult, BenchTaskSpec } from './benchmark/benchmark.js';
+export { generateProviderConfig, generateProviderConfigFromFile } from './generation/generateAdapter.js';
+export type { GenerateOptions } from './generation/generateAdapter.js';
+export { McpRegistry, StaticMcpSource } from './mcp/mcp.js';
+export type { McpToolSource } from './mcp/mcp.js';
+export { setCredentialResolver, Credential } from './security/credentials.js';
+export type { CredentialResolver } from './security/credentials.js';
+export { CallbackSink, MemorySink, MultiSink, NullSink } from './telemetry/telemetry.js';
+export type { TelemetrySink } from './telemetry/telemetry.js';
+export { MARKETPLACE, listPresets, findPreset, presetToConfig } from './marketplace/presets.js';
+export type { ProviderPreset } from './marketplace/presets.js';
+export { loadRemoteConfig, loadConfigAsync } from './config/load.js';
+export { Runtime } from './runtime/runtime.js';
+export type { RuntimeOptions } from './runtime/runtime.js';
+export { RUNTIME_MODES } from './runtime/types.js';
+export type { RuntimeMode, ExecutableMode, ModeSource, ModeResolution, RuntimeConfig, RuntimeSettings, RuntimeRunInput, RuntimeResult, RuntimeStatus, Clarification, ArtifactRef } from './runtime/types.js';
+export type { RuntimeContext } from './runtime/context.js';
+export { resolvePolicy, defaultAutonomyForMode } from './runtime/policy.js';
+export type { ExecutionPolicy, PermissionPolicy, Autonomy, ApprovalLevel, PolicyOverrides } from './runtime/policy.js';
+export { parseRuntimeConfig, loadRuntimeConfig, findRuntimeConfigFile } from './runtime/config.js';
+export { HeuristicIntentClassifier } from './runtime/intent/classifier.js';
+export type { IntentClassifier, IntentClassification, IntentInput } from './runtime/intent/classifier.js';
+export { detectWorkspace, summarizeWorkspace } from './runtime/workspace/workspace.js';
+export type { WorkspaceInfo } from './runtime/workspace/workspace.js';
+export { MODE_AVAILABILITY, IMPLEMENTED_MODES } from './runtime/modes/availability.js';
+export { CHAT_TASK } from './runtime/modes/chat.js';
+export { RuntimeEmitter, MemoryEventSink, CallbackEventSink } from './runtime/events.js';
+export type { RuntimeEvent, RuntimeEventInput, RuntimeEventSink } from './runtime/events.js';
+export type { RuntimeHost, ApprovalProvider, ApprovalRequest } from './runtime/host.js';
+export { deriveAccessState, buildProviderViews, ProviderViewCache } from './runtime/providerView.js';
+export type { AccessState, ProviderView, ModelView, ProviderViewSource } from './runtime/providerView.js';
+export { RuntimeStore, STORE_VERSION } from './store/store.js';
+export type { RuntimeStoreOptions, StorePaths } from './store/store.js';
+export { FileArea, NullArea } from './store/area.js';
+export type { Area, IntegrityIssue } from './store/area.js';
+export { resolveHome, projectId, repositoryId, findRepoRoot } from './store/paths.js';
+export type { StoreScope } from './store/paths.js';
+export { ConversationStore } from './conversations/conversations.js';
+export type { ConversationTurn, ConversationMeta, TurnRole } from './conversations/conversations.js';
+export { MemoryStore } from './memory/memory.js';
+export type { MemoryRecord, MemoryScope, MemorySource, RememberInput, SearchOptions, DeletionAudit, EmbeddingProvider } from './memory/memory.js';
+export { classifyMemory } from './memory/classifier.js';
+export type { MemoryCandidate } from './memory/classifier.js';
+export { bm25Search, tokenize } from './memory/bm25.js';
+export type { MemoryTrace } from './runtime/types.js';
+export { compileContext } from './context/compiler.js';
+export type { ContextBlock, CompiledBlock, CompiledContext, CompileMetrics, CompileOptions, ContextValidation, RetentionLevel } from './context/compiler.js';
+export { TokenEstimator, estimateTokens } from './context/tokens.js';
+export { resolveContextBudget, DEFAULT_CONTEXT_TOKENS } from './context/budget.js';
+export type { ContextBudgetInputs } from './context/budget.js';
+export type { ContextReport } from './runtime/types.js';
+export { ToolRegistry } from './tools/registry.js';
+export { authorize, denied } from './tools/tool.js';
+export type { Tool, ToolContext, ToolResult, ToolErrorCode } from './tools/tool.js';
+export { resolvePermissions } from './tools/permissions.js';
+export type { ResolvedPermissions } from './tools/permissions.js';
+export { resolveInJail, JailError } from './tools/jail.js';
+export { defaultRunner, safeEnv } from './tools/runner.js';
+export type { CommandRunner, RunOptions, RunResult } from './tools/runner.js';
+export { filesystemTool } from './tools/builtins/filesystem.js';
+export { shellTool, createShellTool, isDestructive } from './tools/builtins/shell.js';
+export { gitTool, createGitTool } from './tools/builtins/git.js';
+export { wrapUntrusted, looksLikeInjection } from './tools/untrusted.js';
+export { SkillRegistry } from './skills/registry.js';
+export type { Skill, SkillContext, SkillPlan, SkillResult, SkillValidation } from './skills/skill.js';
+export { fileAnalyzerSkill } from './skills/builtins/fileAnalyzer.js';
+export { repositoryAnalyzerSkill } from './skills/builtins/repositoryAnalyzer.js';
+export { parseManifest, manifestToSkill } from './skills/manifest.js';
+export type { SkillManifest, ManifestStep } from './skills/manifest.js';
+export { discoverSkills, scanRepoForSkills, loadSkillSource, loadSkillPackage, isSkill } from './skills/discovery.js';
+export type { SkillSource, SkillSourceKind, LoadedSource } from './skills/discovery.js';
+export { validatePlan, executionWaves } from './orchestration/plan.js';
+export type { ExecutionPlan, PlanStep, PlanStepStatus, PlanValidation } from './orchestration/plan.js';
+export { generatePlan } from './orchestration/planner.js';
+export type { PlannerInput, PlannerResult } from './orchestration/planner.js';
+export { executePlan } from './orchestration/executor.js';
+export type { ExecuteResult, ExecuteDeps, StepObservation } from './orchestration/executor.js';
+export { orchestrate } from './orchestration/orchestrator.js';
+export type { OrchestrateInput, OrchestrateOutcome, OrchestrationStatus } from './orchestration/orchestrator.js';
+export { ExecutionStore } from './executions/store.js';
+export type { ExecutionStoreOptions, AcquireResult } from './executions/store.js';
+export type { Execution, ExecutionStatus, Lease, Checkpoint, PendingInput } from './executions/execution.js';
+export { RESUMABLE, TERMINAL } from './executions/execution.js';
+export { captureCheckpoint, reconcile, gitHead } from './executions/checkpoint.js';
+export type { Reconciliation } from './executions/checkpoint.js';
+export { ArtifactStore } from './artifacts/artifacts.js';
+export type { PutArtifactInput } from './artifacts/artifacts.js';
+export { compare } from './comparison/comparator.js';
+export type { CompareInput } from './comparison/comparator.js';
+export { analyze, similarity, jaccard, clusterByAgreement, structuredContradictions, missingPoints } from './comparison/analysis.js';
+export { renderComparison } from './comparison/render.js';
+export type { ComparisonPin, ComparisonCandidate, ComparisonResult, ComparisonAnalysis, ComparisonRanking, ComparisonMethod, ComparisonSignal, ComparisonDifference, Contradiction, MissingPoint, AgreementCluster, EvidenceResult, } from './comparison/comparison.js';
+export type { CompareRunOptions } from './runtime/types.js';
+export { LearningStore } from './learning/learningStore.js';
+export type { LearningOutcome, LearnedStat, SkillRef } from './learning/learningStore.js';
+export { classifyFeedback } from './learning/feedback.js';
+export type { FeedbackSignal } from './learning/feedback.js';
+export { resolveRoutingPrefs, withPreferredProviders } from './runtime/routing.js';
+export type { RoutingSources } from './runtime/routing.js';
+export { isExcluded, isPreferred } from './core/router/routingPrefs.js';
+export type { RoutingPreferences } from './types.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,107 @@
+/**
+ * Public entry point for ai-runtime.
+ *
+ *   import { AI } from 'ai-runtime-engine';
+ *   const ai = new AI(config).registerProvider(myProvider);
+ *   const result = await ai.run({ task: 'generate-playwright-tests', input: ticket });
+ */
+// Facade
+export { AI } from './plugin/ai.js';
+export { MockProvider } from './providers/mock/mockProvider.js';
+export { makeModel } from './providers/mock/scenarios.js';
+// Concrete adapter + factory (build providers from config, or construct directly)
+export { HttpProvider } from './providers/httpProvider.js';
+export { buildProvider } from './providers/factory.js';
+export { PROVIDER_DEFAULTS } from './config/providerDefaults.js';
+export { resolveModelMetadata } from './discovery/modelCatalog.js';
+export { registerWire } from './providers/wire/registry.js';
+// Errors
+export { AIError, isRetryable, statusToCategory, toAIError } from './core/fallback/errors.js';
+// Capability helpers (for adapters/catalogs building CapabilityProfiles)
+export { capabilitySatisfies, emptyProfile, getCapability, mergeProfiles, profileFromDeclared, rankOf, } from './core/capabilities/evidence.js';
+export { AGENT_CAPABILITIES, INPUT_MODALITIES, INTELLIGENCE_SKILLS, OUTPUT_MODALITIES, } from './core/capabilities/taxonomy.js';
+// Task defaults
+export { BUILTIN_TASKS } from './core/registry/builtinTasks.js';
+// Config resolution + defaults + loading
+export { DEFAULT_WEIGHTS, resolveConfig } from './config/defaults.js';
+export { loadConfig, findConfigFile } from './config/load.js';
+export { parseConfig } from './config/schema.js';
+// Health monitoring
+export { HealthMonitor } from './core/health/monitor.js';
+export { isRoutableState } from './core/health/health.js';
+// Validation
+export { validate } from './core/validation/validator.js';
+// Learning & verification — learning, probing, verification, OpenAPI discovery, benchmarking
+export { PerformanceStore } from './learning/performanceStore.js';
+export { CapabilityOverlay } from './core/capabilities/overlay.js';
+export { BudgetTracker } from './core/policies/budget.js';
+export { probeModel, ALL_PROBES } from './probing/probe.js';
+export { runVerification } from './verification/verify.js';
+export { analyzeOpenApi, analyzeOpenApiFile } from './discovery/openapi.js';
+export { benchmark } from './benchmark/benchmark.js';
+// Enterprise & extensibility — dynamic adapters, MCP, enterprise credentials, observability, policy, marketplace, remote
+export { generateProviderConfig, generateProviderConfigFromFile } from './generation/generateAdapter.js';
+export { McpRegistry, StaticMcpSource } from './mcp/mcp.js';
+export { setCredentialResolver, Credential } from './security/credentials.js';
+export { CallbackSink, MemorySink, MultiSink, NullSink } from './telemetry/telemetry.js';
+export { MARKETPLACE, listPresets, findPreset, presetToConfig } from './marketplace/presets.js';
+export { loadRemoteConfig, loadConfigAsync } from './config/load.js';
+// ── Runtime (Phase 1) — high-level facade over the router: modes, workspace, policy ──
+export { Runtime } from './runtime/runtime.js';
+export { RUNTIME_MODES } from './runtime/types.js';
+export { resolvePolicy, defaultAutonomyForMode } from './runtime/policy.js';
+export { parseRuntimeConfig, loadRuntimeConfig, findRuntimeConfigFile } from './runtime/config.js';
+export { HeuristicIntentClassifier } from './runtime/intent/classifier.js';
+export { detectWorkspace, summarizeWorkspace } from './runtime/workspace/workspace.js';
+export { MODE_AVAILABILITY, IMPLEMENTED_MODES } from './runtime/modes/availability.js';
+export { CHAT_TASK } from './runtime/modes/chat.js';
+// ── Runtime (Phase 2) — events, host contract, provider views ──
+export { RuntimeEmitter, MemoryEventSink, CallbackEventSink } from './runtime/events.js';
+export { deriveAccessState, buildProviderViews, ProviderViewCache } from './runtime/providerView.js';
+// ── Runtime (Phase 3) — local store, conversations, memory ──
+export { RuntimeStore, STORE_VERSION } from './store/store.js';
+export { FileArea, NullArea } from './store/area.js';
+export { resolveHome, projectId, repositoryId, findRepoRoot } from './store/paths.js';
+export { ConversationStore } from './conversations/conversations.js';
+export { MemoryStore } from './memory/memory.js';
+export { classifyMemory } from './memory/classifier.js';
+export { bm25Search, tokenize } from './memory/bm25.js';
+// ── Runtime (Phase 4) — context compiler + token budgets ──
+export { compileContext } from './context/compiler.js';
+export { TokenEstimator, estimateTokens } from './context/tokens.js';
+export { resolveContextBudget, DEFAULT_CONTEXT_TOKENS } from './context/budget.js';
+// ── Runtime (Phase 5) — tools, permissions, skills, untrusted-data boundary ──
+export { ToolRegistry } from './tools/registry.js';
+export { authorize, denied } from './tools/tool.js';
+export { resolvePermissions } from './tools/permissions.js';
+export { resolveInJail, JailError } from './tools/jail.js';
+export { defaultRunner, safeEnv } from './tools/runner.js';
+export { filesystemTool } from './tools/builtins/filesystem.js';
+export { shellTool, createShellTool, isDestructive } from './tools/builtins/shell.js';
+export { gitTool, createGitTool } from './tools/builtins/git.js';
+export { wrapUntrusted, looksLikeInjection } from './tools/untrusted.js';
+export { SkillRegistry } from './skills/registry.js';
+export { fileAnalyzerSkill } from './skills/builtins/fileAnalyzer.js';
+export { repositoryAnalyzerSkill } from './skills/builtins/repositoryAnalyzer.js';
+// ── Runtime (Phase 11) — local skill discovery (manifests + module skills) ──
+export { parseManifest, manifestToSkill } from './skills/manifest.js';
+export { discoverSkills, scanRepoForSkills, loadSkillSource, loadSkillPackage, isSkill } from './skills/discovery.js';
+// ── Runtime (Phase 6) — planner, executor, orchestrator ──
+export { validatePlan, executionWaves } from './orchestration/plan.js';
+export { generatePlan } from './orchestration/planner.js';
+export { executePlan } from './orchestration/executor.js';
+export { orchestrate } from './orchestration/orchestrator.js';
+// ── Runtime (Phase 7) — persistent executions, artifacts, checkpoints ──
+export { ExecutionStore } from './executions/store.js';
+export { RESUMABLE, TERMINAL } from './executions/execution.js';
+export { captureCheckpoint, reconcile, gitHead } from './executions/checkpoint.js';
+export { ArtifactStore } from './artifacts/artifacts.js';
+// ── Runtime (Phase 8) — comparison engine (fan-out pins → agreement/differences/contradictions/missing) ──
+export { compare } from './comparison/comparator.js';
+export { analyze, similarity, jaccard, clusterByAgreement, structuredContradictions, missingPoints } from './comparison/analysis.js';
+export { renderComparison } from './comparison/render.js';
+// ── Runtime (Phase 9) — learning (skill/workflow/plan) + feedback + exclude/prefer routing ──
+export { LearningStore } from './learning/learningStore.js';
+export { classifyFeedback } from './learning/feedback.js';
+export { resolveRoutingPrefs, withPreferredProviders } from './runtime/routing.js';
+export { isExcluded, isPreferred } from './core/router/routingPrefs.js';

package/dist/learning/feedback.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Deterministic feedback classification — turns free-text user feedback ("that worked", "wrong root
+ * cause") into a positive/negative/neutral signal for the learning store. Negation dominates: if the
+ * text reads negative it is negative even when it also contains a positive word (e.g. "not working"
+ * contains "working"). Ambiguous or unrecognized text is neutral — never guessed.
+ */
+export type FeedbackSignal = 'positive' | 'negative' | 'neutral';
+/** Classify user feedback text. Negation wins over a co-occurring positive token. */
+export declare function classifyFeedback(text: string): FeedbackSignal;

package/dist/learning/feedback.js

@@ -0,0 +1,18 @@
+/**
+ * Deterministic feedback classification — turns free-text user feedback ("that worked", "wrong root
+ * cause") into a positive/negative/neutral signal for the learning store. Negation dominates: if the
+ * text reads negative it is negative even when it also contains a positive word (e.g. "not working"
+ * contains "working"). Ambiguous or unrecognized text is neutral — never guessed.
+ */
+const NEGATIVE = /\b(wrong|incorrect|(did|does|is|was|are|has)(n'?t| not) work\w*|failed|failing|broken|useless|wrong root cause|off base|nope|no good|bad)\b/i;
+/** A positive term negated within a short window — e.g. "not good", "isn't correct", "no longer working". */
+const NEG_POSITIVE = /(?:\b(?:not|never|no longer)\b|n'?t)\s+(?:\w+\s+){0,2}(?:worked|works|working|correct|great|good|fixed|resolved|perfect|nice|helpful|right|useful)\b/i;
+const POSITIVE = /\b(worked|works|working|correct|great|good|fixed|resolved|perfect|nice|helpful|thanks|thank you|spot on|exactly|that'?s right|well done)\b/i;
+/** Classify user feedback text. Negation wins over a co-occurring positive token. */
+export function classifyFeedback(text) {
+    if (NEGATIVE.test(text) || NEG_POSITIVE.test(text))
+        return 'negative';
+    if (POSITIVE.test(text))
+        return 'positive';
+    return 'neutral';
+}

package/dist/learning/learningStore.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Runtime-level learning (spec §34). Records outcomes at several granularities — provider,
+ * provider/model, skill (with EXACT version), workflow (goal pattern → skills), plan (goal pattern →
+ * mode) — behind a minimum-sample gate, and turns strong provider records into SOFT prefer signals.
+ *
+ * Learning only ever produces soft signals: `preferredProviders()` feeds the scorer's userPreference
+ * dimension. It can never re-admit an excluded/incapable/unhealthy provider (those are dropped by the
+ * hard filter) — the safety-rail test proves this. Stats persist in the store's cross-project `learning`
+ * area; a stateless store makes this a no-op.
+ */
+import type { Area } from '../store/area.js';
+import type { FeedbackSignal } from './feedback.js';
+import type { ComparisonSignal } from '../comparison/comparison.js';
+export interface LearnedStat {
+    attempts: number;
+    successes: number;
+    totalLatencyMs: number;
+    positive: number;
+    negative: number;
+}
+export interface SkillRef {
+    id: string;
+    version: string;
+}
+export interface LearningOutcome {
+    /** Coarse goal pattern (e.g. the first few significant tokens) for workflow/plan learning. */
+    goalType?: string;
+    mode?: string;
+    providerId?: string;
+    model?: string;
+    /** Skills used, referenced by EXACT version so a skill update lowers historical confidence. */
+    skills?: SkillRef[];
+    ok: boolean;
+    latencyMs?: number;
+}
+export declare class LearningStore {
+    private readonly area;
+    readonly enabled: boolean;
+    private readonly stats;
+    /** Keys touched by the most recent record/ingest — the target of a bare `feedback(text)`. */
+    private lastKeys;
+    constructor(area: Area);
+    private get;
+    private bump;
+    private keysFor;
+    /** Record one outcome across every granularity it touches. No-op when learning is disabled. */
+    record(o: LearningOutcome): void;
+    /** Ingest Phase-8 comparison signals: each ran candidate is an outcome; an evidence winner is a positive. */
+    ingestComparisonSignals(signals: ComparisonSignal[]): void;
+    /** Apply free-text feedback to the most-recent outcome, or to an explicit provider/model. */
+    feedback(text: string, opts?: {
+        providerId?: string;
+        model?: string;
+    }): FeedbackSignal;
+    /**
+     * Providers whose blended success rate clears `minRate` with at least `minSamples` observations —
+     * surfaced as SOFT prefer signals only. An excluded/incapable provider that appears here is still
+     * dropped by the hard filter; this never forces a selection.
+     */
+    preferredProviders(opts?: {
+        minSamples?: number;
+        minRate?: number;
+    }): string[];
+    snapshot(): Array<{
+        key: string;
+    } & LearnedStat>;
+    private persist;
+}

package/dist/learning/learningStore.js

@@ -0,0 +1,138 @@
+/**
+ * Runtime-level learning (spec §34). Records outcomes at several granularities — provider,
+ * provider/model, skill (with EXACT version), workflow (goal pattern → skills), plan (goal pattern →
+ * mode) — behind a minimum-sample gate, and turns strong provider records into SOFT prefer signals.
+ *
+ * Learning only ever produces soft signals: `preferredProviders()` feeds the scorer's userPreference
+ * dimension. It can never re-admit an excluded/incapable/unhealthy provider (those are dropped by the
+ * hard filter) — the safety-rail test proves this. Stats persist in the store's cross-project `learning`
+ * area; a stateless store makes this a no-op.
+ */
+import { classifyFeedback } from './feedback.js';
+const RECORD_ID = 'stats';
+const MIN_SAMPLES = 3;
+function emptyStat() {
+    return { attempts: 0, successes: 0, totalLatencyMs: 0, positive: 0, negative: 0 };
+}
+export class LearningStore {
+    area;
+    enabled;
+    stats = new Map();
+    /** Keys touched by the most recent record/ingest — the target of a bare `feedback(text)`. */
+    lastKeys = [];
+    constructor(area) {
+        this.area = area;
+        this.enabled = area.enabled;
+        const saved = area.tryReadJson(RECORD_ID);
+        if (saved)
+            for (const [k, v] of Object.entries(saved))
+                this.stats.set(k, { ...emptyStat(), ...v });
+    }
+    get(key) {
+        let s = this.stats.get(key);
+        if (!s) {
+            s = emptyStat();
+            this.stats.set(key, s);
+        }
+        return s;
+    }
+    bump(key, ok, latencyMs = 0) {
+        const s = this.get(key);
+        s.attempts += 1;
+        if (ok)
+            s.successes += 1;
+        s.totalLatencyMs += latencyMs;
+        return s;
+    }
+    keysFor(o) {
+        const keys = [];
+        if (o.providerId)
+            keys.push(`provider:${o.providerId}`);
+        if (o.providerId && o.model)
+            keys.push(`pm:${o.providerId}/${o.model}`);
+        for (const s of o.skills ?? [])
+            keys.push(`skill:${s.id}@${s.version}`);
+        if (o.goalType && o.skills?.length)
+            keys.push(`workflow:${o.goalType}`);
+        if (o.goalType && o.mode)
+            keys.push(`plan:${o.goalType}`);
+        return keys;
+    }
+    /** Record one outcome across every granularity it touches. No-op when learning is disabled. */
+    record(o) {
+        if (!this.enabled)
+            return;
+        const keys = this.keysFor(o);
+        for (const k of keys)
+            this.bump(k, o.ok, o.latencyMs);
+        this.lastKeys = keys;
+        this.persist();
+    }
+    /** Ingest Phase-8 comparison signals: each ran candidate is an outcome; an evidence winner is a positive. */
+    ingestComparisonSignals(signals) {
+        if (!this.enabled)
+            return;
+        const touched = [];
+        for (const s of signals) {
+            if (!s.ran)
+                continue;
+            const keys = [`provider:${s.providerId}`, `pm:${s.providerId}/${s.model}`];
+            for (const k of keys) {
+                const stat = this.bump(k, s.ok, s.latencyMs);
+                if (s.preferred)
+                    stat.positive += 1; // an evidence-established winner is explicit positive signal
+            }
+            touched.push(...keys);
+        }
+        this.lastKeys = touched;
+        this.persist();
+    }
+    /** Apply free-text feedback to the most-recent outcome, or to an explicit provider/model. */
+    feedback(text, opts = {}) {
+        const sig = classifyFeedback(text);
+        if (!this.enabled || sig === 'neutral')
+            return sig;
+        const keys = opts.providerId
+            ? [`provider:${opts.providerId}`, ...(opts.model ? [`pm:${opts.providerId}/${opts.model}`] : [])]
+            : this.lastKeys;
+        for (const k of keys) {
+            const s = this.get(k);
+            if (sig === 'positive')
+                s.positive += 1;
+            else
+                s.negative += 1;
+        }
+        if (keys.length)
+            this.persist();
+        return sig;
+    }
+    /**
+     * Providers whose blended success rate clears `minRate` with at least `minSamples` observations —
+     * surfaced as SOFT prefer signals only. An excluded/incapable provider that appears here is still
+     * dropped by the hard filter; this never forces a selection.
+     */
+    preferredProviders(opts = {}) {
+        const minSamples = opts.minSamples ?? MIN_SAMPLES;
+        const minRate = opts.minRate ?? 0.6;
+        const ranked = [];
+        for (const [k, s] of this.stats) {
+            if (!k.startsWith('provider:'))
+                continue;
+            const signals = s.attempts + s.positive + s.negative;
+            if (signals < minSamples)
+                continue;
+            const rate = (s.successes + s.positive) / signals;
+            if (rate >= minRate)
+                ranked.push({ id: k.slice('provider:'.length), rate });
+        }
+        return ranked.sort((a, b) => b.rate - a.rate).map((x) => x.id);
+    }
+    snapshot() {
+        return [...this.stats.entries()].map(([key, s]) => ({ key, ...s }));
+    }
+    persist() {
+        if (!this.enabled)
+            return;
+        this.area.writeJson(RECORD_ID, Object.fromEntries(this.stats));
+    }
+}

package/dist/learning/performanceStore.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Learning-based routing (PRD §31/§50). Records observed outcomes per (task, provider, model) and
+ * exposes observed success-rate and latency so the scorer can prefer what actually works for a task,
+ * not just what the catalog advertised. It only feeds SOFT scoring dimensions — it can never override
+ * a hard constraint (capability, privacy, cost, disabled). Observations need a minimum sample count
+ * before they are trusted, to avoid over-reacting to noise.
+ */
+export interface ObservedPerf {
+    samples: number;
+    successRate: number;
+    avgLatencyMs: number;
+}
+export declare class PerformanceStore {
+    private readonly stats;
+    private key;
+    record(taskId: string, providerId: string, model: string, ok: boolean, latencyMs: number): void;
+    /** Observed performance for a (task, provider, model), or undefined until MIN_SAMPLES is reached. */
+    forTask(taskId: string, providerId: string, model: string): ObservedPerf | undefined;
+    /** Full snapshot for inspection / persistence. */
+    snapshot(): Array<{
+        taskId: string;
+        providerId: string;
+        model: string;
+    } & ObservedPerf>;
+}
+/** A lookup bound to the current task, handed to the scorer. */
+export type HistoryLookup = (providerId: string, model: string) => ObservedPerf | undefined;

package/dist/marketplace/presets.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Provider marketplace. A curated catalog of ready-to-use provider presets so a user can
+ * add a provider by name instead of hand-writing baseUrl/wireShape/env. Most entries are OpenAI-
+ * compatible and therefore ride the same single HTTP path; the native ones name their wire shape.
+ * A preset resolves to a plain ProviderConfig the operator can drop into their config.
+ */
+import type { PrivacyClass, ProviderConfig, ProviderKind } from '../types.js';
+import type { WireShape } from '../providers/wire/types.js';
+export interface ProviderPreset {
+    id: string;
+    kind: ProviderKind;
+    name: string;
+    description: string;
+    baseUrl?: string;
+    wireShape: WireShape;
+    privacyClass: PrivacyClass;
+    apiKeyEnv?: string;
+    defaultModels: string[];
+}
+export declare const MARKETPLACE: ProviderPreset[];
+export declare function listPresets(): ProviderPreset[];
+export declare function findPreset(id: string): ProviderPreset | undefined;
+/** Resolve a preset (plus optional overrides) into a ProviderConfig ready to register. */
+export declare function presetToConfig(presetId: string, overrides?: Partial<ProviderConfig>): ProviderConfig;

package/dist/marketplace/presets.js

@@ -0,0 +1,52 @@
+/**
+ * Provider marketplace. A curated catalog of ready-to-use provider presets so a user can
+ * add a provider by name instead of hand-writing baseUrl/wireShape/env. Most entries are OpenAI-
+ * compatible and therefore ride the same single HTTP path; the native ones name their wire shape.
+ * A preset resolves to a plain ProviderConfig the operator can drop into their config.
+ */
+import { PROVIDER_DEFAULTS } from '../config/providerDefaults.js';
+const nativePresets = ['gemini', 'groq', 'anthropic', 'ollama'].map((kind) => {
+    const d = PROVIDER_DEFAULTS[kind];
+    return {
+        id: kind,
+        kind,
+        name: d.name,
+        description: `${d.name} via its ${d.wireShape === 'anthropic' ? 'native' : 'OpenAI-compatible'} API`,
+        ...(d.baseUrl ? { baseUrl: d.baseUrl } : {}),
+        wireShape: d.wireShape,
+        privacyClass: d.privacyClass,
+        ...(d.apiKeyEnv ? { apiKeyEnv: d.apiKeyEnv } : {}),
+        defaultModels: d.defaultModels,
+    };
+});
+const communityPresets = [
+    { id: 'openrouter', kind: 'openai-compatible', name: 'OpenRouter', description: 'Aggregator of many models via one OpenAI-compatible endpoint', baseUrl: 'https://openrouter.ai/api/v1', wireShape: 'openai', privacyClass: 'cloud', apiKeyEnv: 'OPENROUTER_API_KEY', defaultModels: [] },
+    { id: 'cerebras', kind: 'openai-compatible', name: 'Cerebras', description: 'Fast inference, OpenAI-compatible', baseUrl: 'https://api.cerebras.ai/v1', wireShape: 'openai', privacyClass: 'cloud', apiKeyEnv: 'CEREBRAS_API_KEY', defaultModels: [] },
+    { id: 'mistral', kind: 'openai-compatible', name: 'Mistral', description: 'Mistral models, OpenAI-compatible', baseUrl: 'https://api.mistral.ai/v1', wireShape: 'openai', privacyClass: 'cloud', apiKeyEnv: 'MISTRAL_API_KEY', defaultModels: [] },
+    { id: 'together', kind: 'openai-compatible', name: 'Together AI', description: 'Open models, OpenAI-compatible', baseUrl: 'https://api.together.xyz/v1', wireShape: 'openai', privacyClass: 'cloud', apiKeyEnv: 'TOGETHER_API_KEY', defaultModels: [] },
+    { id: 'deepseek', kind: 'openai-compatible', name: 'DeepSeek', description: 'DeepSeek models, OpenAI-compatible', baseUrl: 'https://api.deepseek.com/v1', wireShape: 'openai', privacyClass: 'cloud', apiKeyEnv: 'DEEPSEEK_API_KEY', defaultModels: [] },
+];
+export const MARKETPLACE = [...nativePresets, ...communityPresets];
+export function listPresets() {
+    return MARKETPLACE;
+}
+export function findPreset(id) {
+    return MARKETPLACE.find((p) => p.id === id);
+}
+/** Resolve a preset (plus optional overrides) into a ProviderConfig ready to register. */
+export function presetToConfig(presetId, overrides = {}) {
+    const preset = findPreset(presetId);
+    if (!preset)
+        throw new Error(`unknown provider preset '${presetId}'`);
+    const config = {
+        id: preset.id,
+        kind: preset.kind,
+        ...(preset.baseUrl ? { baseUrl: preset.baseUrl } : {}),
+        ...(preset.apiKeyEnv ? { apiKeyEnv: preset.apiKeyEnv } : {}),
+        wireShape: preset.wireShape,
+        privacyClass: preset.privacyClass,
+        ...(preset.defaultModels.length ? { models: preset.defaultModels } : {}),
+        ...overrides,
+    };
+    return config;
+}

package/dist/mcp/mcp.d.ts

@@ -0,0 +1,31 @@
+/**
+ * MCP integration. MCP is treated as an INTEGRATION LAYER for tools/context, NOT as another
+ * model provider. A source exposes tools (as normalized
+ * ToolSpecs) that the router hands to whichever model it selects; the model's tool_calling capability
+ * is what carries them. Sources are pluggable; a StaticMcpSource covers in-process tools and tests.
+ *
+ * This is a minimal, transport-agnostic surface: real stdio/HTTP MCP clients implement `McpToolSource`.
+ */
+import type { ToolSpec } from '../types.js';
+export interface McpToolSource {
+    readonly id: string;
+    listTools(): Promise<ToolSpec[]>;
+    callTool?(name: string, args: unknown): Promise<unknown>;
+}
+export declare class StaticMcpSource implements McpToolSource {
+    readonly id: string;
+    private readonly tools;
+    private readonly handlers;
+    constructor(id: string, tools: ToolSpec[], handlers?: Record<string, (args: unknown) => unknown | Promise<unknown>>);
+    listTools(): Promise<ToolSpec[]>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+}
+export declare class McpRegistry {
+    private readonly sources;
+    register(source: McpToolSource): void;
+    list(): McpToolSource[];
+    /** Aggregate tools across all registered sources. Tool names are namespaced by source to avoid clashes. */
+    allTools(): Promise<ToolSpec[]>;
+    /** Route a (namespaced) tool call to its source. */
+    call(name: string, args: unknown): Promise<unknown>;
+}