ai-runtime-engine 1.3.0 → 2.8.0

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

@@ -0,0 +1,112 @@
+/**
+ * Agent task state (Phase 3.4) - the record, and THE PROJECTION TABLE.
+ *
+ * The state set is the PRD's; no state is invented here. Every one of them projects onto the EXISTING
+ * PlanStepStatus / ExecutionStatus vocabularies, and that is deliberate: 3.4 adds no new status
+ * anywhere, which is what stops a later phase from needing one.
+ *
+ * An INTERRUPTION IS NOT A STATE. A crash, a parent pause, or a parent cancel leaves the task in a
+ * normal state and records WHY in `interruption`, so the reason is auditable without growing the
+ * lifecycle.
+ */
+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 {
+    /** 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. 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. */
+    diagnostics: AdmissionRejection[];
+    failure?: {
+        code: StepObservationCode;
+        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;
+    exec: ExecutionStatus;
+    code?: StepObservationCode;
+    /** False for the states only a persisted, resumable task can reach (Phase 3.5). */
+    reachableIn34: boolean;
+}
+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 + 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

@@ -0,0 +1,48 @@
+/**
+ * Agent task state (Phase 3.4) - the record, and THE PROJECTION TABLE.
+ *
+ * The state set is the PRD's; no state is invented here. Every one of them projects onto the EXISTING
+ * PlanStepStatus / ExecutionStatus vocabularies, and that is deliberate: 3.4 adds no new status
+ * anywhere, which is what stops a later phase from needing one.
+ *
+ * An INTERRUPTION IS NOT A STATE. A crash, a parent pause, or a parent cancel leaves the task in a
+ * 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 },
+    running: { step: 'running', exec: 'running', reachableIn34: true },
+    completed: { step: 'succeeded', exec: 'completed', reachableIn34: true },
+    failed: { step: 'failed', exec: 'failed', code: 'agent-failed', reachableIn34: true },
+    cancelled: { step: 'skipped', exec: 'cancelled', code: 'cancelled', reachableIn34: true },
+    // Declared, not reachable in 3.4: nothing persists an AgentTaskRecord yet, so nothing can be resumed
+    // into a waiting state. The rows exist so 3.5 inherits a mapping instead of inventing one.
+    waiting_for_input: { step: 'pending', exec: 'waiting_for_input', reachableIn34: false },
+    waiting_for_clarification: { step: 'pending', exec: 'waiting_for_clarification', reachableIn34: false },
+    paused: { step: 'pending', exec: 'paused', reachableIn34: false },
+};
+/** 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 + 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)}_${process.pid.toString(36)}_${counter.toString(36)}`;
+}

package/dist/agents/worker.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The agent worker (Phase 3.4) - runs ONE agent step.
+ *
+ * IT NEVER CALLS `orchestrate()`. It composes `generatePlan` + `executePlan` directly, because
+ * re-entering the orchestrator inside a step would re-run the parent's gates per step: re-asking for
+ * approval, re-applying the parent call budget, and re-checking plan/dry-run mode. A useful consequence
+ * of that same structure is that a dry run can never reach a worker at all - `orchestrate` returns
+ * before `executePlan` is ever called.
+ *
+ * IT NEVER CONSTRUCTS AN `AI`. One router: the inner planning call goes through a METERED FACADE over
+ * the parent's AI, so every inner model call is counted against the envelope's reservation - including
+ * the ones a skill makes through `SkillContext.ai`, which the parent budget cannot see today.
+ *
+ * DEPTH 1 IS STRUCTURAL: the inner plan is generated with `agents: []`, so `validatePlan` rejects a
+ * nested agent step as `unknown agent`. There is no runtime depth counter to get wrong.
+ */
+import { AI } from '../plugin/ai.js';
+import type { AgentTaskRecord } from './task.js';
+import type { AgentEnvelope } from './envelope.js';
+import type { AgentDefinition } from './definition.js';
+import type { PlanStep } from '../orchestration/plan.js';
+import type { StepObservation } from '../orchestration/executor.js';
+import type { Skill, SkillResult, SkillValidation } from '../skills/skill.js';
+import type { ToolResult } from '../tools/tool.js';
+import type { ArtifactRef } from '../runtime/types.js';
+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;
+    /** Narrowed to the envelope by the caller; the worker does not re-derive a catalog. */
+    skills: Skill[];
+    runSkill: (id: string, input: unknown, overrides: {
+        permissions: PermissionPolicy;
+        signal?: AbortSignal;
+        ai?: AI;
+    }) => Promise<{
+        result: SkillResult;
+        validation: SkillValidation;
+    }>;
+    runTool: (id: string, input: unknown, overrides: {
+        permissions: PermissionPolicy;
+        signal?: AbortSignal;
+    }) => Promise<ToolResult>;
+    /** Store evidence content. Returns `unavailable` rather than a dangling ref when the store is off. */
+    putArtifact: (content: string, source: string) => {
+        ref?: ArtifactRef;
+        unavailable: boolean;
+    };
+    emit?: (event: {
+        type: 'agent.task.started' | 'agent.task.completed';
+        record: AgentTaskRecord;
+    }) => void;
+    parentSignal?: AbortSignal;
+    /** Why the parent aborted, when it knows. Distinguishes a cancel from a pause on the record. */
+    abortReason?: () => 'pause' | 'parent-cancel' | undefined;
+    provenance: {
+        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;
+}
+export declare function runAgentTask(step: PlanStep, envelope: AgentEnvelope, definition: AgentDefinition, deps: AgentWorkerDeps): Promise<RunAgentTaskResult>;