ai-runtime-engine 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -5,6 +5,65 @@ All notable changes to `ai-runtime` are documented here. The format follows
 Versioning](https://semver.org/). Development history and rationale live in
 [docs/DECISIONS.md](docs/DECISIONS.md) and [docs/PROGRESS.md](docs/PROGRESS.md).
 
+## [2.8.0] — 2026-09-05
+
+Agent work now **survives a crash**. Until this release an agent's progress existed only in memory: the
+execution was written when it started and when it finished, so killing the process mid-run left a
+record with no plan and no agent state, and resuming replanned from the bare goal — discarding
+everything the agents had done. Additive: with `runtime.agents` absent, and with persistence disabled,
+every prompt, key and rendered line is identical to 2.7.0.
+
+### Added
+
+- **Persisted agent tasks.** `Execution.agentTasks` carries a versioned `AgentTaskRecord` per delegated
+  step: the inner plan with per-step statuses, the inner steps already completed, bounded inner
+  observations, an inner checkpoint, findings and admission diagnostics, and split call/tool accounting.
+  Read them with `parseAgentTasks` — the raw array is unvalidated JSON from a file, and each record is
+  schema-checked on read, fail-closed and per record.
+- **Incremental commit points.** `executePlan` reports progress at four quiescent points, `orchestrate`
+  reports the plan once it is approved and within budget, and the worker reports each task transition —
+  including from *inside* the inner run, so an agent's own progress reaches disk while it is still
+  working. Everything a resume needs is on disk before the next wave starts.
+- **Resumable inner waits.** An agent whose planner asks a question no longer fails its branch: the step
+  stays `pending`, the run pauses, and the answer is routed into *that agent's* inner goal. Two agents
+  can wait at once — the first claims the single pending slot and the rest are rediscovered as each is
+  answered.
+- **Crash reconciliation.** A task left `running` by a process that no longer exists returns to `queued`
+  with an auditable `interruption` reason (`crash` / `pause` / `parent-cancel`). It runs on resume *and*
+  inside pause/cancel, so a cancelled execution cannot strand records that still claim to be running.
+- **MCP is part of drift.** Checkpoints now fingerprint the MCP tools a plan references. A server that
+  changes a tool's shape, or drops it, while a plan sits paused is drift — the same as an edited file.
+- **Findings survive a replan.** Drift replaces the plan, but a validated finding is a fact about the
+  workspace, so active findings are carried (bounded and fenced) into the new planning context.
+
+### Fixed
+
+- **Deep redaction corrupted shared structure.** `redact()` used one visited-set for the whole
+  traversal, so a merely *shared* reference (not a cycle) became the string `"[circular]"`. Every
+  finding on an agent task shares one evidence array, so a task with two or more findings was written
+  to disk malformed and then dropped whole on read. Redaction now tracks the ancestor path; a genuine
+  cycle is still reported. This affects every caller of `redact`, not only agent state.
+- **A cancellation could be overwritten by the run that was being cancelled.** The end-of-run write
+  bypassed the ownership rules, so a `cancelExecution` landing mid-run was replaced by `completed` —
+  and terminal, so the work could not be resumed either.
+- **Secrets could reach the execution file.** Logs, telemetry, CLI output and MCP results all redact;
+  the execution store did not. Tool output and agent findings are now redacted at the persistence
+  boundary. Found by the phase's own leak scan, which is now a permanent test.
+- A resumed run reported `failed` when it was merely waiting again, and its summary said so.
+- `resume-execution <id>` with no answer replanned from the goal, destroying sibling agents' progress —
+  and `--answer` is optional in the CLI, so that was the ordinary invocation.
+- Pause and cancel could be undone by an in-flight commit; a commit is now refused rather than
+  clobbering a status this owner cannot produce, and a refused commit stops the run instead of letting
+  two owners execute the same steps.
+
+### Changed
+
+- `Finding` ids minted by a resumed attempt are namespaced (`…@a2`), and findings **merge** across
+  attempts rather than being replaced, so an interrupted attempt's findings are never orphaned.
+- A persisted observation stores `data.findingIds` instead of a second copy of the findings.
+- `nextAgentTaskId` includes the pid: under a frozen test clock two Runtimes in one process minted
+  colliding ids, which propagated into `Finding.id`.
+
 ## [2.7.0] — 2026-09-04
 
 Multi-agent core. A plan step can now **delegate to an agent** — a bounded sub-task with its own plan,
@@ -691,6 +750,7 @@ Initial release: the provider-agnostic AI **router** — capability-based routin
 scoring, evidence validation, fallback, health tracking, learning-based scoring, multi-model verification,
 budgets, MCP tools, OpenAPI-based adapter generation, and the `AI` class + CLI.
 
+[2.8.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.8.0
 [2.7.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.7.0
 [2.6.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.6.0
 [2.5.1]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.5.1

package/dist/agents/roles.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The closed role vocabulary for auto-decomposition (Phase 3.7).
+ *
+ * Auto-decomposition lets a goal produce agent steps with no operator-authored definition. The thing
+ * that makes it safe is what it does NOT do: no model-authored string ever becomes an objective, a tool
+ * id, or a permission. The model's only influence is choosing among the bounded agents offered to it —
+ * the same closed-set discipline `deriveCapabilitiesOffline` uses, applied to roles instead of ids.
+ *
+ * Every objective here is written in-tree by a human, because the objective is the one string that
+ * reaches the inner prompt UNFENCED (the step input beside it is fenced as untrusted). Every role is
+ * read-shaped, and adding a write-shaped one is a decision to record, not a line to slip in: the
+ * permission clamp would still deny it, but the catalog it is offered should not suggest otherwise.
+ */
+import type { AgentDefinition } from './definition.js';
+export interface AgentRole {
+    id: string;
+    /** IN-TREE and human-written. Never derived, never model-authored. */
+    objective: string;
+    /** What the role is for, shown in the plan catalog so the planner can choose between roles. */
+    description: string;
+    /**
+     * An output contract is MANDATORY for a derived role, though optional for an authored definition.
+     * `contractFailed` returns false when no contract is declared and the finding cap becomes infinite —
+     * so an agent nobody wrote would be the one agent whose output could never fail admission, and the
+     * one whose finding count is unbounded.
+     */
+    outputContract: NonNullable<AgentDefinition['outputContract']>;
+}
+/** Three roles ship in 3.0.0. All read-shaped; see the header before adding a fourth. */
+export declare const AGENT_ROLES: readonly AgentRole[];
+/** The id prefix reserved for synthesized agents, so one can never collide with an authored id. */
+export declare const DERIVED_ID_PREFIX = "auto_";
+/** The agent id a role synthesizes to. */
+export declare function roleAgentId(roleId: string): string;
+/** Whether an id belongs to the reserved synthesized namespace. */
+export declare function isDerivedAgentId(id: string): boolean;

package/dist/agents/roles.js

@@ -0,0 +1,44 @@
+/**
+ * The closed role vocabulary for auto-decomposition (Phase 3.7).
+ *
+ * Auto-decomposition lets a goal produce agent steps with no operator-authored definition. The thing
+ * that makes it safe is what it does NOT do: no model-authored string ever becomes an objective, a tool
+ * id, or a permission. The model's only influence is choosing among the bounded agents offered to it —
+ * the same closed-set discipline `deriveCapabilitiesOffline` uses, applied to roles instead of ids.
+ *
+ * Every objective here is written in-tree by a human, because the objective is the one string that
+ * reaches the inner prompt UNFENCED (the step input beside it is fenced as untrusted). Every role is
+ * read-shaped, and adding a write-shaped one is a decision to record, not a line to slip in: the
+ * permission clamp would still deny it, but the catalog it is offered should not suggest otherwise.
+ */
+/** Three roles ship in 3.0.0. All read-shaped; see the header before adding a fourth. */
+export const AGENT_ROLES = [
+    {
+        id: 'investigate',
+        objective: 'Investigate the question you are given by reading the workspace. Report what you found as structured findings, each naming the file or symbol it is about. Do not modify anything.',
+        description: 'reads the workspace to answer a question, and reports findings',
+        outputContract: { types: ['observation'], maxFindings: 5, requireSubject: true },
+    },
+    {
+        id: 'verify',
+        objective: 'Check the specific claim you are given against the workspace. Report whether it holds, as structured findings that name what you checked. Do not modify anything.',
+        description: 'checks a specific claim against the workspace and reports whether it holds',
+        outputContract: { types: ['verification'], maxFindings: 5, requireSubject: true },
+    },
+    {
+        id: 'survey',
+        objective: 'Survey the area you are given and describe what is there: the files, their roles, and how they relate. Report structured findings. Do not modify anything.',
+        description: 'describes the shape of an area of the workspace',
+        outputContract: { types: ['survey'], maxFindings: 5, requireSubject: true },
+    },
+];
+/** The id prefix reserved for synthesized agents, so one can never collide with an authored id. */
+export const DERIVED_ID_PREFIX = 'auto_';
+/** The agent id a role synthesizes to. */
+export function roleAgentId(roleId) {
+    return `${DERIVED_ID_PREFIX}${roleId}`;
+}
+/** Whether an id belongs to the reserved synthesized namespace. */
+export function isDerivedAgentId(id) {
+    return id.startsWith(DERIVED_ID_PREFIX);
+}

package/dist/agents/synthesize.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Synthesizing agents from the registry (Phase 3.7) — auto-decomposition.
+ *
+ * THE TOOL SET IS THE WHOLE PROBLEM. A capability's providers are NAMESPACED ids (`tool:filesystem`)
+ * while the tool registry holds bare ones (`filesystem`), and `narrowEnvelope` intersects against the
+ * bare set. Emitting provider ids directly yields an empty catalog for every derived agent — a feature
+ * that is inert while looking correct, and whose obvious tests ("a derived agent cannot name a tool
+ * outside the registry") pass vacuously on the empty array. So the prefix is stripped here, membership
+ * in the parent catalog is asserted here, and the tests assert a NON-EMPTY result.
+ *
+ * WHAT IS NOT USED: BM25 relevance. It was measured to abstain on exactly the goals these roles exist
+ * for — "review the changed files", "find the bug", "audit the auth module" all derive nothing, because
+ * its thresholds were tuned for a different job (advisory capability hints, where a false positive
+ * merely over-advises). Gating whether an agent EXISTS on that calibration would make decomposition a
+ * silent no-op for the goals it is for. Roles are offered whenever they have tools; which one fits the
+ * goal is the planner's judgment, made from the role descriptions, which is exactly its job.
+ */
+import type { AgentRole } from './roles.js';
+import type { AgentDefinition } from './definition.js';
+export interface DerivedAgent {
+    id: string;
+    roleId: string;
+    definition: AgentDefinition;
+}
+export interface SynthesizeInput {
+    /** Every capability the registry knows, with its effects and providers. */
+    capabilities: Array<{
+        id: string;
+        effects: readonly string[];
+        providers: string[];
+    }>;
+    /** The tool ids the parent actually holds — the set `narrowEnvelope` will intersect against. */
+    parentTools: string[];
+    roles?: readonly AgentRole[];
+}
+/**
+ * Offer one bounded agent per role that has at least one usable tool.
+ *
+ * A role draws the parent's tools that provide at least one READ-effect capability. Effects are
+ * advisory metadata and never authorization (invariant 25) — the permission clamp in `narrowEnvelope`
+ * is what actually denies writing. Using them here only NARROWS what a machine-generated agent is
+ * offered, which fails safe: a tool with no declared effects is inferred write-shaped and excluded.
+ */
+export declare function synthesizeAgents(input: SynthesizeInput): DerivedAgent[];

package/dist/agents/synthesize.js

@@ -0,0 +1,60 @@
+/**
+ * Synthesizing agents from the registry (Phase 3.7) — auto-decomposition.
+ *
+ * THE TOOL SET IS THE WHOLE PROBLEM. A capability's providers are NAMESPACED ids (`tool:filesystem`)
+ * while the tool registry holds bare ones (`filesystem`), and `narrowEnvelope` intersects against the
+ * bare set. Emitting provider ids directly yields an empty catalog for every derived agent — a feature
+ * that is inert while looking correct, and whose obvious tests ("a derived agent cannot name a tool
+ * outside the registry") pass vacuously on the empty array. So the prefix is stripped here, membership
+ * in the parent catalog is asserted here, and the tests assert a NON-EMPTY result.
+ *
+ * WHAT IS NOT USED: BM25 relevance. It was measured to abstain on exactly the goals these roles exist
+ * for — "review the changed files", "find the bug", "audit the auth module" all derive nothing, because
+ * its thresholds were tuned for a different job (advisory capability hints, where a false positive
+ * merely over-advises). Gating whether an agent EXISTS on that calibration would make decomposition a
+ * silent no-op for the goals it is for. Roles are offered whenever they have tools; which one fits the
+ * goal is the planner's judgment, made from the role descriptions, which is exactly its job.
+ */
+import { AGENT_ROLES, roleAgentId } from './roles.js';
+/** Strip the `tool:` / `skill:` source prefix from a provider id. */
+function bareProviderId(providerId) {
+    const at = providerId.indexOf(':');
+    return at < 0 ? { kind: '', id: providerId } : { kind: providerId.slice(0, at), id: providerId.slice(at + 1) };
+}
+/**
+ * Offer one bounded agent per role that has at least one usable tool.
+ *
+ * A role draws the parent's tools that provide at least one READ-effect capability. Effects are
+ * advisory metadata and never authorization (invariant 25) — the permission clamp in `narrowEnvelope`
+ * is what actually denies writing. Using them here only NARROWS what a machine-generated agent is
+ * offered, which fails safe: a tool with no declared effects is inferred write-shaped and excluded.
+ */
+export function synthesizeAgents(input) {
+    const parent = new Set(input.parentTools);
+    const readable = new Set();
+    for (const cap of input.capabilities) {
+        if (!cap.effects.includes('read') || cap.effects.includes('write'))
+            continue;
+        for (const providerId of cap.providers) {
+            const { kind, id } = bareProviderId(providerId);
+            // Tools only: a skill brings its own tool requirements, and a derived agent gets no skills.
+            if (kind === 'tool' && parent.has(id))
+                readable.add(id);
+        }
+    }
+    const tools = [...readable].sort();
+    if (tools.length === 0)
+        return []; // nothing to read with ⇒ nothing worth offering
+    return (input.roles ?? AGENT_ROLES).map((role) => ({
+        id: roleAgentId(role.id),
+        roleId: role.id,
+        definition: {
+            objective: role.objective,
+            tools,
+            // No skills: a skill's declared tools would have to be re-checked against the envelope, and a
+            // derived agent has no operator to have vetted that.
+            skills: [],
+            outputContract: role.outputContract,
+        },
+    }));
+}

package/dist/agents/task.d.ts

@@ -9,33 +9,76 @@
  * normal state and records WHY in `interruption`, so the reason is auditable without growing the
  * lifecycle.
  */
-import type { PlanStepStatus } from '../orchestration/plan.js';
-import type { StepObservationCode } from '../orchestration/executor.js';
-import type { ExecutionStatus } from '../executions/execution.js';
+import type { ExecutionPlan, PlanStepStatus } from '../orchestration/plan.js';
+import type { StepObservation, StepObservationCode } from '../orchestration/executor.js';
+import type { Checkpoint, ExecutionStatus } from '../executions/execution.js';
 import type { AdmissionRejection } from './admit.js';
 import type { Finding } from './finding.js';
 export type AgentTaskState = 'created' | 'queued' | 'running' | 'completed' | 'failed' | 'cancelled' | 'waiting_for_input' | 'waiting_for_clarification' | 'paused';
 export interface AgentTaskRecord {
-    /** `ag_<base36 now>_<counter>`. `agentTaskId`, NEVER `taskId` - that name belongs to the router. */
+    /** Phase 3.5: record schema version. A record whose `v` is not 1 is DROPPED on read, never coerced —
+     *  a future shape must not be silently reinterpreted as this one. */
+    v: 1;
+    /** `ag_<base36 now>_<pid>_<counter>`. `agentTaskId`, NEVER `taskId` - that name belongs to the router. */
     agentTaskId: string;
     agentId: string;
     stepId: string;
     state: AgentTaskState;
     createdAt: number;
+    /** Phase 3.5: last write. Distinct from `endedAt` — a task is written many times before it ends. */
+    updatedAt: number;
     startedAt?: number;
     endedAt?: number;
-    /** Additive, and NOT a state. Carries why a non-terminal task stopped. */
+    /** Additive, and NOT a state. Carries why a non-terminal task stopped. Cleared when a resumed task is
+     *  promoted back to `running`, so the stamp always describes the LATEST interruption (Phase 3.5). */
     interruption?: {
         kind: 'crash' | 'pause' | 'parent-cancel';
         at: number;
         detail?: string;
     };
+    /** Which run/plan minted this record. */
+    provenance: {
+        executionId?: string;
+        planVersion: number;
+    };
+    /** Hash of the AgentDefinition. An operator who edits the definition invalidates the inner plan. */
+    agentDefHash: string;
+    /** Hash of the NARROWED envelope — the tools/permissions/caps the inner plan was built against. */
+    envelopeHash: string;
+    /** Hash of the STEP, not its id. Plan step ids (`s1`, `auto1`) recur across replans, so id-matching
+     *  would bind a record to a different step's work; the input is what makes the step this step. */
+    stepInputHash: string;
+    /** How many times this task has been started. Findings minted on attempt 2 are namespaced by it, so a
+     *  resumed attempt can never mint an id that collides with a finding already on the record. */
+    attempt: number;
     innerPlanVersion?: number;
+    /** The inner plan with per-step statuses. Dropped (never truncated) when oversized — a half-written
+     *  plan is worse than none, because it would be executed. */
+    innerPlan?: ExecutionPlan;
+    /** THE resume primitive: inner steps already done, fed straight to `executePlan`'s `skip`. Survives
+     *  `innerPlan` being dropped, so a too-large plan still costs re-planning, never re-execution. */
+    innerCompletedSteps: string[];
+    /** Bounded slice of inner observations, in executor order. */
+    innerObservations: StepObservation[];
+    innerObservationsOmitted: number;
+    /** Workspace fingerprint of the inner run — the outer checkpoint cannot see files only an agent touched. */
+    innerCheckpoint?: Checkpoint;
+    /** The one inner wait that is reachable: the inner planner asked a question. */
+    pendingInner?: {
+        kind: 'clarification';
+        question: string;
+        at: number;
+    };
     innerSteps: {
         total: number;
         succeeded: number;
     };
+    /** What the step RESERVED from the outer pool (`envelope.reservation`). */
+    callsReserved: number;
+    /** Cumulative across attempts. Charged, never refunded downward. */
     callsUsed: number;
+    /** DERIVED for reporting only — `max(0, reserved - used)`. Nothing computes a budget from this. */
+    callsRefunded: number;
     toolCallsUsed: number;
     findings: Finding[];
     /** Candidates the admission pipeline REFUSED. Auditable, and never threaded anywhere. */
@@ -45,6 +88,10 @@ export interface AgentTaskRecord {
         message: string;
     };
 }
+/** Terminal agent-task states: reached once, never left. A commit may not move a task out of one. */
+export declare const AGENT_TERMINAL: ReadonlySet<AgentTaskState>;
+/** States a persisted task may be resumed from. Exactly the complement of AGENT_TERMINAL. */
+export declare const AGENT_RESUMABLE: ReadonlySet<AgentTaskState>;
 /** One row per agent-task state. Read this table; never re-derive a projection at a call site. */
 export interface ProjectionRow {
     step: PlanStepStatus;
@@ -56,5 +103,10 @@ export interface ProjectionRow {
 export declare const AGENT_TASK_PROJECTION: Readonly<Record<AgentTaskState, ProjectionRow>>;
 /** The states an agent task can actually reach in 3.4. */
 export declare const REACHABLE_IN_34: AgentTaskState[];
-/** Mint an agent task id. Base36 clock + a counter, so ids are stable under a fake clock. */
+/**
+ * Mint an agent task id. Base36 clock + PID + a counter, so ids are stable under a fake clock and still
+ * unique across processes. The pid is not decoration: tests freeze the clock, and two Runtimes in one
+ * process would otherwise mint the same id — a collision that propagates straight into `Finding.id`
+ * (`${agentTaskId}_f<n>`) and would silently merge two agents' findings.
+ */
 export declare function nextAgentTaskId(now: number): string;

package/dist/agents/task.js

@@ -9,6 +9,17 @@
  * normal state and records WHY in `interruption`, so the reason is auditable without growing the
  * lifecycle.
  */
+/** Terminal agent-task states: reached once, never left. A commit may not move a task out of one. */
+export const AGENT_TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+/** States a persisted task may be resumed from. Exactly the complement of AGENT_TERMINAL. */
+export const AGENT_RESUMABLE = new Set([
+    'created',
+    'queued',
+    'running',
+    'waiting_for_input',
+    'waiting_for_clarification',
+    'paused',
+]);
 export const AGENT_TASK_PROJECTION = {
     created: { step: 'pending', exec: 'running', reachableIn34: true },
     queued: { step: 'pending', exec: 'running', reachableIn34: true },
@@ -25,8 +36,13 @@ export const AGENT_TASK_PROJECTION = {
 /** The states an agent task can actually reach in 3.4. */
 export const REACHABLE_IN_34 = Object.keys(AGENT_TASK_PROJECTION).filter((s) => AGENT_TASK_PROJECTION[s].reachableIn34);
 let counter = 0;
-/** Mint an agent task id. Base36 clock + a counter, so ids are stable under a fake clock. */
+/**
+ * Mint an agent task id. Base36 clock + PID + a counter, so ids are stable under a fake clock and still
+ * unique across processes. The pid is not decoration: tests freeze the clock, and two Runtimes in one
+ * process would otherwise mint the same id — a collision that propagates straight into `Finding.id`
+ * (`${agentTaskId}_f<n>`) and would silently merge two agents' findings.
+ */
 export function nextAgentTaskId(now) {
     counter += 1;
-    return `ag_${now.toString(36)}_${counter.toString(36)}`;
+    return `ag_${now.toString(36)}_${process.pid.toString(36)}_${counter.toString(36)}`;
 }

package/dist/agents/worker.d.ts

@@ -27,6 +27,12 @@ import type { PermissionPolicy } from '../runtime/policy.js';
 import type { Clock } from '../util/clock.js';
 /** How much of a step input may reach the inner prompt. It is model-authored, and it is fenced. */
 export declare const AGENT_INPUT_MAX = 1000;
+/** Inner observations persisted per task. The record lives in a JSON file that is rewritten every
+ *  commit, so this is a durability bound, not a display one. Beyond it, the count is kept and the
+ *  content dropped — an honest "there was more" rather than a silently short list. */
+export declare const INNER_OBS_MAX = 20;
+/** Admission rejections kept per task. They accumulate across attempts and are rewritten every commit. */
+export declare const DIAGNOSTICS_KEPT = 50;
 export interface AgentWorkerDeps {
     ai: AI;
     clock: Clock;
@@ -60,7 +66,24 @@ export interface AgentWorkerDeps {
         executionId?: string;
         planVersion: number;
     };
+    /** Phase 3.5: called whenever the record MATERIALLY changes, so inner progress reaches disk while the
+     *  agent is still running. Without a seam inside the inner run, everything between `running` and
+     *  `finish()` — the inner plan, every completed inner step, every inner model call — is lost to a
+     *  crash, and the resume has nothing to skip. Synchronous; must not throw. */
+    onRecord?: (record: AgentTaskRecord) => void;
+    /** Phase 3.5: a persisted record to CONTINUE instead of minting a fresh one. The caller proves it
+     *  belongs to THIS step by step-input hash before passing it. */
+    resume?: AgentTaskRecord;
+    /** Phase 3.5: the human's answer to this task's inner clarification. Model-authored text from the
+     *  user, so it is fenced into the inner goal like any other untrusted input. */
+    resumeAnswer?: string;
 }
+/**
+ * What makes a step THIS step. Plan step ids (`s1`, `auto1`) are model-authored and recur across
+ * replans, so binding a persisted record by id alone would hand one step's completed inner work to a
+ * different step that happens to share its id — same agent, different input, silently wrong findings.
+ */
+export declare function stepIdentity(step: PlanStep): string;
 export interface RunAgentTaskResult {
     observation: StepObservation;
     record: AgentTaskRecord;