ai-runtime-engine 1.1.0

package/dist/runtime/providerView.js

@@ -0,0 +1,105 @@
+/**
+ * Provider/model inspection views for the interactive surfaces. Distinguishes cataloged (documented)
+ * vs accessible (health-derived) vs capability-verified (probed) state, and derives a display-only
+ * `AccessState` from the FROZEN `HealthState` enum (the enum is never modified). A freshness cache keeps
+ * a chatty REPL from re-hitting providers on every command; stale records display as ACCESS_UNKNOWN and
+ * never count as proof of usability.
+ */
+import { systemClock } from '../util/clock.js';
+/** Map a HealthState to an AccessState. Exhaustive over the 12 frozen states (compile-checked). */
+export function deriveAccessState(state) {
+    switch (state) {
+        case 'NOT_CONFIGURED':
+            return 'NOT_CONFIGURED';
+        case 'CONFIGURED':
+            return 'CONFIGURED';
+        case 'AVAILABLE':
+            return 'AVAILABLE';
+        case 'DEGRADED':
+            return 'DEGRADED';
+        case 'RATE_LIMITED':
+            return 'RATE_LIMITED';
+        case 'QUOTA_EXCEEDED':
+            return 'QUOTA_EXCEEDED';
+        case 'AUTH_FAILED':
+            return 'AUTH_FAILED';
+        case 'NETWORK_ERROR':
+            return 'DEGRADED';
+        case 'MODEL_UNAVAILABLE':
+            return 'MODEL_UNAVAILABLE';
+        case 'CAPABILITY_MISMATCH':
+            return 'DEGRADED';
+        case 'DISABLED':
+            return 'CONFIGURED';
+        case 'UNKNOWN':
+            return 'ACCESS_UNKNOWN';
+    }
+}
+const GROUPS = ['input', 'output', 'intelligence', 'agent'];
+function hasVerifiedCapability(profile) {
+    for (const group of GROUPS) {
+        const bucket = profile[group];
+        for (const cap of Object.values(bucket))
+            if (cap.evidence === 'verified')
+                return true;
+    }
+    return profile.context.contextWindow.evidence === 'verified';
+}
+/** Build a joined provider/model view. Live: calls checkHealth() + discover(). */
+export async function buildProviderViews(source, opts) {
+    const ttlMs = opts.ttlMs ?? 60_000;
+    const [health, metas] = await Promise.all([source.checkHealth(), source.discover()]);
+    const healthById = new Map(health.map((h) => [h.providerId, h]));
+    const metaById = new Map(metas.map((m) => [m.id, m]));
+    return source.providers().map((p) => {
+        const h = healthById.get(p.id);
+        const meta = metaById.get(p.id);
+        const models = (meta?.models ?? []).map((m) => ({
+            id: m.id,
+            cataloged: m.source !== 'unknown',
+            verified: hasVerifiedCapability(m.capabilities),
+            ...(m.contextWindow !== undefined ? { contextWindow: m.contextWindow } : {}),
+            ...(m.quality?.tier ? { quality: m.quality.tier } : {}),
+            source: m.source,
+        }));
+        const healthState = h?.state ?? 'UNKNOWN';
+        // A positive checkedAt is a real self-reported timestamp; 0/undefined means "no timestamp" — since
+        // buildProviderViews just called checkHealth() live, treat that as fresh, not ancient.
+        const checkedAt = h?.checkedAt !== undefined && h.checkedAt > 0 ? h.checkedAt : undefined;
+        const ageMs = checkedAt !== undefined ? Math.max(0, opts.now - checkedAt) : undefined;
+        const stale = ageMs !== undefined ? ageMs > ttlMs : false;
+        const accessState = stale ? 'ACCESS_UNKNOWN' : deriveAccessState(healthState);
+        return {
+            id: p.id,
+            name: p.name,
+            kind: p.kind,
+            enabled: p.enabled,
+            accessState,
+            healthState,
+            ...(checkedAt !== undefined ? { checkedAt } : {}),
+            ...(ageMs !== undefined ? { ageMs } : {}),
+            stale,
+            models,
+        };
+    });
+}
+/** Memoizes provider views for a ttl so a long-lived REPL doesn't re-hit providers on every command. */
+export class ProviderViewCache {
+    source;
+    clock;
+    ttlMs;
+    last;
+    constructor(source, options = {}) {
+        this.source = source;
+        this.clock = options.clock ?? systemClock;
+        this.ttlMs = options.ttlMs ?? 60_000;
+    }
+    async get(force = false) {
+        const now = this.clock.now();
+        if (!force && this.last && now - this.last.at < this.ttlMs)
+            return this.last.views;
+        const views = await buildProviderViews(this.source, { now, ttlMs: this.ttlMs });
+        this.last = { at: now, views };
+        return views;
+    }
+}

package/dist/runtime/routing.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Runtime routing-preference resolution. Exclude/prefer come from three sources — env
+ * (`AI_EXCLUDE_PROVIDERS`/`AI_EXCLUDE_MODELS`/`AI_PREFER_PROVIDERS`/`AI_PREFER_MODELS`, comma-separated),
+ * project config (`routing:`), and per-run — and are UNIONed across all three. Union (not replace) is the
+ * safe choice for exclusions: an exclusion set at any level always holds, so a higher-precedence source
+ * can never silently re-admit something a lower one excluded. Preferences union too (harmless, soft).
+ */
+import type { RoutingPreferences } from '../types.js';
+export interface RoutingSources {
+    env?: NodeJS.ProcessEnv;
+    config?: RoutingPreferences;
+    perRun?: RoutingPreferences;
+}
+/** Resolve effective routing prefs by unioning env + config + per-run. Returns undefined when nothing is set. */
+export declare function resolveRoutingPrefs(sources: RoutingSources): RoutingPreferences | undefined;
+/**
+ * Fold learned soft-prefer providers into a routing prefs object. An excluded provider is NEVER added
+ * back (belt-and-suspenders with the filter's hard gate) — so learning can never re-admit an exclusion.
+ */
+export declare function withPreferredProviders(base: RoutingPreferences | undefined, providers: string[]): RoutingPreferences | undefined;
+/**
+ * Union two routing-prefs objects. Exclusions are a FLOOR — the union always keeps every exclusion from
+ * either side, so a lower-priority `override` (e.g. a caller's escape-hatch request.routing) can add
+ * preferences but can NEVER drop a resolved exclusion. Returns undefined when both are empty/undefined.
+ */
+export declare function mergeRouting(base: RoutingPreferences | undefined, override: RoutingPreferences | undefined): RoutingPreferences | undefined;

package/dist/runtime/routing.js

@@ -0,0 +1,65 @@
+/**
+ * Runtime routing-preference resolution. Exclude/prefer come from three sources — env
+ * (`AI_EXCLUDE_PROVIDERS`/`AI_EXCLUDE_MODELS`/`AI_PREFER_PROVIDERS`/`AI_PREFER_MODELS`, comma-separated),
+ * project config (`routing:`), and per-run — and are UNIONed across all three. Union (not replace) is the
+ * safe choice for exclusions: an exclusion set at any level always holds, so a higher-precedence source
+ * can never silently re-admit something a lower one excluded. Preferences union too (harmless, soft).
+ */
+function csv(v) {
+    return (v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+function union(...lists) {
+    const seen = new Set();
+    const out = [];
+    for (const list of lists)
+        for (const x of list ?? [])
+            if (!seen.has(x)) {
+                seen.add(x);
+                out.push(x);
+            }
+    return out;
+}
+/** Resolve effective routing prefs by unioning env + config + per-run. Returns undefined when nothing is set. */
+export function resolveRoutingPrefs(sources) {
+    const env = sources.env ?? {};
+    const excludeProviders = union(csv(env.AI_EXCLUDE_PROVIDERS), sources.config?.excludeProviders, sources.perRun?.excludeProviders);
+    const excludeModels = union(csv(env.AI_EXCLUDE_MODELS), sources.config?.excludeModels, sources.perRun?.excludeModels);
+    const preferProviders = union(csv(env.AI_PREFER_PROVIDERS), sources.config?.preferProviders, sources.perRun?.preferProviders);
+    const preferModels = union(csv(env.AI_PREFER_MODELS), sources.config?.preferModels, sources.perRun?.preferModels);
+    const prefs = {
+        ...(excludeProviders.length ? { excludeProviders } : {}),
+        ...(excludeModels.length ? { excludeModels } : {}),
+        ...(preferProviders.length ? { preferProviders } : {}),
+        ...(preferModels.length ? { preferModels } : {}),
+    };
+    return Object.keys(prefs).length ? prefs : undefined;
+}
+/**
+ * Fold learned soft-prefer providers into a routing prefs object. An excluded provider is NEVER added
+ * back (belt-and-suspenders with the filter's hard gate) — so learning can never re-admit an exclusion.
+ */
+export function withPreferredProviders(base, providers) {
+    const excluded = new Set(base?.excludeProviders ?? []);
+    const add = providers.filter((p) => !excluded.has(p));
+    if (!add.length)
+        return base;
+    return { ...(base ?? {}), preferProviders: union(base?.preferProviders, add) };
+}
+/**
+ * Union two routing-prefs objects. Exclusions are a FLOOR — the union always keeps every exclusion from
+ * either side, so a lower-priority `override` (e.g. a caller's escape-hatch request.routing) can add
+ * preferences but can NEVER drop a resolved exclusion. Returns undefined when both are empty/undefined.
+ */
+export function mergeRouting(base, override) {
+    if (!base)
+        return override;
+    if (!override)
+        return base;
+    const merged = {
+        ...(union(base.excludeProviders, override.excludeProviders).length ? { excludeProviders: union(base.excludeProviders, override.excludeProviders) } : {}),
+        ...(union(base.excludeModels, override.excludeModels).length ? { excludeModels: union(base.excludeModels, override.excludeModels) } : {}),
+        ...(union(base.preferProviders, override.preferProviders).length ? { preferProviders: union(base.preferProviders, override.preferProviders) } : {}),
+        ...(union(base.preferModels, override.preferModels).length ? { preferModels: union(base.preferModels, override.preferModels) } : {}),
+    };
+    return Object.keys(merged).length ? merged : undefined;
+}

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Runtime — the high-level facade OVER the existing `AI` router. It resolves a mode + policy, assembles
+ * a RuntimeContext, executes chat through `AI.run()`, and streams redacted lifecycle events. It never
+ * routes or scores; all model selection stays in the one router. Unimplemented modes degrade to chat.
+ */
+import { AI } from '../plugin/ai.js';
+import type { AIOptions } from '../plugin/ai.js';
+import type { WorkspaceInfo } from './workspace/workspace.js';
+import type { IntentClassifier } from './intent/classifier.js';
+import type { RuntimeEvent } from './events.js';
+import type { RuntimeHost } from './host.js';
+import { RuntimeStore } from '../store/store.js';
+import { ConversationStore } from '../conversations/conversations.js';
+import { MemoryStore } from '../memory/memory.js';
+import type { Tool, ToolResult } from '../tools/tool.js';
+import { resolvePermissions } from '../tools/permissions.js';
+import type { Skill, SkillResult, SkillValidation, SkillPlan } from '../skills/skill.js';
+import type { SkillSource, LoadedSource } from '../skills/discovery.js';
+import { ExecutionStore } from '../executions/store.js';
+import type { Execution } from '../executions/execution.js';
+import { ArtifactStore } from '../artifacts/artifacts.js';
+import type { CompareInput } from '../comparison/comparator.js';
+import type { ComparisonResult } from '../comparison/comparison.js';
+import { LearningStore } from '../learning/learningStore.js';
+import type { FeedbackSignal } from '../learning/feedback.js';
+import type { PermissionPolicy } from './policy.js';
+import type { RuntimeConfig, RuntimeResult, RuntimeRunInput, RuntimeSettings } from './types.js';
+export interface RuntimeOptions {
+    /** Workspace root; defaults to process.cwd(). */
+    workspace?: string;
+    /** Explicit config file path (bypasses discovery). */
+    config?: string;
+    /** Injection passed straight to the inner AI (fetchImpl, clock, env, sinks). */
+    ai?: AIOptions;
+    /** Intent classifier; defaults to the deterministic heuristic one. */
+    classifier?: IntentClassifier;
+    /** Detect workspace traits at load (default true). */
+    detectWorkspace?: boolean;
+    /** Host integration: event sink, credential resolver, workspace, approval (Phase 5). */
+    host?: RuntimeHost;
+    /** 'disabled' turns off all local persistence (conversations, memory) — for CI/tests/ephemeral use. */
+    persistence?: 'enabled' | 'disabled';
+    /** The config file actually resolved (set by Runtime.load; surfaced via `runtime.configFile`). */
+    configFile?: string;
+}
+export declare class Runtime {
+    private readonly _ai;
+    private readonly settingsValue;
+    private readonly classifier;
+    private readonly env;
+    private readonly workspace?;
+    private readonly emitter;
+    private readonly _store;
+    private readonly _memory;
+    private readonly _conversations;
+    private readonly estimator;
+    private readonly _tools;
+    private readonly _skills;
+    private readonly _executions;
+    private readonly _artifacts;
+    private readonly _learning;
+    private readonly workspaceRoot;
+    private readonly configPermissions;
+    private readonly approval?;
+    private readonly _configFile?;
+    private _loadedSkillSources;
+    constructor(config?: RuntimeConfig, options?: RuntimeOptions, workspace?: WorkspaceInfo);
+    /** Build a Runtime from a workspace: load config (.ai-runtime/config.yaml > root fallback), detect workspace. */
+    static load(options?: RuntimeOptions): Promise<Runtime>;
+    /**
+     * Load consented local skills — the conventional `.ai-runtime/skills/` dir plus any `skills.paths` in
+     * config — and register them. Manifests are data; module skills run the user's own code, which is why
+     * only these consented locations auto-load. Off when `skills.autoload: false`. Resilient: a broken
+     * source is recorded (see `skillSources()`), never fatal. Called by `Runtime.load`.
+     */
+    autoloadSkills(): Promise<void>;
+    /** What autoloadSkills loaded (or failed to), for `info`/`doctor`/`skills` reporting. */
+    skillSources(): LoadedSource[];
+    /** Scan the workspace for skill-looking files elsewhere (report only — nothing is loaded). */
+    discoverSkillCandidates(): SkillSource[];
+    /** Explicitly load chosen skill sources (e.g. candidates the user picked) and register them. */
+    loadSkillSources(sources: SkillSource[]): Promise<LoadedSource[]>;
+    /** The config file this runtime resolved (`.ai-runtime/config.yaml` or a fallback), if any. */
+    get configFile(): string | undefined;
+    /** The inner router facade — register providers/tasks/MCP sources here. */
+    get ai(): AI;
+    /** The local runtime store (conversations, memory, indexes, cache). */
+    get store(): RuntimeStore;
+    /** Durable scoped memory. */
+    get memory(): MemoryStore;
+    /** Persistent conversation history. */
+    get conversations(): ConversationStore;
+    private memoryEnabled;
+    /** Durable cross-run learning (provider/skill/workflow/plan outcomes; feeds soft prefer signals). */
+    get learning(): LearningStore;
+    private learningEnabled;
+    /**
+     * Effective exclude/prefer routing for a run: env + project config + per-run (unioned), then learned
+     * soft-prefer folded in — but never re-admitting an excluded provider. Learning stays subordinate to
+     * every hard gate (exclude/privacy/pin/capability/budget), which the router filter enforces.
+     */
+    private effectiveRouting;
+    /** Apply free-text feedback (e.g. "that worked" / "wrong root cause") to the most recent outcome. */
+    feedback(text: string, opts?: {
+        providerId?: string;
+        model?: string;
+    }): FeedbackSignal;
+    /** A coarse goal pattern (first few significant tokens) keying workflow/plan learning. */
+    private goalType;
+    /** Resolve exact-version SkillRefs for the skill steps of a plan (for skill/workflow learning). */
+    private planSkillRefs;
+    /** Register a tool. Chainable. */
+    registerTool(tool: Tool): this;
+    tools(): Tool[];
+    /** Register a skill. Chainable. */
+    registerSkill(skill: Skill): this;
+    /** Skills whose required tools are all registered. */
+    skills(): Skill[];
+    /** The resolved tool permissions for this runtime (config grants over deny-by-default defaults). */
+    permissions(): ReturnType<typeof resolvePermissions>;
+    private toolContext;
+    /** Invoke a registered tool with the runtime's resolved permissions + host approval. */
+    runTool(id: string, input: unknown, overrides?: {
+        permissions?: PermissionPolicy;
+        signal?: AbortSignal;
+    }): Promise<ToolResult>;
+    /** Run a skill end-to-end (plan → execute → validate) with tools bound to the runtime's permissions. */
+    runSkill(id: string, input: unknown, overrides?: {
+        permissions?: PermissionPolicy;
+        signal?: AbortSignal;
+    }): Promise<{
+        plan: SkillPlan;
+        result: SkillResult;
+        validation: SkillValidation;
+    }>;
+    workspaceInfo(): WorkspaceInfo | undefined;
+    settings(): Readonly<RuntimeSettings>;
+    /** Subscribe to runtime lifecycle events; returns an unsubscribe function. */
+    on(listener: (event: RuntimeEvent) => void): () => void;
+    /** Recent runtime events (redacted, metadata only). */
+    events(): RuntimeEvent[];
+    run(input: string | RuntimeRunInput): Promise<RuntimeResult>;
+    /** The persistent execution store and its owner-lease machinery. */
+    get executionStore(): ExecutionStore;
+    /** The artifact store (content owner behind ArtifactRef). */
+    get artifacts(): ArtifactStore;
+    /** Recent persisted executions, newest first. */
+    executions(): Execution[];
+    /** plan/execute/orchestrate/agent/debug: run the orchestrator and persist a resumable Execution. */
+    private runOrchestration;
+    /** Run `fn` while heartbeating the execution lease so a long run never lets the lease expire. */
+    private withHeartbeat;
+    private orchestrateInput;
+    /** Record an EXECUTED orchestration outcome for learning. plan-only, dry-run, and waiting states are
+     * skipped — no skill ran, so there is no success/failure to learn (recording them would teach noise). */
+    private recordOrchestration;
+    private execStatus;
+    private mapOutcome;
+    private resultFromExecution;
+    /**
+     * Compare a task across several models/providers and return a normalized comparison (agreement,
+     * differences, contradictions, missing info, and an EVIDENCE-first ranking). Runs entirely through the
+     * ONE router (`AI.run()` pins) — no second selection engine. Pass a `validate` for evidence-based
+     * ranking (beats any judge), or a `judge` pin for a labeled opinion; with neither it reports only.
+     */
+    compare(input: Omit<CompareInput, 'ai'>): Promise<ComparisonResult>;
+    /** compare mode: fan out over pins (default: every enabled, non-excluded provider) and render. Read-only. */
+    private runCompareMode;
+    /** Default compare pins: one per enabled, non-excluded provider (model left to the provider default). */
+    private defaultComparePins;
+    /**
+     * Resume a persisted execution: acquire its lease, reconcile the workspace, then continue (if
+     * unchanged) or replan (on drift) — never blindly. Answers a pending clarification/approval.
+     */
+    resumeExecution(id: string, opts?: {
+        clarificationAnswer?: string;
+        approve?: boolean;
+        signal?: AbortSignal;
+    }): Promise<RuntimeResult>;
+    private orchestrateRunners;
+    /** Mark an execution paused (it can be resumed later). */
+    pauseExecution(id: string): boolean;
+    /** Cancel an execution (terminal). */
+    cancelExecution(id: string): boolean;
+    /** Assemble the context blocks for a chat run: user system (critical), workspace (high), memory (normal). */
+    private contextBlocks;
+    /** Best-effort estimator calibration from provider-reported input usage (estimates never claim to be exact). */
+    private calibrate;
+    /** Capture an explicit "remember …" fact and retrieve relevant facts for context. Off when disabled. */
+    private applyMemory;
+}