ai-runtime-engine 1.1.0

package/dist/mcp/mcp.js

@@ -0,0 +1,54 @@
+/**
+ * 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`.
+ */
+export class StaticMcpSource {
+    id;
+    tools;
+    handlers;
+    constructor(id, tools, handlers = {}) {
+        this.id = id;
+        this.tools = tools;
+        this.handlers = handlers;
+    }
+    async listTools() {
+        return this.tools;
+    }
+    async callTool(name, args) {
+        const handler = this.handlers[name];
+        if (!handler)
+            throw new Error(`MCP source '${this.id}' has no handler for tool '${name}'`);
+        return handler(args);
+    }
+}
+export class McpRegistry {
+    sources = new Map();
+    register(source) {
+        this.sources.set(source.id, source);
+    }
+    list() {
+        return [...this.sources.values()];
+    }
+    /** Aggregate tools across all registered sources. Tool names are namespaced by source to avoid clashes. */
+    async allTools() {
+        const out = [];
+        for (const source of this.sources.values()) {
+            for (const tool of await source.listTools()) {
+                out.push({ ...tool, name: tool.name.includes('.') ? tool.name : `${source.id}.${tool.name}` });
+            }
+        }
+        return out;
+    }
+    /** Route a (namespaced) tool call to its source. */
+    async call(name, args) {
+        const [sourceId, ...rest] = name.split('.');
+        const source = sourceId ? this.sources.get(sourceId) : undefined;
+        if (!source || !source.callTool)
+            throw new Error(`no MCP source can handle tool '${name}'`);
+        return source.callTool(rest.join('.') || name, args);
+    }
+}

package/dist/memory/bm25.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A compact, dependency-free BM25 ranker — the default memory retrieval scorer. It runs offline and
+ * deterministically. An `EmbeddingProvider` seam (memory/memory.ts) lets real embeddings replace this
+ * later without changing the retrieval API.
+ */
+export declare function tokenize(text: string): string[];
+export interface Bm25Doc {
+    id: string;
+    text: string;
+}
+export interface Bm25Hit {
+    id: string;
+    score: number;
+}
+/** Rank docs against a query with BM25. Returns hits with score > 0, highest first. */
+export declare function bm25Search(query: string, docs: Bm25Doc[], limit?: number): Bm25Hit[];

package/dist/memory/bm25.js

@@ -0,0 +1,56 @@
+/**
+ * A compact, dependency-free BM25 ranker — the default memory retrieval scorer. It runs offline and
+ * deterministically. An `EmbeddingProvider` seam (memory/memory.ts) lets real embeddings replace this
+ * later without changing the retrieval API.
+ */
+const STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'is', 'are', 'was', 'were', 'be', 'been', 'to', 'of', 'in', 'on', 'for', 'with', 'as', 'by', 'at', 'this', 'that', 'these', 'those', 'it', 'its', 'i', 'you', 'we', 'they', 'do', 'does', 'did', 'has', 'have', 'had', 'will', 'would', 'should', 'can', 'could',
+]);
+export function tokenize(text) {
+    const out = [];
+    for (const m of text.toLowerCase().matchAll(/[a-z0-9]+/g)) {
+        const tok = m[0];
+        if (tok.length >= 2 && !STOPWORDS.has(tok))
+            out.push(tok);
+    }
+    return out;
+}
+const K1 = 1.5;
+const B = 0.75;
+/** Rank docs against a query with BM25. Returns hits with score > 0, highest first. */
+export function bm25Search(query, docs, limit = 10) {
+    const queryTerms = [...new Set(tokenize(query))];
+    if (queryTerms.length === 0 || docs.length === 0)
+        return [];
+    const tokenized = docs.map((d) => ({ id: d.id, terms: tokenize(d.text) }));
+    const N = tokenized.length;
+    const avgdl = tokenized.reduce((s, d) => s + d.terms.length, 0) / N || 1;
+    const df = new Map();
+    for (const term of queryTerms) {
+        let count = 0;
+        for (const d of tokenized)
+            if (d.terms.includes(term))
+                count += 1;
+        df.set(term, count);
+    }
+    const hits = [];
+    for (const d of tokenized) {
+        const dl = d.terms.length;
+        const tf = new Map();
+        for (const t of d.terms)
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+        let score = 0;
+        for (const term of queryTerms) {
+            const f = tf.get(term);
+            if (!f)
+                continue;
+            const n = df.get(term);
+            const idf = Math.log(1 + (N - n + 0.5) / (n + 0.5));
+            score += idf * ((f * (K1 + 1)) / (f + K1 * (1 - B + (B * dl) / avgdl)));
+        }
+        if (score > 0)
+            hits.push({ id: d.id, score });
+    }
+    hits.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : 1));
+    return hits.slice(0, limit);
+}

package/dist/memory/classifier.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Explicit-memory classifier. Detects a clear "remember this" instruction in user text and extracts the
+ * fact + a scope guess. Conservative by design: only explicit requests become high-confidence memories
+ * here. Observed/inferred capture (from execution outcomes) arrives in later phases at low confidence.
+ */
+import type { MemoryScope, MemorySource } from './memory.js';
+export interface MemoryCandidate {
+    text: string;
+    scope: MemoryScope;
+    source: MemorySource;
+    confidence: number;
+}
+/** Returns a memory candidate for an explicit "remember …" instruction, else undefined. */
+export declare function classifyMemory(input: string): MemoryCandidate | undefined;

package/dist/memory/classifier.js

@@ -0,0 +1,17 @@
+/**
+ * Explicit-memory classifier. Detects a clear "remember this" instruction in user text and extracts the
+ * fact + a scope guess. Conservative by design: only explicit requests become high-confidence memories
+ * here. Observed/inferred capture (from execution outcomes) arrives in later phases at low confidence.
+ */
+const TRIGGER = /^\s*(?:please\s+)?(?:remember|note|keep in mind|don'?t forget|do not forget)(?:\s+that)?\s*[:,-]?\s+(.+)$/i;
+/** Returns a memory candidate for an explicit "remember …" instruction, else undefined. */
+export function classifyMemory(input) {
+    const m = TRIGGER.exec(input);
+    if (!m)
+        return undefined;
+    const fact = m[1].trim().replace(/\s+/g, ' ');
+    if (!fact)
+        return undefined;
+    const scope = /\b(i|my|me)\b.*\b(prefer|like|want|always|never|usually|hate|favou?rite)\b/i.test(fact) || /^my\b/i.test(fact) ? 'user' : 'project';
+    return { text: fact, scope, source: 'explicit', confidence: 0.9 };
+}

package/dist/memory/memory.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Memory store — durable, scoped facts (distinct from conversations and learning). Records are redacted
+ * before storage, ranked at query time with BM25 (+ metadata/temporal/relationship filtering), and
+ * deleted with a full cascade + audit. Conflict resolution supersedes contradictory facts rather than
+ * blindly merging. Physical placement: user → shared user store; repository → repo-shared; everything
+ * else → the per-project store (so monorepo packages don't cross-contaminate).
+ */
+import type { Clock } from '../util/clock.js';
+import type { RuntimeStore } from '../store/store.js';
+export type MemoryScope = 'user' | 'project' | 'repository' | 'domain' | 'skill' | 'execution';
+export type MemorySource = 'explicit' | 'observed' | 'inferred' | 'imported';
+export interface MemoryRecord {
+    id: string;
+    scope: MemoryScope;
+    text: string;
+    domain?: string;
+    source: MemorySource;
+    confidence: number;
+    createdAt: number;
+    updatedAt: number;
+    validUntil?: number;
+    supersedes?: string[];
+    supersededBy?: string;
+    conflictGroup?: string;
+    sourcePriority?: number;
+    relatedIds?: string[];
+}
+export interface RememberInput {
+    text: string;
+    scope?: MemoryScope;
+    source?: MemorySource;
+    confidence?: number;
+    domain?: string;
+    validUntil?: number;
+    conflictGroup?: string;
+    sourcePriority?: number;
+    relatedIds?: string[];
+}
+export interface SearchOptions {
+    scopes?: MemoryScope[];
+    limit?: number;
+    minConfidence?: number;
+    domain?: string;
+    now?: number;
+}
+export interface DeletionAudit {
+    id: string;
+    primary: boolean;
+    indexes: boolean;
+    relationships: number;
+    cache: boolean;
+}
+/** Future extension seam: real embeddings replace BM25 without changing the retrieval API. */
+export interface EmbeddingProvider {
+    embed(texts: string[]): Promise<number[][]>;
+}
+export declare class MemoryStore {
+    private readonly store;
+    private readonly clock;
+    private counter;
+    constructor(store: RuntimeStore, clock?: Clock);
+    get enabled(): boolean;
+    private area;
+    private nextId;
+    /** Store a fact. Redacts text, resolves conflicts (supersedes prior same-group facts). */
+    remember(input: RememberInput): MemoryRecord;
+    /** Mark existing records in the same conflict group as superseded by the new record. */
+    private supersedeConflicts;
+    get(id: string): MemoryRecord | undefined;
+    /** Every stored record across scopes (including superseded/expired). A corrupt file is skipped. */
+    all(): MemoryRecord[];
+    /** Retrieval: filter (scope/domain/confidence/temporal/superseded) → BM25 rank → top-N. */
+    search(query: string, opts?: SearchOptions): MemoryRecord[];
+    /** Delete a record and cascade (strip references, heal supersession chains), under the lock. */
+    delete(id: string): DeletionAudit;
+    /** The cascade itself (assumes the caller holds the lock). Heals A→B→C when B is removed. */
+    private removeCascade;
+    /** Remove expired records with full cascade, under the lock. Returns removed ids. */
+    purgeExpired(now?: number): string[];
+}

package/dist/memory/memory.js

@@ -0,0 +1,191 @@
+/**
+ * Memory store — durable, scoped facts (distinct from conversations and learning). Records are redacted
+ * before storage, ranked at query time with BM25 (+ metadata/temporal/relationship filtering), and
+ * deleted with a full cascade + audit. Conflict resolution supersedes contradictory facts rather than
+ * blindly merging. Physical placement: user → shared user store; repository → repo-shared; everything
+ * else → the per-project store (so monorepo packages don't cross-contaminate).
+ */
+import { systemClock } from '../util/clock.js';
+import { redactString } from '../security/redact.js';
+import { bm25Search } from './bm25.js';
+function physical(scope) {
+    if (scope === 'user')
+        return 'user';
+    if (scope === 'repository')
+        return 'repository';
+    return 'project';
+}
+const PHYSICAL = ['user', 'project', 'repository'];
+export class MemoryStore {
+    store;
+    clock;
+    counter = 0;
+    constructor(store, clock = systemClock) {
+        this.store = store;
+        this.clock = clock;
+    }
+    get enabled() {
+        return this.store.enabled;
+    }
+    area(scope) {
+        return this.store.memory(physical(scope));
+    }
+    nextId() {
+        // clock + pid + per-instance counter + entropy → collision-safe across instances and processes.
+        return `mem_${this.clock.now().toString(36)}_${process.pid.toString(36)}_${(this.counter += 1).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+    }
+    /** Store a fact. Redacts text, resolves conflicts (supersedes prior same-group facts). */
+    remember(input) {
+        const now = this.clock.now();
+        const scope = input.scope ?? 'project';
+        const record = {
+            id: this.nextId(),
+            scope,
+            text: redactString(input.text),
+            source: input.source ?? 'explicit',
+            confidence: clamp(input.confidence ?? 0.9),
+            createdAt: now,
+            updatedAt: now,
+            ...(input.domain ? { domain: input.domain } : {}),
+            ...(input.validUntil !== undefined ? { validUntil: input.validUntil } : {}),
+            ...(input.conflictGroup ? { conflictGroup: input.conflictGroup } : {}),
+            ...(input.sourcePriority !== undefined ? { sourcePriority: input.sourcePriority } : {}),
+            ...(input.relatedIds ? { relatedIds: input.relatedIds } : {}),
+        };
+        this.store.withLock(() => {
+            if (record.conflictGroup)
+                this.supersedeConflicts(record);
+            this.area(scope).writeJson(record.id, record);
+        });
+        return record;
+    }
+    /** Mark existing records in the same conflict group as superseded by the new record. */
+    supersedeConflicts(incoming) {
+        const superseded = [];
+        for (const scope of PHYSICAL) {
+            const area = this.store.memory(scope);
+            for (const id of area.listIds()) {
+                const rec = area.tryReadJson(id);
+                if (!rec || rec.id === incoming.id || rec.supersededBy)
+                    continue;
+                if (rec.conflictGroup && rec.conflictGroup === incoming.conflictGroup) {
+                    rec.supersededBy = incoming.id;
+                    rec.updatedAt = incoming.createdAt;
+                    area.writeJson(rec.id, rec);
+                    superseded.push(rec.id);
+                }
+            }
+        }
+        if (superseded.length)
+            incoming.supersedes = superseded;
+    }
+    get(id) {
+        for (const scope of PHYSICAL) {
+            const rec = this.store.memory(scope).tryReadJson(id);
+            if (rec)
+                return rec;
+        }
+        return undefined;
+    }
+    /** Every stored record across scopes (including superseded/expired). A corrupt file is skipped. */
+    all() {
+        const out = [];
+        for (const scope of PHYSICAL) {
+            const area = this.store.memory(scope);
+            for (const id of area.listIds()) {
+                const rec = area.tryReadJson(id);
+                if (rec)
+                    out.push(rec);
+            }
+        }
+        return out;
+    }
+    /** Retrieval: filter (scope/domain/confidence/temporal/superseded) → BM25 rank → top-N. */
+    search(query, opts = {}) {
+        const now = opts.now ?? this.clock.now();
+        const minConfidence = opts.minConfidence ?? 0;
+        const scopeFilter = opts.scopes ? new Set(opts.scopes) : undefined;
+        const all = this.all();
+        const byId = new Map(all.map((r) => [r.id, r]));
+        // A record is hidden only when its superseder still EXISTS and is not itself expired — so a fact
+        // superseded by a temporary record becomes live again once that record expires or is deleted.
+        const supersederActive = (sid) => {
+            const s = byId.get(sid);
+            return !!s && (s.validUntil === undefined || s.validUntil >= now);
+        };
+        const candidates = all.filter((r) => {
+            if (r.validUntil !== undefined && r.validUntil < now)
+                return false;
+            if (r.supersededBy && supersederActive(r.supersededBy))
+                return false;
+            if (r.confidence < minConfidence)
+                return false;
+            if (scopeFilter && !scopeFilter.has(r.scope))
+                return false;
+            if (opts.domain && r.domain !== opts.domain)
+                return false;
+            return true;
+        });
+        const candById = new Map(candidates.map((r) => [r.id, r]));
+        const hits = bm25Search(query, candidates.map((r) => ({ id: r.id, text: r.text })), opts.limit ?? 10);
+        return hits.map((h) => candById.get(h.id)).filter((r) => r !== undefined);
+    }
+    /** Delete a record and cascade (strip references, heal supersession chains), under the lock. */
+    delete(id) {
+        return this.store.withLock(() => this.removeCascade(id));
+    }
+    /** The cascade itself (assumes the caller holds the lock). Heals A→B→C when B is removed. */
+    removeCascade(id) {
+        const target = this.get(id);
+        const inheritor = target?.supersededBy; // if the removed record was itself superseded, heirs re-link to its head
+        let primary = false;
+        let relationships = 0;
+        for (const scope of PHYSICAL) {
+            const area = this.store.memory(scope);
+            for (const other of area.listIds()) {
+                if (other === id) {
+                    area.remove(id);
+                    primary = true;
+                    continue;
+                }
+                const rec = area.tryReadJson(other);
+                if (!rec)
+                    continue;
+                let changed = false;
+                if (rec.relatedIds?.includes(id)) {
+                    rec.relatedIds = rec.relatedIds.filter((r) => r !== id);
+                    changed = true;
+                }
+                if (rec.supersededBy === id) {
+                    if (inheritor)
+                        rec.supersededBy = inheritor; // chain heals: still superseded by the newer head
+                    else
+                        delete rec.supersededBy; // the removed record was the head → this one is live again
+                    changed = true;
+                }
+                if (rec.supersedes?.includes(id)) {
+                    rec.supersedes = rec.supersedes.filter((r) => r !== id);
+                    changed = true;
+                }
+                if (changed) {
+                    relationships += 1;
+                    area.writeJson(rec.id, rec);
+                }
+            }
+        }
+        // Indexes are derived from records at query time; nothing separate to purge (true once persisted).
+        return { id, primary, indexes: true, relationships, cache: true };
+    }
+    /** Remove expired records with full cascade, under the lock. Returns removed ids. */
+    purgeExpired(now = this.clock.now()) {
+        return this.store.withLock(() => {
+            const expired = this.all().filter((r) => r.validUntil !== undefined && r.validUntil < now).map((r) => r.id);
+            for (const id of expired)
+                this.removeCascade(id);
+            return expired;
+        });
+    }
+}
+function clamp(n) {
+    return Math.max(0, Math.min(1, n));
+}

package/dist/orchestration/executor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Executor — runs a validated plan's steps through the runtime's skills/tools, DAG-ordered, up to
+ * `maxParallelSteps` at a time. A step succeeds only on EVIDENCE (a skill's own validation, or a tool's
+ * ok result) — never a model's say-so. A step whose dependency failed is skipped, not run. The executor
+ * never mutates anything itself; all side effects go through the permission-gated tools.
+ */
+import type { SkillResult, SkillValidation } from '../skills/skill.js';
+import type { ToolResult } from '../tools/tool.js';
+import type { ExecutionPlan } from './plan.js';
+export interface StepObservation {
+    stepId: string;
+    skill?: string;
+    tool?: string;
+    ok: boolean;
+    output?: string;
+    error?: string;
+}
+export interface ExecuteResult {
+    ok: boolean;
+    plan: ExecutionPlan;
+    observations: StepObservation[];
+}
+export interface ExecuteDeps {
+    runSkill: (id: string, input: unknown) => Promise<{
+        result: SkillResult;
+        validation: SkillValidation;
+    }>;
+    runTool: (id: string, input: unknown) => Promise<ToolResult>;
+    maxParallelSteps?: number;
+    signal?: AbortSignal;
+    /** Step ids already completed in a prior run — marked succeeded and NOT re-executed (resume). */
+    skip?: ReadonlySet<string>;
+}
+/** Execute a plan. Runs DAG waves; within a wave, batches of at most maxParallelSteps run concurrently. */
+export declare function executePlan(plan: ExecutionPlan, deps: ExecuteDeps): Promise<ExecuteResult>;

package/dist/orchestration/executor.js

@@ -0,0 +1,65 @@
+/**
+ * Executor — runs a validated plan's steps through the runtime's skills/tools, DAG-ordered, up to
+ * `maxParallelSteps` at a time. A step succeeds only on EVIDENCE (a skill's own validation, or a tool's
+ * ok result) — never a model's say-so. A step whose dependency failed is skipped, not run. The executor
+ * never mutates anything itself; all side effects go through the permission-gated tools.
+ */
+import { executionWaves } from './plan.js';
+async function runStep(step, deps) {
+    try {
+        if (step.skill) {
+            const { result, validation } = await deps.runSkill(step.skill, step.input);
+            const ok = result.ok && validation.ok;
+            return { stepId: step.id, skill: step.skill, ok, ...(result.output !== undefined ? { output: result.output } : {}), ...(ok ? {} : { error: result.error?.message ?? validation.checks.find((c) => !c.ok)?.why ?? 'validation failed' }) };
+        }
+        if (step.tool) {
+            const result = await deps.runTool(step.tool, step.input);
+            return { stepId: step.id, tool: step.tool, ok: result.ok, ...(result.output !== undefined ? { output: result.output } : {}), ...(result.ok ? {} : { error: result.error?.message ?? 'tool failed' }) };
+        }
+        return { stepId: step.id, ok: false, error: 'step names neither a skill nor a tool' };
+    }
+    catch (err) {
+        return { stepId: step.id, ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Execute a plan. Runs DAG waves; within a wave, batches of at most maxParallelSteps run concurrently. */
+export async function executePlan(plan, deps) {
+    const max = Math.max(1, deps.maxParallelSteps ?? 2);
+    const observations = [];
+    const failedOrSkipped = new Set(); // read for dependency-skipping; success is tracked via step.status
+    for (const wave of executionWaves(plan.steps)) {
+        // A step runs only if all its dependencies succeeded; otherwise it is skipped.
+        const runnable = [];
+        for (const step of wave) {
+            const depsFailed = (step.dependsOn ?? []).some((d) => failedOrSkipped.has(d));
+            if (deps.skip?.has(step.id)) {
+                step.status = 'succeeded'; // already done in a prior run (resume) — not re-executed
+            }
+            else if (deps.signal?.aborted) {
+                step.status = 'skipped';
+                failedOrSkipped.add(step.id);
+            }
+            else if (depsFailed) {
+                step.status = 'skipped';
+                failedOrSkipped.add(step.id);
+                observations.push({ stepId: step.id, ok: false, error: 'skipped: a dependency failed' });
+            }
+            else {
+                runnable.push(step);
+            }
+        }
+        for (let i = 0; i < runnable.length; i += max) {
+            const batch = runnable.slice(i, i + max);
+            batch.forEach((s) => (s.status = 'running'));
+            const results = await Promise.all(batch.map((s) => runStep(s, deps)));
+            results.forEach((obs, j) => {
+                const step = batch[j];
+                step.status = obs.ok ? 'succeeded' : 'failed';
+                if (!obs.ok)
+                    failedOrSkipped.add(step.id);
+                observations.push(obs);
+            });
+        }
+    }
+    return { ok: plan.steps.every((s) => s.status === 'succeeded'), plan, observations };
+}

package/dist/orchestration/orchestrator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Orchestrator — the understand→plan→(approve/dry-run)→execute→observe→validate→done?/replan loop.
+ * The model proposes plans; the Runtime owns execution, approval, and limits (from ExecutionPolicy).
+ * `plan` mode plans only; `execute` runs a single planned pass; `orchestrate` replans on failure up to
+ * the iteration limit. Dry-run performs ZERO mutations. Missing information surfaces as clarification.
+ */
+import type { AI } from '../plugin/ai.js';
+import type { RoutingPreferences } from '../types.js';
+import type { Skill, SkillResult, SkillValidation } from '../skills/skill.js';
+import type { ApprovalProvider } from '../runtime/host.js';
+import type { ExecutionPolicy } from '../runtime/policy.js';
+import type { ToolResult } from '../tools/tool.js';
+import type { StepObservation } from './executor.js';
+import type { ExecutionPlan } from './plan.js';
+export type OrchestrationStatus = 'completed' | 'failed' | 'waiting_for_clarification' | 'waiting_for_approval' | 'dry-run';
+export interface OrchestrateInput {
+    goal: string;
+    /** plan = plan only; execute = single pass; orchestrate/agent/debug = replan loop. */
+    mode: 'plan' | 'execute' | 'orchestrate' | 'agent' | 'debug';
+    ai: AI;
+    skills: Skill[];
+    tools: string[];
+    policy: ExecutionPolicy;
+    approval?: ApprovalProvider;
+    runSkill: (id: string, input: unknown) => Promise<{
+        result: SkillResult;
+        validation: SkillValidation;
+    }>;
+    runTool: (id: string, input: unknown) => Promise<ToolResult>;
+    signal?: AbortSignal;
+    /** User exclude/prefer routing, applied to planning-model calls. */
+    routing?: RoutingPreferences;
+}
+export interface OrchestrateOutcome {
+    status: OrchestrationStatus;
+    plan?: ExecutionPlan;
+    planHistory: ExecutionPlan[];
+    observations: StepObservation[];
+    clarification?: string;
+    summary: string;
+}
+export declare function orchestrate(input: OrchestrateInput): Promise<OrchestrateOutcome>;

package/dist/orchestration/orchestrator.js

@@ -0,0 +1,63 @@
+/**
+ * Orchestrator — the understand→plan→(approve/dry-run)→execute→observe→validate→done?/replan loop.
+ * The model proposes plans; the Runtime owns execution, approval, and limits (from ExecutionPolicy).
+ * `plan` mode plans only; `execute` runs a single planned pass; `orchestrate` replans on failure up to
+ * the iteration limit. Dry-run performs ZERO mutations. Missing information surfaces as clarification.
+ */
+import { generatePlan } from './planner.js';
+import { executePlan } from './executor.js';
+function planSummary(plan) {
+    const lines = plan.steps.map((s) => `  ${s.id}. ${s.description} [${s.skill ? 'skill:' + s.skill : 'tool:' + s.tool}]`);
+    return `Plan v${plan.version} for "${plan.goal}" (${plan.steps.length} steps):\n${lines.join('\n')}`;
+}
+export async function orchestrate(input) {
+    const planHistory = [];
+    const loops = input.mode === 'orchestrate' || input.mode === 'agent' || input.mode === 'debug';
+    const maxIterations = loops ? Math.max(1, input.policy.maxIterations ?? (input.mode === 'agent' ? 10 : 5)) : 1;
+    const needsApproval = input.policy.approval !== 'none' && input.policy.autonomy !== 'chat';
+    let priorObservations = [];
+    // Accumulate observations across replan iterations so an early return never discards the trace of
+    // prior iterations that already executed (and may have mutated the workspace).
+    const allObservations = [];
+    for (let version = 1; version <= maxIterations; version += 1) {
+        const planResult = await generatePlan({
+            goal: input.goal,
+            ai: input.ai,
+            skills: input.skills,
+            tools: input.tools,
+            version,
+            ...(input.routing ? { routing: input.routing } : {}),
+            ...(version > 1 ? { reason: 'previous attempt did not complete', priorObservations } : {}),
+        });
+        if (planResult.clarification)
+            return { status: 'waiting_for_clarification', planHistory, observations: [...allObservations], clarification: planResult.clarification, summary: planResult.clarification };
+        if (!planResult.plan)
+            return { status: 'failed', planHistory, observations: [...allObservations], summary: planResult.error ?? 'planning failed' };
+        const plan = planResult.plan;
+        planHistory.push(plan);
+        if (input.mode === 'plan')
+            return { status: 'completed', plan, planHistory, observations: [...allObservations], summary: `${planSummary(plan)}\n(plan only — not executed)` };
+        // Dry-run: report, never execute. Checked BEFORE approval — a dry run changes nothing, so it never
+        // needs approval.
+        if (input.policy.dryRun)
+            return { status: 'dry-run', plan, planHistory, observations: [...allObservations], summary: `${planSummary(plan)}\n(dry run — no changes were made)` };
+        // Approval gate (assisted/autonomous with an approval level).
+        if (needsApproval) {
+            if (!input.approval)
+                return { status: 'waiting_for_approval', plan, planHistory, observations: [...allObservations], summary: `${planSummary(plan)}\nApproval required before execution.` };
+            const approved = await input.approval.requestApproval({ action: `execute plan v${plan.version} for "${plan.goal}"`, reason: planSummary(plan), risk: 'medium' });
+            if (!approved)
+                return { status: 'failed', plan, planHistory, observations: [...allObservations], summary: 'plan was not approved' };
+        }
+        const exec = await executePlan(plan, { runSkill: input.runSkill, runTool: input.runTool, ...(input.policy.maxParallelSteps ? { maxParallelSteps: input.policy.maxParallelSteps } : {}), ...(input.signal ? { signal: input.signal } : {}) });
+        allObservations.push(...exec.observations);
+        if (exec.ok)
+            return { status: 'completed', plan, planHistory, observations: [...allObservations], summary: `completed "${plan.goal}" in ${plan.steps.length} step(s)` };
+        // Failed: gather evidence and replan (orchestrate only) or stop.
+        priorObservations = exec.observations.filter((o) => !o.ok).map((o) => `${o.stepId}: ${o.error ?? 'failed'}`);
+        if (!loops || version === maxIterations) {
+            return { status: 'failed', plan, planHistory, observations: [...allObservations], summary: `did not complete "${plan.goal}" after ${version} attempt(s): ${priorObservations.join('; ')}` };
+        }
+    }
+    return { status: 'failed', planHistory, observations: [...allObservations], summary: 'exhausted planning attempts' };
+}