ai-runtime-engine 1.1.0

package/dist/runtime/host.d.ts

@@ -0,0 +1,27 @@
+/**
+ * RuntimeHost — the generic host-integration contract. A host (CLI, IDE, web app, CI, automation)
+ * supplies a workspace, an event sink, and optional credential/approval providers; the Runtime returns
+ * results and streams events. The Runtime never depends on any UI. In Phase 2 `workspace`, `eventSink`,
+ * and `credentialResolver` are wired; `approval` is part of the contract but consumed in Phase 5.
+ */
+import type { CredentialResolver } from '../security/credentials.js';
+import type { RuntimeEventSink } from './events.js';
+/** Requested by the Runtime before a dangerous action; a host decides yes/no. Consumed in Phase 5. */
+export interface ApprovalRequest {
+    action: string;
+    reason?: string;
+    risk?: 'low' | 'medium' | 'high';
+}
+export interface ApprovalProvider {
+    requestApproval(request: ApprovalRequest): Promise<boolean>;
+}
+export interface RuntimeHost {
+    /** Workspace root the Runtime should operate in. */
+    workspace?: string;
+    /** Receives redacted runtime lifecycle events. */
+    eventSink?: RuntimeEventSink;
+    /** Resolves an env-var NAME to a secret value (e.g. an OS keychain). Env still wins when present. */
+    credentialResolver?: CredentialResolver;
+    /** Approves dangerous actions. Wired in Phase 5. */
+    approval?: ApprovalProvider;
+}

package/dist/runtime/host.js

@@ -0,0 +1,7 @@
+/**
+ * RuntimeHost — the generic host-integration contract. A host (CLI, IDE, web app, CI, automation)
+ * supplies a workspace, an event sink, and optional credential/approval providers; the Runtime returns
+ * results and streams events. The Runtime never depends on any UI. In Phase 2 `workspace`, `eventSink`,
+ * and `credentialResolver` are wired; `approval` is part of the contract but consumed in Phase 5.
+ */
+export {};

package/dist/runtime/intent/classifier.d.ts

@@ -0,0 +1,30 @@
+/**
+ * IntentClassifier — the seam. HeuristicIntentClassifier is a deterministic, offline, pure classifier
+ * (no clock/env/fs). `classify` may return a Promise, so a future AI-assisted classifier drops in via
+ * RuntimeOptions.classifier with no API change. Ambiguity (low confidence + competing modes) is
+ * flagged, never guessed away.
+ */
+import type { ExecutableMode } from '../types.js';
+import type { WorkspaceInfo } from '../workspace/workspace.js';
+export interface IntentInput {
+    text: string;
+    hasParts?: boolean;
+    workspace?: WorkspaceInfo;
+}
+export interface IntentClassification {
+    mode: ExecutableMode;
+    confidence: number;
+    reason: string;
+    /** True when confidence is low and ≥2 modes compete — the caller may ask for clarification. */
+    ambiguous: boolean;
+    /** Full per-mode score breakdown (for debugging/tests). */
+    scores: Partial<Record<ExecutableMode, number>>;
+}
+export interface IntentClassifier {
+    classify(input: IntentInput): IntentClassification | Promise<IntentClassification>;
+}
+/** Below this confidence with ≥2 competing modes, the result is flagged ambiguous. */
+export declare const AMBIGUITY_CONFIDENCE = 0.55;
+export declare class HeuristicIntentClassifier implements IntentClassifier {
+    classify(input: IntentInput): IntentClassification;
+}

package/dist/runtime/intent/classifier.js

@@ -0,0 +1,60 @@
+/**
+ * IntentClassifier — the seam. HeuristicIntentClassifier is a deterministic, offline, pure classifier
+ * (no clock/env/fs). `classify` may return a Promise, so a future AI-assisted classifier drops in via
+ * RuntimeOptions.classifier with no API change. Ambiguity (low confidence + competing modes) is
+ * flagged, never guessed away.
+ */
+import { SIGNALS, MODEL_TOKENS, CHAT_BASELINE, TIE_BREAK_PRIORITY } from './signals.js';
+/** Below this confidence with ≥2 competing modes, the result is flagged ambiguous. */
+export const AMBIGUITY_CONFIDENCE = 0.55;
+export class HeuristicIntentClassifier {
+    classify(input) {
+        const text = input.text ?? '';
+        const scores = new Map();
+        const matched = [];
+        const add = (mode, weight, label) => {
+            scores.set(mode, (scores.get(mode) ?? 0) + weight);
+            matched.push(`${mode}("${label}")`);
+        };
+        // chat baseline so it wins when nothing else fires.
+        scores.set('chat', CHAT_BASELINE);
+        // Lexical signals.
+        for (const s of SIGNALS) {
+            if (s.pattern.test(text))
+                add(s.mode, s.weight, s.label);
+        }
+        // Structural cues.
+        if (/```|(^|\n)\s*(Error|Exception|Traceback)\b|\bat .+:\d+:\d+/.test(text))
+            add('debug', 3, 'stacktrace/code');
+        const steps = (text.match(/(^|\n)\s*(?:\d+[.)]|[-*])\s+/g) ?? []).length;
+        if (steps >= 3) {
+            add('orchestrate', 2, 'numbered-steps');
+            add('plan', 1, 'numbered-steps');
+        }
+        if (/\?\s*$/.test(text.trim()))
+            add('chat', 1, 'question-mark');
+        if (text.trim().length > 0 && text.trim().length < 20)
+            add('chat', 1, 'short-input');
+        const modelHits = MODEL_TOKENS.filter((re) => re.test(text)).length;
+        if (modelHits >= 2)
+            add('compare', 2, 'model-pair');
+        // Rank.
+        const ranked = [...scores.entries()].sort((a, b) => {
+            if (b[1] !== a[1])
+                return b[1] - a[1];
+            return TIE_BREAK_PRIORITY.indexOf(b[0]) - TIE_BREAK_PRIORITY.indexOf(a[0]);
+        });
+        const [topMode, topScore] = ranked[0] ?? ['chat', CHAT_BASELINE];
+        const runnerUp = ranked[1]?.[1] ?? 0;
+        const confidence = Math.min(0.95, Math.max(0.4, topScore / (topScore + runnerUp || 1)));
+        const competing = ranked.filter(([, v]) => v > 0).length;
+        const ambiguous = confidence < AMBIGUITY_CONFIDENCE && competing >= 2;
+        const scoreObj = {};
+        for (const [m, v] of scores)
+            scoreObj[m] = v;
+        const reason = matched.length > 0
+            ? `matched ${matched.slice(0, 4).join(', ')}${matched.length > 4 ? ', …' : ''}`
+            : 'no strong mode signals; defaulting to chat';
+        return { mode: topMode, confidence, reason, ambiguous, scores: scoreObj };
+    }
+}

package/dist/runtime/intent/signals.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Deterministic intent signals — the data behind the heuristic classifier. Each rule contributes its
+ * weight to a mode when its pattern matches. Structural cues (code fences, numbered steps, model-name
+ * pairs) are applied separately in classifier.ts. Everything here is pure data.
+ */
+import type { ExecutableMode } from '../types.js';
+export interface Signal {
+    mode: ExecutableMode;
+    pattern: RegExp;
+    weight: number;
+    label: string;
+}
+/** Baseline score chat always carries so it wins when nothing else fires. */
+export declare const CHAT_BASELINE = 0.5;
+/** Deterministic tie-break order (higher index = wins ties). Declared, so it is testable. */
+export declare const TIE_BREAK_PRIORITY: ExecutableMode[];
+export declare const SIGNALS: Signal[];
+/** Known model/provider tokens; ≥2 distinct in one input is a strong compare signal. */
+export declare const MODEL_TOKENS: RegExp[];

package/dist/runtime/intent/signals.js

@@ -0,0 +1,46 @@
+/**
+ * Deterministic intent signals — the data behind the heuristic classifier. Each rule contributes its
+ * weight to a mode when its pattern matches. Structural cues (code fences, numbered steps, model-name
+ * pairs) are applied separately in classifier.ts. Everything here is pure data.
+ */
+/** Baseline score chat always carries so it wins when nothing else fires. */
+export const CHAT_BASELINE = 0.5;
+/** Deterministic tie-break order (higher index = wins ties). Declared, so it is testable. */
+export const TIE_BREAK_PRIORITY = ['chat', 'execute', 'plan', 'agent', 'orchestrate', 'compare', 'debug'];
+export const SIGNALS = [
+    // plan
+    { mode: 'plan', pattern: /\b(plan|roadmap|strateg(y|ies)|outline|break (this|it) down|steps to|approach for|how should (i|we))\b/i, weight: 3, label: 'plan' },
+    // execute
+    { mode: 'execute', pattern: /\b(run|execute|apply|perform|carry out|implement|make (the|this) change)\b/i, weight: 2, label: 'execute' },
+    // orchestrate
+    { mode: 'orchestrate', pattern: /\b(orchestrate|pipeline|workflow|coordinate|end[- ]to[- ]end)\b/i, weight: 3, label: 'orchestrate' },
+    { mode: 'orchestrate', pattern: /\bfix\b.*\b(tests?|failures?|build|suite|errors?)\b/i, weight: 2, label: 'fix-task' },
+    // agent
+    { mode: 'agent', pattern: /\b(autonomously|on my behalf|agentic|multi[- ]step)\b/i, weight: 3, label: 'agent' },
+    { mode: 'agent', pattern: /\bkeep (going|iterating|fixing|trying)\b|\buntil\b.*\b(pass|passes|green|done|works?)\b/i, weight: 3, label: 'until-done' },
+    // compare
+    { mode: 'compare', pattern: /\b(compare|versus|vs\.?|side[- ]by[- ]side|benchmark)\b/i, weight: 3, label: 'compare' },
+    { mode: 'compare', pattern: /\bwhich (model|provider|one|approach)\b|\btry (both|all)\b/i, weight: 2, label: 'which' },
+    // debug
+    { mode: 'debug', pattern: /\b(debug|diagnose|root cause|troubleshoot)\b/i, weight: 3, label: 'debug' },
+    { mode: 'debug', pattern: /\bwhy (is|does|did|are|am|won'?t|can'?t)\b.*\b(fail|failing|error|crash|broken|not work)\b/i, weight: 3, label: 'why-failing' },
+    { mode: 'debug', pattern: /\b(not working|isn'?t working|stack ?trace|traceback)\b/i, weight: 2, label: 'broken' },
+    // chat
+    { mode: 'chat', pattern: /^\s*(what|who|why|how|when|where|explain|tell me|describe|define)\b/i, weight: 1, label: 'question' },
+    { mode: 'chat', pattern: /^\s*(hi|hello|hey|thanks|thank you)\b/i, weight: 1, label: 'greeting' },
+];
+/** Known model/provider tokens; ≥2 distinct in one input is a strong compare signal. */
+export const MODEL_TOKENS = [
+    /\bgpt-?\d/i,
+    /\bo\d(-mini|-preview)?\b/i,
+    /\bclaude\b/i,
+    /\bsonnet\b/i,
+    /\bopus\b/i,
+    /\bhaiku\b/i,
+    /\bgemini\b/i,
+    /\bgroq\b/i,
+    /\bllama\b/i,
+    /\bmistral\b/i,
+    /\bollama\b/i,
+    /\bdeepseek\b/i,
+];

package/dist/runtime/modes/availability.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Which executable modes are actually implemented, and the phase that will implement the rest. An
+ * unimplemented mode degrades to chat with a clear notice (never a hard error for a valid mode name).
+ */
+import type { ExecutableMode } from '../types.js';
+export declare const MODE_AVAILABILITY: Record<ExecutableMode, {
+    implemented: boolean;
+    plannedPhase?: number;
+}>;
+export declare const IMPLEMENTED_MODES: ReadonlySet<ExecutableMode>;
+export declare function isModeImplemented(mode: ExecutableMode): boolean;

package/dist/runtime/modes/availability.js

@@ -0,0 +1,17 @@
+/**
+ * Which executable modes are actually implemented, and the phase that will implement the rest. An
+ * unimplemented mode degrades to chat with a clear notice (never a hard error for a valid mode name).
+ */
+export const MODE_AVAILABILITY = {
+    chat: { implemented: true },
+    plan: { implemented: true },
+    execute: { implemented: true },
+    orchestrate: { implemented: true },
+    debug: { implemented: true },
+    agent: { implemented: true },
+    compare: { implemented: true },
+};
+export const IMPLEMENTED_MODES = new Set(Object.keys(MODE_AVAILABILITY).filter((m) => MODE_AVAILABILITY[m].implemented));
+export function isModeImplemented(mode) {
+    return MODE_AVAILABILITY[mode].implemented;
+}

package/dist/runtime/modes/chat.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The generic `chat` task + the mapping between RuntimeRunInput/RunResult and the router. QA-neutral by
+ * construction: capability keys come straight from the shared taxonomy, no context floor, so tiny
+ * local models qualify. The chat task is registered on the Runtime's AI instance only-if-absent.
+ */
+import type { RoutingPreferences, RunRequest, RunResult, TaskDefinition } from '../../types.js';
+import type { ModeResolution, RuntimeResult, RuntimeRunInput, Clarification } from '../types.js';
+import type { Strategy } from '../../types.js';
+export declare const CHAT_TASK: TaskDefinition;
+/** Extract plain text from a RuntimeRunInput for intent classification. */
+export declare function inputText(input: RuntimeRunInput['input']): string;
+/**
+ * Build the router RunRequest for a chat run. The system prompt is precompiled by the ContextCompiler
+ * (workspace summary + memory facts + user system, under a token budget) — never raw repo contents.
+ */
+export declare function buildChatRequest(input: RuntimeRunInput, strategy?: Strategy, system?: string, routing?: RoutingPreferences): RunRequest;
+/** Map a router RunResult into a RuntimeResult. Routing passes through verbatim; errors keep their category. */
+export declare function toRuntimeResult(run: RunResult, mode: ModeResolution, runId: string, clarification?: Clarification): RuntimeResult;

package/dist/runtime/modes/chat.js

@@ -0,0 +1,67 @@
+/**
+ * The generic `chat` task + the mapping between RuntimeRunInput/RunResult and the router. QA-neutral by
+ * construction: capability keys come straight from the shared taxonomy, no context floor, so tiny
+ * local models qualify. The chat task is registered on the Runtime's AI instance only-if-absent.
+ */
+import { mergeRouting } from '../routing.js';
+export const CHAT_TASK = {
+    id: 'chat',
+    aliases: ['conversation', 'general-chat'],
+    description: 'General conversational response over text input.',
+    required: [
+        { group: 'intelligence', key: 'reasoning' },
+        { group: 'output', key: 'text' },
+    ],
+    preferred: [{ group: 'intelligence', key: 'summarization' }],
+    output: { format: 'text' },
+    defaultStrategy: 'best',
+};
+function normalizeInput(input) {
+    return typeof input === 'string' ? { text: input } : input;
+}
+/** Extract plain text from a RuntimeRunInput for intent classification. */
+export function inputText(input) {
+    if (typeof input === 'string')
+        return input;
+    if (input.text)
+        return input.text;
+    return (input.parts ?? []).filter((p) => p.kind === 'text').map((p) => p.text).join('\n');
+}
+/**
+ * Build the router RunRequest for a chat run. The system prompt is precompiled by the ContextCompiler
+ * (workspace summary + memory facts + user system, under a token budget) — never raw repo contents.
+ */
+export function buildChatRequest(input, strategy, system, routing) {
+    const req = {
+        task: 'chat',
+        input: normalizeInput(input.input),
+        ...(system ? { system } : {}),
+        ...(strategy ? { strategy } : {}),
+        ...(input.sensitivity ? { sensitivity: input.sensitivity } : {}),
+        ...(input.output ? { output: input.output } : {}),
+        ...(input.request ?? {}), // escape hatch: may add preferences, but must NOT drop a resolved exclusion
+    };
+    // Resolved routing is a FLOOR for exclusions — union it over any escape-hatch request.routing so a
+    // caller can add prefer but can never silently re-admit an env/config exclusion.
+    const merged = mergeRouting(routing, req.routing);
+    if (merged)
+        req.routing = merged;
+    else
+        delete req.routing;
+    return req;
+}
+/** Map a router RunResult into a RuntimeResult. Routing passes through verbatim; errors keep their category. */
+export function toRuntimeResult(run, mode, runId, clarification) {
+    const response = run.response ? { ...(run.response.text !== undefined ? { text: run.response.text } : {}), ...(run.response.json !== undefined ? { json: run.response.json } : {}) } : undefined;
+    return {
+        ok: run.ok,
+        runId,
+        mode,
+        status: clarification ? 'waiting_for_clarification' : 'completed',
+        ...(response ? { response } : {}),
+        ...(clarification ? { clarification } : {}),
+        routing: run.routing,
+        ...(run.error ? { error: run.error } : {}),
+        artifacts: [],
+    };
+}

package/dist/runtime/modes/modeResolver.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Mode + strategy precedence. Explicit per-run > project config > env > automatic detection. An
+ * explicit mode is NEVER overridden by detection. Invalid env values are silently ignored (env must
+ * never break a run). Unimplemented modes degrade to chat with a notice.
+ */
+import type { ExecutableMode, ModeResolution, RuntimeMode } from '../types.js';
+import type { Strategy } from '../../types.js';
+import type { IntentClassification, IntentClassifier, IntentInput } from '../intent/classifier.js';
+export interface ResolveModeInput {
+    /** RuntimeRunInput.mode (may be undefined or 'auto'). */
+    explicit?: RuntimeMode;
+    /** RuntimeSettings.defaultMode (may be undefined or 'auto'). */
+    configDefault?: RuntimeMode;
+    /** Raw AI_DEFAULT_MODE value from the injected env (validated; invalid ignored). */
+    envDefault?: string;
+    intent: IntentInput;
+    classifier: IntentClassifier;
+    /** Override mode availability (defaults to MODE_AVAILABILITY). Lets the degrade path stay testable. */
+    availability?: Partial<Record<ExecutableMode, {
+        implemented: boolean;
+        plannedPhase?: number;
+    }>>;
+}
+export interface ModeResolutionResult {
+    resolution: ModeResolution;
+    /** Present only when the mode came from auto detection — lets the caller act on ambiguity. */
+    classification?: IntentClassification;
+}
+/**
+ * Resolve the mode for a run. Throws AIError(CONFIG) only for an INVALID mode string passed
+ * programmatically (a valid-but-unimplemented mode degrades, it does not throw).
+ */
+export declare function resolveMode(input: ResolveModeInput): Promise<ModeResolutionResult>;
+export interface ResolveStrategyInput {
+    explicit?: Strategy;
+    configDefault?: Strategy;
+    envDefault?: string;
+}
+/**
+ * Resolve the strategy to pass through. Precedence: per-run > config > env. Returns undefined when
+ * nothing is set, so the router's own chain (task default → router config → 'best') stays intact.
+ */
+export declare function resolveStrategy(input: ResolveStrategyInput): Strategy | undefined;

package/dist/runtime/modes/modeResolver.js

@@ -0,0 +1,78 @@
+/**
+ * Mode + strategy precedence. Explicit per-run > project config > env > automatic detection. An
+ * explicit mode is NEVER overridden by detection. Invalid env values are silently ignored (env must
+ * never break a run). Unimplemented modes degrade to chat with a notice.
+ */
+import { AIError } from '../../core/fallback/errors.js';
+import { RUNTIME_MODES } from '../types.js';
+import { STRATEGIES } from '../../config/schema.js';
+import { MODE_AVAILABILITY } from './availability.js';
+function isRuntimeMode(v) {
+    return typeof v === 'string' && RUNTIME_MODES.includes(v);
+}
+function isStrategy(v) {
+    return typeof v === 'string' && STRATEGIES.includes(v);
+}
+/**
+ * Resolve the mode for a run. Throws AIError(CONFIG) only for an INVALID mode string passed
+ * programmatically (a valid-but-unimplemented mode degrades, it does not throw).
+ */
+export async function resolveMode(input) {
+    // An explicit but invalid mode string (reachable only from JS callers) is a config error.
+    if (input.explicit !== undefined && !isRuntimeMode(input.explicit)) {
+        throw new AIError(`invalid mode '${String(input.explicit)}'; valid modes: ${RUNTIME_MODES.join(', ')}`, { category: 'CONFIG' });
+    }
+    const requested = input.explicit ?? 'auto';
+    let selected;
+    let source;
+    let confidence;
+    let reason;
+    let classification;
+    if (input.explicit !== undefined && input.explicit !== 'auto') {
+        selected = input.explicit;
+        source = 'explicit';
+        confidence = 1;
+        reason = 'mode explicitly requested';
+    }
+    else if (input.configDefault !== undefined && input.configDefault !== 'auto') {
+        selected = input.configDefault;
+        source = 'config';
+        confidence = 1;
+        reason = 'project default mode';
+    }
+    else if (isRuntimeMode(input.envDefault) && input.envDefault !== 'auto') {
+        selected = input.envDefault;
+        source = 'env';
+        confidence = 1;
+        reason = 'AI_DEFAULT_MODE';
+    }
+    else {
+        classification = await input.classifier.classify(input.intent);
+        selected = classification.mode;
+        source = 'auto';
+        confidence = classification.confidence;
+        reason = classification.ambiguous ? `${classification.reason} (ambiguous)` : classification.reason;
+    }
+    // Availability: degrade unimplemented modes to chat with a notice.
+    const availability = { ...MODE_AVAILABILITY, ...input.availability };
+    let executed = selected;
+    if (!availability[selected].implemented) {
+        const phase = availability[selected].plannedPhase;
+        executed = 'chat';
+        reason = `${reason}; '${selected}' is not yet implemented${phase ? ` (planned for Phase ${phase})` : ''} — executed as chat`;
+    }
+    return { resolution: { requested, selected, executed, confidence, reason, source }, ...(classification ? { classification } : {}) };
+}
+/**
+ * Resolve the strategy to pass through. Precedence: per-run > config > env. Returns undefined when
+ * nothing is set, so the router's own chain (task default → router config → 'best') stays intact.
+ */
+export function resolveStrategy(input) {
+    if (input.explicit !== undefined)
+        return input.explicit;
+    if (input.configDefault !== undefined)
+        return input.configDefault;
+    if (isStrategy(input.envDefault))
+        return input.envDefault;
+    return undefined;
+}

package/dist/runtime/policy.d.ts

@@ -0,0 +1,72 @@
+/**
+ * ExecutionPolicy — the SINGLE authority for autonomy, approval, dry-run, execution limits, and
+ * permissions. Every later layer (planner, orchestrator, executor, agent, tools, approval system,
+ * dry-run, budgets) READS the resolved policy; none re-derives it. In Phase 1 only the shape and
+ * resolution exist — enforcement is trivial (chat only) — but there is exactly one definition.
+ */
+import type { ExecutableMode, RuntimeSettings } from './types.js';
+/** How much independent action is permitted. Distinct from mode (what kind of work). */
+export type Autonomy = 'chat' | 'assisted' | 'autonomous';
+/** When human approval is required. */
+export type ApprovalLevel = 'none' | 'before-plan' | 'before-execution' | 'per-dangerous-action';
+/**
+ * Permission posture (config-facing; all optional, deny-by-default for write/exec). The concrete,
+ * fully-defaulted form tools consume is `ResolvedPermissions` (src/tools/permissions.ts). Phase 1
+ * shipped the flat `fsWrite`/`shell`/`gitWrite` fields; Phase 5 adds the structured allowlist model.
+ * Both are honored by `resolvePermissions` (structured fields win when set).
+ */
+export interface PermissionPolicy {
+    /** Allow filesystem reads within the workspace. Default true (reads are jailed to the workspace). */
+    fsRead?: boolean;
+    /** Allow filesystem writes within the workspace. Default false. */
+    fsWrite?: boolean;
+    /** Allow shell execution. Default false. */
+    shell?: boolean;
+    /** Allowlist of shell commands (argv[0]); empty means nothing is pre-approved. */
+    shellAllowedCommands?: string[];
+    /** Umbrella for git commit+push (Phase 1 field). `gitCommit`/`gitPush` override it when set. */
+    gitWrite?: boolean;
+    gitCommit?: boolean;
+    gitPush?: boolean;
+    /** Allow tool network access. Default false. */
+    network?: boolean;
+}
+export interface ExecutionPolicy {
+    autonomy: Autonomy;
+    approval: ApprovalLevel;
+    dryRun: boolean;
+    maxIterations?: number;
+    maxCalls?: number;
+    maxCostUsd?: number;
+    maxParallelSteps?: number;
+    permissions: PermissionPolicy;
+}
+/** Per-run overrides a caller may pass (all optional; highest precedence). */
+export interface PolicyOverrides {
+    autonomy?: Autonomy;
+    approval?: ApprovalLevel;
+    dryRun?: boolean;
+    maxIterations?: number;
+    maxCalls?: number;
+    maxCostUsd?: number;
+    maxParallelSteps?: number;
+    permissions?: PermissionPolicy;
+}
+/** Autonomy implied by a mode when nothing more specific is set. */
+export declare function defaultAutonomyForMode(mode: ExecutableMode): Autonomy;
+export interface ResolvePolicyInput {
+    mode: ExecutableMode;
+    overrides?: PolicyOverrides;
+    settings?: RuntimeSettings;
+    /** Raw env values (injected for testability), e.g. AI_MAX_COST_USD / AI_MAX_CALLS. */
+    env?: {
+        maxCostUsd?: number;
+        maxCalls?: number;
+    };
+}
+/**
+ * Resolve the one policy for a run. Precedence: per-run overrides > env > mode-derived defaults.
+ * (Project-config policy fields are folded in through `settings`/`overrides` by the caller as those
+ * config keys land; Phase 1 wires the mode-derived + env + per-run rungs.)
+ */
+export declare function resolvePolicy(input: ResolvePolicyInput): ExecutionPolicy;

package/dist/runtime/policy.js

@@ -0,0 +1,59 @@
+/**
+ * ExecutionPolicy — the SINGLE authority for autonomy, approval, dry-run, execution limits, and
+ * permissions. Every later layer (planner, orchestrator, executor, agent, tools, approval system,
+ * dry-run, budgets) READS the resolved policy; none re-derives it. In Phase 1 only the shape and
+ * resolution exist — enforcement is trivial (chat only) — but there is exactly one definition.
+ */
+/** Autonomy implied by a mode when nothing more specific is set. */
+export function defaultAutonomyForMode(mode) {
+    switch (mode) {
+        case 'chat':
+        case 'plan':
+            return 'chat';
+        case 'agent':
+            return 'autonomous';
+        case 'execute':
+        case 'orchestrate':
+        case 'compare':
+        case 'debug':
+            return 'assisted';
+    }
+}
+/** Approval implied by an autonomy level. */
+function defaultApprovalForAutonomy(autonomy) {
+    switch (autonomy) {
+        case 'chat':
+            return 'none';
+        case 'assisted':
+            return 'before-execution';
+        case 'autonomous':
+            return 'per-dangerous-action';
+    }
+}
+/**
+ * Resolve the one policy for a run. Precedence: per-run overrides > env > mode-derived defaults.
+ * (Project-config policy fields are folded in through `settings`/`overrides` by the caller as those
+ * config keys land; Phase 1 wires the mode-derived + env + per-run rungs.)
+ */
+export function resolvePolicy(input) {
+    const o = input.overrides ?? {};
+    const autonomy = o.autonomy ?? defaultAutonomyForMode(input.mode);
+    const approval = o.approval ?? defaultApprovalForAutonomy(autonomy);
+    const policy = {
+        autonomy,
+        approval,
+        dryRun: o.dryRun ?? false,
+        permissions: o.permissions ?? {},
+    };
+    const maxCostUsd = o.maxCostUsd ?? input.env?.maxCostUsd;
+    const maxCalls = o.maxCalls ?? input.env?.maxCalls;
+    if (maxCostUsd !== undefined)
+        policy.maxCostUsd = maxCostUsd;
+    if (maxCalls !== undefined)
+        policy.maxCalls = maxCalls;
+    if (o.maxIterations !== undefined)
+        policy.maxIterations = o.maxIterations;
+    if (o.maxParallelSteps !== undefined)
+        policy.maxParallelSteps = o.maxParallelSteps;
+    return policy;
+}

package/dist/runtime/providerView.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 type { Clock } from '../util/clock.js';
+import type { Evidence, HealthState, HealthStatus, ProviderMetadata } from '../types.js';
+import type { ProviderInfo } from '../plugin/ai.js';
+/** Display-only access state, derived from HealthState + discovery freshness. Not a router concept. */
+export type AccessState = 'NOT_CONFIGURED' | 'CONFIGURED' | 'AUTHENTICATED' | 'AUTH_FAILED' | 'ACCESS_UNKNOWN' | 'AVAILABLE' | 'DEGRADED' | 'RATE_LIMITED' | 'QUOTA_EXCEEDED' | 'MODEL_UNAVAILABLE';
+/** Map a HealthState to an AccessState. Exhaustive over the 12 frozen states (compile-checked). */
+export declare function deriveAccessState(state: HealthState): AccessState;
+export interface ModelView {
+    id: string;
+    /** In the model catalog or operator-declared (source !== 'unknown'). */
+    cataloged: boolean;
+    /** At least one capability has been verified by a probe. */
+    verified: boolean;
+    contextWindow?: number;
+    quality?: string;
+    source: Evidence;
+}
+export interface ProviderView {
+    id: string;
+    name: string;
+    kind: string;
+    enabled: boolean;
+    accessState: AccessState;
+    healthState: HealthState;
+    checkedAt?: number;
+    ageMs?: number;
+    /** True when the health record is older than the freshness ttl. */
+    stale: boolean;
+    models: ModelView[];
+}
+/** The subset of the AI facade a provider view needs — so views are testable with a stub. */
+export interface ProviderViewSource {
+    providers(): ProviderInfo[];
+    checkHealth(): Promise<HealthStatus[]>;
+    discover(): Promise<ProviderMetadata[]>;
+}
+export interface BuildViewOptions {
+    now: number;
+    /** Freshness ttl in ms; a health record older than this displays as ACCESS_UNKNOWN. Default 60s. */
+    ttlMs?: number;
+}
+/** Build a joined provider/model view. Live: calls checkHealth() + discover(). */
+export declare function buildProviderViews(source: ProviderViewSource, opts: BuildViewOptions): Promise<ProviderView[]>;
+/** Memoizes provider views for a ttl so a long-lived REPL doesn't re-hit providers on every command. */
+export declare class ProviderViewCache {
+    private readonly source;
+    private readonly clock;
+    private readonly ttlMs;
+    private last?;
+    constructor(source: ProviderViewSource, options?: {
+        clock?: Clock;
+        ttlMs?: number;
+    });
+    get(force?: boolean): Promise<ProviderView[]>;
+}