ai-runtime-engine 1.3.0 → 2.8.0

package/dist/memory/memory.js

@@ -8,20 +8,28 @@
 import { systemClock } from '../util/clock.js';
 import { redactString } from '../security/redact.js';
 import { bm25Search } from './bm25.js';
+import { semanticRank } from './semantic.js';
 function physical(scope) {
     if (scope === 'user')
         return 'user';
     if (scope === 'repository')
         return 'repository';
+    // The organization branch MUST precede the project catch-all, or org facts silently land in project.
+    if (scope === 'organization')
+        return 'organization';
     return 'project';
 }
-const PHYSICAL = ['user', 'project', 'repository'];
+const PHYSICAL_BASE = ['user', 'project', 'repository'];
 export class MemoryStore {
     store;
+    embedder;
     clock;
     counter = 0;
-    constructor(store, clock = systemClock) {
+    /** Per-instance cache of fact-text → vector, so a stable fact isn't re-embedded on every query. */
+    vecCache = new Map();
+    constructor(store, clock = systemClock, embedder) {
         this.store = store;
+        this.embedder = embedder;
         this.clock = clock;
     }
     get enabled() {
@@ -30,6 +38,11 @@ export class MemoryStore {
     area(scope) {
         return this.store.memory(physical(scope));
     }
+    /** Physical scopes to traverse for reads/cascades — includes `organization` only when one is configured,
+     *  so search/delete/supersession/purge cover it for free without leaking it into org-less stores. */
+    physicalScopes() {
+        return this.store.organizationId ? [...PHYSICAL_BASE, 'organization'] : PHYSICAL_BASE;
+    }
     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)}`;
@@ -38,6 +51,11 @@ export class MemoryStore {
     remember(input) {
         const now = this.clock.now();
         const scope = input.scope ?? 'project';
+        // The org scope is only available when an organization is configured — a clear error beats silently
+        // writing an org-intended fact into the project store (where physical() would otherwise route it).
+        if (scope === 'organization' && !this.store.organizationId) {
+            throw new Error("organization memory scope is not available; set `runtime.organization` in your config");
+        }
         const record = {
             id: this.nextId(),
             scope,
@@ -62,7 +80,7 @@ export class MemoryStore {
     /** Mark existing records in the same conflict group as superseded by the new record. */
     supersedeConflicts(incoming) {
         const superseded = [];
-        for (const scope of PHYSICAL) {
+        for (const scope of this.physicalScopes()) {
             const area = this.store.memory(scope);
             for (const id of area.listIds()) {
                 const rec = area.tryReadJson(id);
@@ -80,7 +98,7 @@ export class MemoryStore {
             incoming.supersedes = superseded;
     }
     get(id) {
-        for (const scope of PHYSICAL) {
+        for (const scope of this.physicalScopes()) {
             const rec = this.store.memory(scope).tryReadJson(id);
             if (rec)
                 return rec;
@@ -90,7 +108,7 @@ export class MemoryStore {
     /** Every stored record across scopes (including superseded/expired). A corrupt file is skipped. */
     all() {
         const out = [];
-        for (const scope of PHYSICAL) {
+        for (const scope of this.physicalScopes()) {
             const area = this.store.memory(scope);
             for (const id of area.listIds()) {
                 const rec = area.tryReadJson(id);
@@ -101,7 +119,8 @@ export class MemoryStore {
         return out;
     }
     /** Retrieval: filter (scope/domain/confidence/temporal/superseded) → BM25 rank → top-N. */
-    search(query, opts = {}) {
+    /** The filter stage shared by BM25 and semantic search: expiry, active-supersession, confidence, scope, domain. */
+    filteredCandidates(opts) {
         const now = opts.now ?? this.clock.now();
         const minConfidence = opts.minConfidence ?? 0;
         const scopeFilter = opts.scopes ? new Set(opts.scopes) : undefined;
@@ -113,7 +132,7 @@ export class MemoryStore {
             const s = byId.get(sid);
             return !!s && (s.validUntil === undefined || s.validUntil >= now);
         };
-        const candidates = all.filter((r) => {
+        return all.filter((r) => {
             if (r.validUntil !== undefined && r.validUntil < now)
                 return false;
             if (r.supersededBy && supersederActive(r.supersededBy))
@@ -126,9 +145,49 @@ export class MemoryStore {
                 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);
+    }
+    rankBm25(query, candidates, limit) {
+        const byId = new Map(candidates.map((r) => [r.id, r]));
+        const hits = bm25Search(query, candidates.map((r) => ({ id: r.id, text: r.text })), limit ?? 10);
+        return hits.map((h) => byId.get(h.id)).filter((r) => r !== undefined);
+    }
+    /** Retrieve facts by BM25 keyword relevance (the offline default; sync, unchanged since 1.0). */
+    search(query, opts = {}) {
+        return this.rankBm25(query, this.filteredCandidates(opts), opts.limit);
+    }
+    /**
+     * Retrieve facts by SEMANTIC (vector) relevance when an embedder is configured, else exactly BM25
+     * (Phase 14). Same filter stage, same `{scope/confidence/temporal}` semantics, same return shape. Any
+     * embedder failure falls back to BM25 — retrieval must never break the run. Candidate vectors are cached
+     * per fact text so a stable fact is embedded at most once per session.
+     */
+    async searchSemantic(query, opts = {}) {
+        const candidates = this.filteredCandidates(opts);
+        if (!this.embedder || candidates.length === 0)
+            return this.rankBm25(query, candidates, opts.limit);
+        try {
+            const need = [...new Set(candidates.map((c) => c.text))].filter((t) => !this.vecCache.has(t));
+            if (need.length) {
+                const vecs = await this.embedder.embed(need);
+                // Cache only USABLE vectors — a degenerate ([] or non-finite) embedding must never be treated as
+                // valid nor poison the cache (a poisoned entry silently excludes that fact for the rest of the session).
+                need.forEach((t, i) => { if (isUsableVec(vecs[i]))
+                    this.vecCache.set(t, vecs[i]); });
+            }
+            const [queryVec] = await this.embedder.embed([query]);
+            const docs = candidates.filter((c) => this.vecCache.has(c.text)).map((c) => ({ id: c.id, vec: this.vecCache.get(c.text) }));
+            // A degenerate query vector, or no candidate that embedded usably, degrades to BM25 — retrieval must
+            // never silently return nothing because the embedder misbehaved (invariant: an empty vector → fallback).
+            if (!isUsableVec(queryVec) || docs.length === 0)
+                return this.rankBm25(query, candidates, opts.limit);
+            const byId = new Map(candidates.map((r) => [r.id, r]));
+            const hits = semanticRank(queryVec, docs, opts.limit ?? 10);
+            return hits.map((h) => byId.get(h.id)).filter((r) => r !== undefined);
+        }
+        catch {
+            // An embedder problem (network, bad response) must never break retrieval — fall back to BM25.
+            return this.rankBm25(query, candidates, opts.limit);
+        }
     }
     /** Delete a record and cascade (strip references, heal supersession chains), under the lock. */
     delete(id) {
@@ -140,7 +199,7 @@ export class MemoryStore {
         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) {
+        for (const scope of this.physicalScopes()) {
             const area = this.store.memory(scope);
             for (const other of area.listIds()) {
                 if (other === id) {
@@ -189,3 +248,8 @@ export class MemoryStore {
 function clamp(n) {
     return Math.max(0, Math.min(1, n));
 }
+/** A vector is usable for ranking only if it is a non-empty array of finite numbers. A degenerate vector
+ *  (empty, or containing NaN/Infinity) must degrade to BM25, never yield a silently-empty semantic result. */
+function isUsableVec(v) {
+    return Array.isArray(v) && v.length > 0 && v.every(Number.isFinite);
+}

package/dist/memory/semantic.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Semantic ranking — the vector counterpart to BM25 (Phase 14). Given a query vector and candidate
+ * vectors, rank by cosine similarity and return the same `{ id, score }` shape as `bm25Search`, so the
+ * retrieval API is unchanged whether ranking is lexical or semantic. Pure and dependency-free.
+ */
+export interface VecDoc {
+    id: string;
+    vec: number[];
+}
+export interface RankedHit {
+    id: string;
+    score: number;
+}
+/** Cosine similarity of two equal-length vectors; 0 when either has no magnitude (or lengths differ). */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/** Rank candidates by cosine similarity to the query vector; top-`limit`, descending, deterministic ties. */
+export declare function semanticRank(queryVec: number[], docs: VecDoc[], limit?: number): RankedHit[];

package/dist/memory/semantic.js

@@ -0,0 +1,29 @@
+/**
+ * Semantic ranking — the vector counterpart to BM25 (Phase 14). Given a query vector and candidate
+ * vectors, rank by cosine similarity and return the same `{ id, score }` shape as `bm25Search`, so the
+ * retrieval API is unchanged whether ranking is lexical or semantic. Pure and dependency-free.
+ */
+/** Cosine similarity of two equal-length vectors; 0 when either has no magnitude (or lengths differ). */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/** Rank candidates by cosine similarity to the query vector; top-`limit`, descending, deterministic ties. */
+export function semanticRank(queryVec, docs, limit = 10) {
+    return docs
+        .map((d) => ({ id: d.id, score: cosineSimilarity(queryVec, d.vec) }))
+        .filter((h) => h.score > 0)
+        .sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+        .slice(0, limit);
+}

package/dist/orchestration/budget.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The single source of per-step model-call cost (Phase 3.4).
+ *
+ * Before this, the rule "a model call is a skill step" was written out three times — the pre-flight
+ * estimate, the executor's wave gate, and the resume recomputation. A third step kind with a non-unit
+ * cost makes three copies untenable, so every call site now folds through here and they cannot disagree
+ * about what a step costs.
+ *
+ * The invariant is PER-STEP COST, not the total: the estimate folds the whole plan while the wave gate
+ * folds a wave's runnable steps, exactly as before. Sharing one `reserve` is what keeps them consistent.
+ */
+import type { PlanStep } from './plan.js';
+/** What an agent step reserves, given the pool still available to it when it is reached. */
+export type ReserveAgentCalls = (step: PlanStep, remaining: number) => number;
+/**
+ * Model calls ONE step needs: a skill step is 1, an agent step is its reservation, a tool step is free.
+ * With no `reserve` supplied an agent step costs 0 — which is only reachable when agents are disabled,
+ * in which case no step names one.
+ */
+export declare function stepCalls(step: PlanStep, remaining: number, reserve?: ReserveAgentCalls): number;
+/**
+ * Fold the cost of a step list SEQUENTIALLY, against a remainder that declines as it goes — so the
+ * number is order-dependent and a reserve function can see what is left.
+ *
+ * Returns exactly the integer `steps.filter((s) => s.skill).length` returns when no step names an agent,
+ * which is what makes the flag-off path byte-identical. Traversal is ARRAY order, not wave order:
+ * `executionWaves` drops steps on a cycle or a dangling dependency, which would silently under-count.
+ * `validatePlan` rejects such plans before they reach here, but array order removes the hazard entirely.
+ */
+export declare function foldCalls(steps: PlanStep[], budgetRemaining: number | undefined, reserve?: ReserveAgentCalls): number;

package/dist/orchestration/budget.js

@@ -0,0 +1,40 @@
+/**
+ * The single source of per-step model-call cost (Phase 3.4).
+ *
+ * Before this, the rule "a model call is a skill step" was written out three times — the pre-flight
+ * estimate, the executor's wave gate, and the resume recomputation. A third step kind with a non-unit
+ * cost makes three copies untenable, so every call site now folds through here and they cannot disagree
+ * about what a step costs.
+ *
+ * The invariant is PER-STEP COST, not the total: the estimate folds the whole plan while the wave gate
+ * folds a wave's runnable steps, exactly as before. Sharing one `reserve` is what keeps them consistent.
+ */
+/**
+ * Model calls ONE step needs: a skill step is 1, an agent step is its reservation, a tool step is free.
+ * With no `reserve` supplied an agent step costs 0 — which is only reachable when agents are disabled,
+ * in which case no step names one.
+ */
+export function stepCalls(step, remaining, reserve) {
+    if (step.skill)
+        return 1;
+    if (step.agent)
+        return Math.max(0, Math.trunc(reserve ? reserve(step, remaining) : 0));
+    return 0;
+}
+/**
+ * Fold the cost of a step list SEQUENTIALLY, against a remainder that declines as it goes — so the
+ * number is order-dependent and a reserve function can see what is left.
+ *
+ * Returns exactly the integer `steps.filter((s) => s.skill).length` returns when no step names an agent,
+ * which is what makes the flag-off path byte-identical. Traversal is ARRAY order, not wave order:
+ * `executionWaves` drops steps on a cycle or a dangling dependency, which would silently under-count.
+ * `validatePlan` rejects such plans before they reach here, but array order removes the hazard entirely.
+ */
+export function foldCalls(steps, budgetRemaining, reserve) {
+    let used = 0;
+    for (const step of steps) {
+        const remaining = budgetRemaining === undefined ? Number.POSITIVE_INFINITY : budgetRemaining - used;
+        used += stepCalls(step, remaining, reserve);
+    }
+    return used;
+}

package/dist/orchestration/executor.d.ts

@@ -6,19 +6,61 @@
  */
 import type { SkillResult, SkillValidation } from '../skills/skill.js';
 import type { ToolResult } from '../tools/tool.js';
-import type { ExecutionPlan } from './plan.js';
+import type { ExecutionPlan, PlanStep } from './plan.js';
+import type { ReserveAgentCalls } from './budget.js';
+import type { ArtifactRef } from '../runtime/types.js';
+/** Why a step ended the way it did, when the reason is not simply "the skill/tool said so". */
+export type StepObservationCode = 'cancelled' | 'agent-failed' | 'agent-timeout' | 'agent-call-budget' | 'agent-tool-budget' | 'finding-contract' | 'agent-not-enabled'
+/** Phase 3.5: the agent's inner run needs an answer. NOT a failure — the step stays `pending` so a
+ *  resume re-runs it rather than skipping its dependents. */
+ | 'agent-waiting';
 export interface StepObservation {
     stepId: string;
     skill?: string;
     tool?: string;
+    /** Phase 3.4: the agent DEFINITION id this step delegated to. */
+    agent?: string;
+    /** Phase 3.4: `agentTaskId`, NEVER `taskId` — that name belongs to the router. */
+    agentTaskId?: string;
     ok: boolean;
     output?: string;
     error?: string;
+    code?: StepObservationCode;
+    /** Phase 3.4, AGENT STEPS ONLY: `{ findings }`, bounded and clamped. Observations are persisted
+     *  verbatim, so copying every skill's `data` here would be unbounded durable growth. */
+    data?: unknown;
+    /** Phase 3.4, agent steps only. */
+    artifacts?: ArtifactRef[];
+    /** Phase 3.4, agent steps only: METERED inner model calls. Charging the actual is the refund. */
+    callsUsed?: number;
+}
+/**
+ * A quiescent moment in `executePlan`, handed to `ExecuteDeps.onProgress` (Phase 3.5).
+ *
+ * Every fire point is between awaits — no `Promise.all` is in flight and every semaphore slot has been
+ * released — so the plan's step statuses are consistent and the snapshot describes a state the run could
+ * legitimately be resumed from. `observations` is a DELTA (what appeared since the previous fire), so a
+ * sink appends rather than de-duplicating; `callsUsed` is cumulative for this `executePlan` call.
+ */
+export interface ProgressSnapshot {
+    at: 'wave-partition' | 'batch' | 'budget-stop' | 'plan-end';
+    plan: ExecutionPlan;
+    observations: StepObservation[];
+    callsUsed: number;
+    /** Step ids whose agent is waiting for input. Non-empty ⇒ the run is resumable, NOT failed. */
+    waiting: string[];
 }
 export interface ExecuteResult {
     ok: boolean;
     plan: ExecutionPlan;
     observations: StepObservation[];
+    /** Phase 22: true when execution paused BEFORE a wave because running it would exceed `callBudget`.
+     *  Not a failure — the completed steps stand and the rest can resume with a raised budget. */
+    stoppedForBudget?: boolean;
+    /** Phase 3.5: steps left waiting for input. Non-empty ⇒ resumable; callers must not report `failed`. */
+    waiting?: string[];
+    /** Model calls (skill steps) actually executed this run. */
+    callsUsed?: number;
 }
 export interface ExecuteDeps {
     runSkill: (id: string, input: unknown) => Promise<{
@@ -30,6 +72,27 @@ export interface ExecuteDeps {
     signal?: AbortSignal;
     /** Step ids already completed in a prior run — marked succeeded and NOT re-executed (resume). */
     skip?: ReadonlySet<string>;
+    /** Phase 22: max model calls (skill steps) this run may make. When the NEXT wave's skill steps would
+     *  exceed it, execution stops before that wave (phase granularity) with `stoppedForBudget:true`. */
+    callBudget?: number;
+    /** Phase 19: per-tool / per-skill concurrency caps (id → max concurrent). Bounds how many steps using a
+     *  given tool/skill run at once, WITHIN the `maxParallelSteps` batch. Absent ⇒ no per-key limit. */
+    limits?: {
+        perTool?: Record<string, number>;
+        perSkill?: Record<string, number>;
+        perAgent?: Record<string, number>;
+    };
+    /** Phase 3.4: run one agent step. Absent ⇒ an agent step fails with code 'agent-not-enabled'. */
+    runAgent?: (step: PlanStep, ctx: {
+        reservation: number;
+        signal?: AbortSignal;
+    }) => Promise<StepObservation>;
+    /** Phase 3.4: what an agent step reserves. The SAME function the pre-flight estimate uses. */
+    reserve?: ReserveAgentCalls;
+    /** Phase 3.5: called at each quiescent point so progress reaches disk BEFORE the next wave starts
+     *  (invariant 18). Synchronous and must not throw — the executor does not own persistence policy and
+     *  will not try to recover from a sink that fails. */
+    onProgress?: (snapshot: ProgressSnapshot) => void;
 }
 /** 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

@@ -5,7 +5,22 @@
  * never mutates anything itself; all side effects go through the permission-gated tools.
  */
 import { executionWaves } from './plan.js';
-async function runStep(step, deps) {
+import { KeyedSemaphore } from '../util/semaphore.js';
+import { foldCalls, stepCalls } from './budget.js';
+/** Run a step, bounded by the per-tool/per-skill limiter when one is configured (else a direct call). */
+async function runStep(step, deps, limiters) {
+    const exec = () => runStepInner(step, deps);
+    if (limiters) {
+        if (step.skill)
+            return limiters.skills.run(step.skill, exec);
+        if (step.tool)
+            return limiters.tools.run(step.tool, exec);
+        if (step.agent)
+            return limiters.agents.run(step.agent, exec);
+    }
+    return exec();
+}
+async function runStepInner(step, deps) {
     try {
         if (step.skill) {
             const { result, validation } = await deps.runSkill(step.skill, step.input);
@@ -16,6 +31,11 @@ async function runStep(step, deps) {
             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' }) };
         }
+        if (step.agent) {
+            if (!deps.runAgent)
+                return { stepId: step.id, agent: step.agent, ok: false, code: 'agent-not-enabled', error: 'agent execution is not enabled' };
+            return deps.runAgent(step, { reservation: stepCalls(step, Number.POSITIVE_INFINITY, deps.reserve), ...(deps.signal ? { signal: deps.signal } : {}) });
+        }
         return { stepId: step.id, ok: false, error: 'step names neither a skill nor a tool' };
     }
     catch (err) {
@@ -25,8 +45,30 @@ async function runStep(step, deps) {
 /** 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);
+    // Per-tool/per-skill limiters are built once (persist across waves). Absent config ⇒ direct calls.
+    const limiters = deps.limits
+        ? { tools: new KeyedSemaphore(deps.limits.perTool ?? {}), skills: new KeyedSemaphore(deps.limits.perSkill ?? {}), agents: new KeyedSemaphore(deps.limits.perAgent ?? {}) }
+        : undefined;
     const observations = [];
     const failedOrSkipped = new Set(); // read for dependency-skipping; success is tracked via step.status
+    // Cancellation is distinguished from failure so a cancelled BRANCH never reads as a silent skip. Only
+    // a step carrying `agent` can enter this set, so with agents disabled it is provably empty and both
+    // branches below render exactly as 2.6.0.
+    const cancelled = new Set();
+    // Phase 3.5: steps whose agent asked for input. They are NOT failures — the step stays `pending`, its
+    // dependents are neither run nor skipped, and the run stops scheduling so it can be resumed.
+    const waiting = new Set();
+    let callsUsed = 0; // model calls = executed skill steps (tool steps are free)
+    let stoppedForBudget = false;
+    // Phase 3.5: observations are handed to the sink as a DELTA, so it appends instead of de-duplicating.
+    let emitted = 0;
+    const fire = (at) => {
+        if (!deps.onProgress)
+            return;
+        const delta = observations.slice(emitted);
+        emitted = observations.length;
+        deps.onProgress({ at, plan, observations: delta, callsUsed, waiting: [...waiting] });
+    };
     for (const wave of executionWaves(plan.steps)) {
         // A step runs only if all its dependencies succeeded; otherwise it is skipped.
         const runnable = [];
@@ -38,28 +80,83 @@ export async function executePlan(plan, deps) {
             else if (deps.signal?.aborted) {
                 step.status = 'skipped';
                 failedOrSkipped.add(step.id);
+                if (step.agent) {
+                    // An agent step that never started because the run was aborted says so, rather than vanishing.
+                    cancelled.add(step.id);
+                    observations.push({ stepId: step.id, agent: step.agent, ok: false, code: 'cancelled', error: 'cancelled: the run was aborted' });
+                }
             }
             else if (depsFailed) {
                 step.status = 'skipped';
                 failedOrSkipped.add(step.id);
-                observations.push({ stepId: step.id, ok: false, error: 'skipped: a dependency failed' });
+                if ((step.dependsOn ?? []).some((d) => cancelled.has(d))) {
+                    cancelled.add(step.id);
+                    observations.push({ stepId: step.id, ok: false, code: 'cancelled', error: 'cancelled: an agent branch was cancelled' });
+                }
+                else {
+                    observations.push({ stepId: step.id, ok: false, error: 'skipped: a dependency failed' });
+                }
             }
             else {
                 runnable.push(step);
             }
         }
+        // Every skipped/cancelled verdict for this wave is now decided and nothing is in flight: the
+        // cheapest honest moment to get the wave's shape on disk, and it precedes the budget stop below.
+        fire('wave-partition');
+        // Phase 22 budget gate: if running this wave's skill steps would exceed the call budget, stop BEFORE
+        // it (phase granularity). Remaining steps keep status 'pending' and can resume with a raised budget.
+        if (deps.callBudget !== undefined) {
+            const waveCalls = foldCalls(runnable, deps.callBudget - callsUsed, deps.reserve);
+            if (waveCalls > 0 && callsUsed + waveCalls > deps.callBudget) {
+                stoppedForBudget = true;
+                fire('budget-stop');
+                break;
+            }
+        }
         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)));
+            const results = await Promise.all(batch.map((s) => runStep(s, deps, limiters)));
             results.forEach((obs, j) => {
                 const step = batch[j];
-                step.status = obs.ok ? 'succeeded' : 'failed';
-                if (!obs.ok)
-                    failedOrSkipped.add(step.id);
+                // A waiting agent is the one non-terminal step outcome: it is neither a success nor a failure, so
+                // it must not mark the step `failed` — that would skip every dependent and make the branch
+                // unrecoverable on resume, which is the opposite of what waiting means.
+                const isWaiting = !obs.ok && obs.code === 'agent-waiting';
+                step.status = isWaiting ? 'pending' : obs.ok ? 'succeeded' : 'failed';
+                if (step.skill)
+                    callsUsed += 1;
+                // Charging what an agent actually SPENT is the refund: an aborted or cancelled task reports its
+                // metered total and the unspent reservation is simply never charged. No ledger, no refund path.
+                else if (step.agent)
+                    callsUsed += obs.callsUsed ?? stepCalls(step, Number.POSITIVE_INFINITY, deps.reserve);
+                if (isWaiting)
+                    waiting.add(step.id);
+                else {
+                    if (!obs.ok && obs.code === 'cancelled')
+                        cancelled.add(step.id);
+                    if (!obs.ok)
+                        failedOrSkipped.add(step.id);
+                }
                 observations.push(obs);
             });
+            fire('batch');
         }
+        // Something is waiting for a human. Scheduling further waves would run work whose inputs may change
+        // once the answer arrives, so the run stops here and resumes when it is answered.
+        if (waiting.size > 0)
+            break;
     }
-    return { ok: plan.steps.every((s) => s.status === 'succeeded'), plan, observations };
+    // Success only if every step succeeded AND we didn't stop early for budget or for an answer.
+    const ok = !stoppedForBudget && waiting.size === 0 && plan.steps.every((s) => s.status === 'succeeded');
+    fire('plan-end');
+    return {
+        ok,
+        plan,
+        observations,
+        callsUsed,
+        ...(stoppedForBudget ? { stoppedForBudget: true } : {}),
+        ...(waiting.size > 0 ? { waiting: [...waiting] } : {}),
+    };
 }

package/dist/orchestration/orchestrator.d.ts

@@ -10,9 +10,20 @@ 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 { PlannerInput } from './planner.js';
+import type { AgentEnvelope } from '../agents/envelope.js';
+import type { ExecuteDeps } from './executor.js';
+import type { CapabilityGap } from '../capabilities/capability.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 type OrchestrationStatus = 'completed' | 'failed' | 'waiting_for_clarification' | 'waiting_for_approval' | 'waiting_for_budget' | 'dry-run';
+/** Estimated vs available model-call budget for a plan (Phase 22). Structurally matches executions' BudgetInfo. */
+export interface PlanBudget {
+    estCalls: number;
+    maxCalls: number;
+    completedSteps: number;
+    totalSteps: number;
+}
 export interface OrchestrateInput {
     goal: string;
     /** plan = plan only; execute = single pass; orchestrate/agent/debug = replan loop. */
@@ -30,6 +41,25 @@ export interface OrchestrateInput {
     signal?: AbortSignal;
     /** User exclude/prefer routing, applied to planning-model calls. */
     routing?: RoutingPreferences;
+    /** Phase 22: run the phases that fit the call budget and pause resumably (vs. the default notify-and-wait). */
+    partial?: boolean;
+    /** Phase 3.1: pre-rendered action-capability snapshot for the planner prompt (opt-in). */
+    capabilityCatalog?: string;
+    /** Phase 3.3: pre-rendered "Required capabilities" block for the planner prompt (opt-in). */
+    requiredCapabilities?: string;
+    /** Phase 3.4: the narrowed envelopes for this run's agent definitions. Absent ⇒ agents are inert:
+     *  the planner is told nothing about agents and `validatePlan` rejects any agent step. */
+    agents?: AgentEnvelope[];
+    /** Phase 3.4: runs one agent step. Supplied together with `agents` by the Runtime. */
+    runAgent?: ExecuteDeps['runAgent'];
+    /** Phase 3.1: maps unregistered plan references to structured gaps. */
+    resolveGaps?: PlannerInput['resolveGaps'];
+    /** Phase 3.5: the plan is settled — approved if approval was required, and inside the call budget.
+     *  Fired BEFORE the first step runs, so a crash during wave 1 still resumes against a real plan
+     *  instead of replanning from the bare goal. */
+    onPlan?: (plan: ExecutionPlan) => void;
+    /** Phase 3.5: forwarded verbatim to `executePlan` — the per-wave/per-batch commit points. */
+    onProgress?: ExecuteDeps['onProgress'];
 }
 export interface OrchestrateOutcome {
     status: OrchestrationStatus;
@@ -38,5 +68,9 @@ export interface OrchestrateOutcome {
     observations: StepObservation[];
     clarification?: string;
     summary: string;
+    /** Phase 3.1: structured capability gaps behind a planning failure (additive metadata). */
+    gaps?: CapabilityGap[];
+    /** Set on `waiting_for_budget` — the estimate/progress the caller surfaces and persists. */
+    budget?: PlanBudget;
 }
 export declare function orchestrate(input: OrchestrateInput): Promise<OrchestrateOutcome>;