ai-runtime-engine 2.7.0 → 2.9.0

package/dist/runtime/events.js

@@ -6,6 +6,10 @@
  * Token-streaming extension point: `response.delta` is reserved here (content-bearing, redacted like
  * everything else). Provider token streaming is NOT implemented in 1.0 — no delta is ever emitted yet —
  * but declaring the arm keeps the host/emitter architecture ready for it without a breaking change.
+ *
+ * EVOLUTION CONTRACT: this union GROWS. A new arm is additive at runtime — an existing consumer keeps
+ * receiving the events it knows — but it breaks an exhaustive `switch` at COMPILE time. Consumers must
+ * carry a default case. Arms added this way are announced in the CHANGELOG.
  */
 import { systemClock } from '../util/clock.js';
 import { redact } from '../security/redact.js';

package/dist/runtime/runtime.d.ts

@@ -25,6 +25,7 @@ import type { SkillSource, LoadedSource } from '../skills/discovery.js';
 import type { AgentDefinition } from '../agents/definition.js';
 import { ExecutionStore } from '../executions/store.js';
 import type { Execution } from '../executions/execution.js';
+import type { AgentTaskState, AgentTaskView } from '../agents/task.js';
 import { ArtifactStore } from '../artifacts/artifacts.js';
 import type { CompareInput } from '../comparison/comparator.js';
 import type { ComparisonResult } from '../comparison/comparison.js';
@@ -87,6 +88,8 @@ export declare class Runtime {
     /** Live runs, so a pause/cancel can abort the agent tasks actually in flight. Only ever populated
      *  when agents are enabled, so pause/cancel are unchanged with the flag off. */
     private readonly liveRuns;
+    /** Phase 3.6: agent tasks running RIGHT NOW in this process, and how to stop each one on its own. */
+    private readonly liveAgentTasks;
     /** The config file's `budget:` ceilings, kept only so the 3.3 pre-pass can decline a model call. */
     private readonly _configBudget?;
     private readonly approval?;
@@ -268,8 +271,29 @@ export declare class Runtime {
     executions(): Execution[];
     /** plan/execute/orchestrate/agent/debug: run the orchestrator and persist a resumable Execution. */
     private runOrchestration;
+    /**
+     * THE mid-run persistence sink (Phase 3.5) — the only thing that writes an execution while it runs.
+     *
+     * Invariant 18 says everything needed for resume is on disk before the next wave starts, and the
+     * non-obvious part is WHAT that includes. Committing the plan, the completed steps and the agent
+     * records is not enough: the resume gate is `!recon.drifted && !!exec.plan`, and `recon` defaults to
+     * DRIFTED whenever `checkpoints` is empty. Since checkpoints were captured only after orchestration
+     * returned, a crash mid-run always drifted, always replanned, and re-ran every completed agent task —
+     * the exact thing this phase exists to prevent. So the sink captures a checkpoint too.
+     *
+     * Every refusal from the funnel ABORTS the run. A refused commit means another owner now owns this
+     * execution's fate; carrying on would call the same tools and burn the same model calls twice while
+     * that owner re-runs the identical steps, and every result would be discarded at the end anyway.
+     */
+    private runPersistence;
     /** Run `fn` while heartbeating the execution lease so a long run never lets the lease expire. */
     private withHeartbeat;
+    /**
+     * Build the OrchestrateInput. The optional half is an OBJECT, not a positional tail: this function
+     * grew to ten parameters and a caller that passed five of them silently got no sink, no signal and no
+     * provenance — a replan that persisted nothing and could not be cancelled. Named fields cannot be
+     * short-counted.
+     */
     private orchestrateInput;
     /** Record an EXECUTED orchestration outcome for learning. plan-only, dry-run, and waiting states are
      * skipped — no skill ran, so there is no success/failure to learn (recording them would teach noise). */
@@ -349,6 +373,72 @@ export declare class Runtime {
      * an agent step would have failed every one of those steps.
      */
     private orchestrateRunners;
+    /**
+     * A bounded, fenced brief of what the agents have already established (Phase 3.5).
+     *
+     * On drift the plan is thrown away and the goal is replanned — but validated findings are facts about
+     * the WORKSPACE, not about the plan's structure, so discarding them silently would make the run redo
+     * work it had already proved. They are agent-authored text, so they cross a prompt boundary fenced,
+     * exactly like every other untrusted string.
+     */
+    private findingsBrief;
+    /**
+     * Fingerprint the MCP tools a plan actually references (Phase 3.5). An MCP server is remote and
+     * mutable: while a plan sits paused it can change a tool's input schema, change what it does, or drop
+     * it entirely — and the plan would then be resumed against a tool that is no longer the tool it was
+     * planned for. Hashing the live declaration makes that visible as ordinary drift.
+     *
+     * Non-MCP tools are deliberately absent: they are in-tree code covered by the config/skill hashes.
+     */
+    private mcpToolHashes;
+    /**
+     * Crash / pause / cancel reconciliation (Phase 3.5). A record left `running` or `created` describes a
+     * worker that no longer exists — the process died, or the parent stopped it — so it goes back to
+     * `queued` with an auditable reason. An interruption is deliberately NOT a state: the lifecycle does
+     * not grow, only the explanation does.
+     *
+     * This runs on the RESUME path and inside pause/cancel. Resume alone is not enough: `cancelExecution`
+     * writes a terminal status and resume early-returns on terminal, so a cancelled execution's `running`
+     * records would stay `running` on disk forever, unstamped and unexplained.
+     *
+     * Records that fail validation are preserved in place, never dropped — reconciling is not a licence to
+     * delete what this version could not parse.
+     */
+    private reconcileAgentTasks;
+    /**
+     * FIRST-WINS PENDING. `Execution.pending` is a single slot but two agents can be waiting at once, so
+     * the earliest-created waiting task claims it. The others are not lost: once this one is answered and
+     * the run continues, the next resume re-elects whichever task is still waiting — rediscovery, rather
+     * than a queue that has to be kept in sync with the records that are already the source of truth.
+     */
+    private electWaitingAgent;
+    /**
+     * Which persisted task, if any, a plan step should CONTINUE. Bound by step-input hash, never by step
+     * id: plan step ids (`s1`, `auto1`) are model-authored and recur across replans, so an id match would
+     * hand one step's completed inner work to a different step with the same id and a different input.
+     */
+    private agentResumeLookup;
+    /**
+     * Every agent task this Runtime can see, newest execution first (Phase 3.6). Live ones (running in
+     * this process) and persisted ones are the same list: a task's record IS its status, so there is no
+     * second source to disagree with.
+     */
+    agentTasks(executionId?: string): AgentTaskView[];
+    /**
+     * Stop one agent task. Four cases, and NONE of them is a silent no-op — a `stop` that appears to do
+     * nothing is indistinguishable from a bug:
+     *
+     *  - running in this process: abort it, then let the worker record `cancelled` as it unwinds;
+     *  - persisted and not finished (another process, or a dead one): write `cancelled` with a
+     *    `parent-cancel` interruption, so the record stops claiming it is queued or running;
+     *  - already finished: report that, and change nothing — a terminal state is sticky;
+     *  - unknown id: say so.
+     */
+    stopAgentTask(agentTaskId: string): {
+        ok: boolean;
+        state?: AgentTaskState;
+        reason: string;
+    };
     /** Abort a run that is in flight, recording WHY so a task can tell a pause from a cancellation. */
     private abortLiveRun;
     /** Mark an execution paused (it can be resumed later). */