@nifrajs/coding-agent 3.2.0

package/src/orchestration/recovery.ts

@@ -0,0 +1,271 @@
+/**
+ * Recovery state machine for at-least-once node dispatch.
+ *
+ * The machine treats every effect invocation as potentially side-effecting. A normal retry is
+ * allowed only for an explicit pre-effect rejection. Once an effect has been invoked, recovery
+ * requires a matching idempotency proof; without one it dead-letters the dispatch instead of
+ * guessing that a duplicate is safe. This is deliberately conservative and never claims exactly
+ * once delivery or hostile-code isolation.
+ */
+
+import {
+  type DispatchResultCode,
+  type InjectedClock,
+  type RunDispatchStore,
+  type RunLease,
+  systemClock,
+} from "./dispatch.ts"
+
+export interface IdempotencyProofStore {
+  has(key: string): boolean | Promise<boolean>
+  record(key: string): void | Promise<void>
+}
+/** Disposable proof reference for tests and one-process local runs. */
+export class MemoryIdempotencyProofStore implements IdempotencyProofStore {
+  private readonly keys = new Set<string>()
+
+  has(key: string): boolean {
+    return this.keys.has(key)
+  }
+
+  record(key: string): void {
+    this.keys.add(key)
+  }
+
+  keysSnapshot(): readonly string[] {
+    return Object.freeze([...this.keys].sort())
+  }
+}
+
+/** A side effect must explicitly confirm that its idempotency proof was durably recorded. */
+export interface CommittedEffect {
+  readonly committed: true
+}
+
+export interface RunEffectContext {
+  readonly lease: RunLease
+  readonly signal: AbortSignal
+  /** Persist a content-free safe boundary; a failed write prevents the next unsafe step. */
+  readonly checkpoint: (boundary: "before-effect" | "after-effect") => Promise<boolean>
+}
+
+export type RunEffect = (context: RunEffectContext) => Promise<CommittedEffect> | CommittedEffect
+
+/** Stable pre-effect failure; it may be retried with a new logical attempt. */
+export class EffectRejectedError extends Error {
+  readonly code: string
+
+  constructor(code = "effect_rejected") {
+    super("run effect was rejected before the side effect boundary")
+    this.name = "EffectRejectedError"
+    this.code = code
+  }
+}
+
+/** Simulates worker loss at a named boundary; the lease is intentionally left unresolved. */
+export class RecoveryCrashError extends Error {
+  readonly boundary: "before-effect" | "after-effect" | "after-checkpoint"
+
+  constructor(boundary: "before-effect" | "after-effect" | "after-checkpoint") {
+    super("worker stopped at a recovery boundary")
+    this.name = "RecoveryCrashError"
+    this.boundary = boundary
+  }
+}
+
+export interface RecoveryMachineOptions {
+  readonly store: RunDispatchStore
+  readonly clock?: InjectedClock
+  readonly proofStore?: IdempotencyProofStore
+  readonly leaseMs?: number
+  readonly retryBackoff?: (attempt: number) => number
+  readonly signal?: AbortSignal
+}
+
+export interface RecoveryProcessResult {
+  readonly leased: number
+  readonly completed: number
+  readonly retried: number
+  readonly deadLettered: number
+  readonly cancelled: number
+}
+
+const DEFAULT_LEASE_MS = 30_000
+const DEFAULT_BACKOFF = (attempt: number): number => Math.min(1_000 * Math.max(1, attempt), 60_000)
+
+function stableCode(error: unknown): string {
+  if (error instanceof EffectRejectedError) return error.code
+  if (error instanceof RecoveryCrashError) return `worker_${error.boundary.replaceAll("-", "_")}`
+  return "effect_failed"
+}
+
+function isAbort(signal: AbortSignal, error?: unknown): boolean {
+  return signal.aborted || (error instanceof DOMException && error.name === "AbortError")
+}
+
+/**
+ * Drives leases through safe checkpoints and terminal transitions. The caller owns the effect and
+ * any real idempotency ledger; this class stores only opaque proof keys in the reference adapter.
+ */
+export class RunRecoveryMachine {
+  private readonly store: RunDispatchStore
+  private readonly clock: InjectedClock
+  private readonly proofs: IdempotencyProofStore
+  private readonly leaseMs: number
+  private readonly retryBackoff: (attempt: number) => number
+  private readonly signal: AbortSignal
+
+  constructor(options: RecoveryMachineOptions) {
+    this.store = options.store
+    this.clock = options.clock ?? systemClock
+    this.proofs = options.proofStore ?? new MemoryIdempotencyProofStore()
+    this.leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS
+    this.retryBackoff = options.retryBackoff ?? DEFAULT_BACKOFF
+    this.signal = options.signal ?? new AbortController().signal
+    if (!Number.isFinite(this.leaseMs) || this.leaseMs <= 0)
+      throw new RangeError("recovery leaseMs must be positive")
+  }
+
+  /** Cancel all matching run dispatches; every late lease write then fails closed. */
+  async cancel(runId: string): Promise<number> {
+    return await this.store.cancel(runId, "cancelled")
+  }
+
+  /** Process one bounded lease batch. No payload is read or emitted by this coordinator. */
+  async process(
+    effect: RunEffect,
+    options: { readonly limit?: number } = {},
+  ): Promise<RecoveryProcessResult> {
+    const limit = options.limit ?? 1
+    const leases = await this.store.lease(this.clock.now(), limit, this.leaseMs)
+    const summary = {
+      leased: leases.length,
+      completed: 0,
+      retried: 0,
+      deadLettered: 0,
+      cancelled: 0,
+    }
+    for (const lease of leases) {
+      const outcome = await this.processLease(lease, effect)
+      summary.completed += outcome === "completed" ? 1 : 0
+      summary.retried += outcome === "retried" ? 1 : 0
+      summary.deadLettered += outcome === "dead-lettered" ? 1 : 0
+      summary.cancelled += outcome === "cancelled" ? 1 : 0
+    }
+    return Object.freeze(summary)
+  }
+
+  private async processLease(
+    lease: RunLease,
+    effect: RunEffect,
+  ): Promise<"completed" | "retried" | "dead-lettered" | "cancelled" | "waiting"> {
+    const signal = this.signal
+    if (signal.aborted) {
+      await this.store.cancel(lease.dispatch.runId, "cancelled")
+      return "cancelled"
+    }
+
+    const inspection = await this.store.inspect(lease.dispatch.dispatchId)
+    const checkpoint = inspection?.checkpoint
+    const proof = await this.proofs.has(lease.idempotencyKey)
+    if (proof || checkpoint?.boundary === "after-effect") {
+      if (!proof) {
+        await this.store.deadLetter(lease, "idempotency_required")
+        return "dead-lettered"
+      }
+      const completed = await this.store.complete(lease)
+      return completed.ok ? "completed" : "waiting"
+    }
+
+    const before = await this.storeCheckpoint(lease, "before-effect")
+    if (!before) return "waiting"
+    if (signal.aborted) {
+      await this.store.cancel(lease.dispatch.runId, "cancelled")
+      return "cancelled"
+    }
+
+    let invoked = false
+    try {
+      invoked = true
+      const committed = await effect({
+        lease,
+        signal,
+        checkpoint: (boundary) => this.storeCheckpoint(lease, boundary),
+      })
+      if (committed.committed !== true) {
+        await this.store.deadLetter(lease, "idempotency_required")
+        return "dead-lettered"
+      }
+      await this.proofs.record(lease.idempotencyKey)
+      const after = await this.storeCheckpoint(lease, "after-effect")
+      if (!after) return "waiting"
+      const completed = await this.store.complete(lease)
+      return completed.ok ? "completed" : "waiting"
+    } catch (error) {
+      if (error instanceof RecoveryCrashError) return "waiting"
+      if (isAbort(signal, error)) {
+        await this.store.cancel(lease.dispatch.runId, "cancelled")
+        return "cancelled"
+      }
+      const failure = stableCode(error)
+      if (invoked && !(error instanceof EffectRejectedError)) {
+        // The effect boundary was crossed, so a retry would be an unproven duplicate.
+        await this.store.deadLetter(lease, "idempotency_required")
+        return "dead-lettered"
+      }
+      if (lease.attempt >= lease.dispatch.maxAttempts) {
+        await this.store.deadLetter(lease, failure)
+        return "dead-lettered"
+      }
+      const delay = this.retryBackoff(lease.attempt)
+      if (!Number.isFinite(delay) || delay < 0)
+        throw new RangeError("recovery retry backoff is invalid")
+      const retried = await this.store.retry(
+        lease,
+        this.clock.now() + Math.min(delay, 86_400_000),
+        failure,
+      )
+      return retried.ok ? "retried" : "waiting"
+    }
+  }
+
+  private async storeCheckpoint(
+    lease: RunLease,
+    boundary: "before-effect" | "after-effect",
+  ): Promise<boolean> {
+    const outcome = await this.store.checkpoint(lease, {
+      version: 1,
+      dispatchId: lease.dispatch.dispatchId,
+      runId: lease.dispatch.runId,
+      nodeId: lease.dispatch.nodeId,
+      attempt: lease.attempt,
+      generation: lease.generation,
+      boundary,
+      idempotencyKey: lease.idempotencyKey,
+      at: this.clock.now(),
+      scheduleToken: lease.scheduleToken,
+    })
+    return outcome.ok
+  }
+}
+
+/** A small deterministic clock useful for recovery schedules and tests. */
+export class TestClock implements InjectedClock {
+  private current: number
+
+  constructor(start = 0) {
+    if (!Number.isSafeInteger(start) || start < 0)
+      throw new RangeError("test clock start is invalid")
+    this.current = start
+  }
+
+  now = (): number => this.current
+
+  advance(milliseconds: number): void {
+    if (!Number.isSafeInteger(milliseconds) || milliseconds < 0)
+      throw new RangeError("test clock advance is invalid")
+    this.current += milliseconds
+  }
+}
+
+export type { DispatchResultCode }

package/src/orchestration/tracer.ts

@@ -0,0 +1,177 @@
+/**
+ * The end-to-end tracer: compile a {@link RunPlan}, run it through the {@link WorkflowRunner}, and
+ * project each transition into content-free {@link RunEvidence}. Every emitted record is re-parsed
+ * through {@link parseRunEvidence}, so the tracer itself proves the stream carries no payload and
+ * stays under the size cap. The terminal digest is a deterministic hash of the evidence stream:
+ * identical plan + catalog + inputs yield an identical digest, which is the deterministic-eval anchor.
+ */
+
+import type {
+  ArtifactPort,
+  ArtifactRef,
+  NodeEffectKey,
+  RunEvidence,
+  RunNode,
+  RunNodeKind,
+  RunPlan,
+} from "@nifrajs/agent-protocol"
+import { parseRunEvidence, parseRunPlan, RUN_PLAN_VERSION } from "@nifrajs/agent-protocol"
+import { type WorkflowEvent, WorkflowRunner } from "../workflows.ts"
+import { noopArtifactPort } from "./artifact-port.ts"
+import type { StepCatalog } from "./catalog.ts"
+import { compileRunPlan, digestRunPlan } from "./compile.ts"
+import { canonicalJson, sha256HexOf } from "./hash.ts"
+
+/** A verify/approve node whose output is not a pass. Other kinds never gate. */
+function isGateRejection(kind: RunNodeKind | undefined, output: unknown): boolean {
+  if (kind === "verify") {
+    if (output === true) return false
+    return !(
+      typeof output === "object" &&
+      output !== null &&
+      (output as { ok?: unknown }).ok === true
+    )
+  }
+  if (kind === "approve") return output !== true
+  return false
+}
+
+export interface RunTraceOptions {
+  /** Caller-supplied, so a trace is fully reproducible. No clock or randomness is read here. */
+  readonly runId: string
+  readonly catalog: StepCatalog
+  /** Defaults to {@link noopArtifactPort} (hash-and-discard). */
+  readonly artifactPort?: ArtifactPort
+  readonly signal?: AbortSignal
+  readonly maxSteps?: number
+  readonly maxDepth?: number
+}
+
+export interface RunTraceResult {
+  readonly ok: boolean
+  readonly runId: string
+  readonly planDigest: string
+  readonly evidence: readonly RunEvidence[]
+  /** SHA-256 hex of the canonical evidence stream. Deterministic across identical runs. */
+  readonly terminalDigest: string
+  readonly error?: string
+}
+
+/** Run a plan and return its content-free evidence stream plus a deterministic terminal digest. */
+export async function runTrace(
+  source: RunPlan | unknown,
+  options: RunTraceOptions,
+): Promise<RunTraceResult> {
+  const plan = parseRunPlan(source)
+  const planDigest = await digestRunPlan(plan)
+  const artifactPort = options.artifactPort ?? noopArtifactPort()
+
+  const effectKeys = new Map<string, NodeEffectKey>()
+  const artifacts = new Map<string, ArtifactRef[]>()
+  const idempotent = new Map<string, boolean>()
+  const kindById = new Map<string, RunNodeKind>()
+  const nodeIds = new Set<string>()
+  const walk = (node: RunNode): void => {
+    nodeIds.add(node.id)
+    kindById.set(node.id, node.kind)
+    const step = "step" in node ? options.catalog.get(node.step) : undefined
+    idempotent.set(node.id, step?.selectEffect !== undefined)
+    switch (node.kind) {
+      case "sequence":
+      case "parallel":
+        for (const child of node.children) walk(child)
+        break
+      case "retry":
+        walk(node.child)
+        break
+      case "branch":
+        walk(node.then)
+        if (node.otherwise !== undefined) walk(node.otherwise)
+        break
+    }
+  }
+  for (const node of plan.nodes) walk(node)
+
+  const step = compileRunPlan(plan, {
+    catalog: options.catalog,
+    planDigest,
+    artifactPort,
+    onNodeEffect: (nodeId, key) => effectKeys.set(nodeId, key),
+    collectArtifact: (nodeId, ref) => {
+      const list = artifacts.get(nodeId)
+      if (list === undefined) artifacts.set(nodeId, [ref])
+      else list.push(ref)
+    },
+  })
+
+  const evidence: RunEvidence[] = []
+  let seq = 0
+  const push = (record: RunEvidence): void => {
+    // Re-parse each record: proves it is content-free and within the size cap before it is kept.
+    evidence.push(parseRunEvidence(record))
+  }
+
+  const onEvent = (event: WorkflowEvent): void => {
+    if (!("id" in event) || !nodeIds.has(event.id)) return
+    const base = {
+      version: RUN_PLAN_VERSION,
+      runId: options.runId,
+      planDigest,
+      nodeId: event.id,
+      seq: seq++,
+      idempotent: idempotent.get(event.id) ?? false,
+    } as const
+    if (event.type === "step.started") {
+      push({ ...base, status: "started" })
+      return
+    }
+    if (event.type === "step.completed") {
+      const key = effectKeys.get(event.id)
+      const refs = artifacts.get(event.id)
+      // A verify/approve gate reports pass/fail through its output, then the kernel aborts the run on
+      // a non-pass. Project that as a failed record so the evidence reflects the gate's verdict.
+      if (isGateRejection(kindById.get(event.id), event.output)) {
+        push({
+          ...base,
+          status: "failed",
+          errorCode: "GATE_REJECTED",
+          ...(key !== undefined ? { effectKey: key.digest } : {}),
+        })
+        return
+      }
+      push({
+        ...base,
+        status: "completed",
+        ...(key !== undefined ? { effectKey: key.digest } : {}),
+        ...(refs !== undefined && refs.length > 0 ? { artifacts: refs } : {}),
+      })
+      return
+    }
+    if (event.type === "step.failed") {
+      const key = effectKeys.get(event.id)
+      push({
+        ...base,
+        status: "failed",
+        errorCode: "STEP_FAILED",
+        ...(key !== undefined ? { effectKey: key.digest } : {}),
+      })
+    }
+  }
+
+  const result = await new WorkflowRunner({
+    onEvent,
+    ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    ...(options.maxSteps !== undefined ? { maxSteps: options.maxSteps } : {}),
+    ...(options.maxDepth !== undefined ? { maxDepth: options.maxDepth } : {}),
+  }).run(step)
+
+  const terminalDigest = await sha256HexOf(canonicalJson(evidence))
+  return {
+    ok: result.ok,
+    runId: options.runId,
+    planDigest,
+    evidence,
+    terminalDigest,
+    ...(result.error !== undefined ? { error: result.error } : {}),
+  }
+}

package/src/plans.ts

@@ -0,0 +1,105 @@
+import {
+  type WorkflowEvent,
+  type WorkflowResult,
+  WorkflowRunner,
+  type WorkflowStep,
+} from "./workflows.ts"
+
+export interface PlanPhase {
+  readonly id: string
+  readonly title: string
+  readonly step: WorkflowStep
+}
+
+export interface AgentPlan {
+  readonly id: string
+  readonly goal: string
+  readonly phases: readonly PlanPhase[]
+  readonly maxSteps?: number
+  readonly maxDepth?: number
+}
+
+export interface PlanEvent {
+  readonly type:
+    | "plan.started"
+    | "plan.phase.started"
+    | "plan.phase.completed"
+    | "plan.completed"
+    | "plan.failed"
+  readonly planId: string
+  readonly phaseId?: string
+  readonly message?: string
+}
+
+export interface PlanRunnerOptions {
+  readonly signal?: AbortSignal
+  readonly onEvent?: (event: PlanEvent | WorkflowEvent) => void | PromiseLike<void>
+}
+
+export interface PlanResult extends WorkflowResult {
+  readonly planId: string
+  readonly goal: string
+}
+
+/** First-party plan mode built on the bounded workflow primitives; no model or UI dependency. */
+export class PlanRunner {
+  private readonly options: PlanRunnerOptions
+
+  constructor(options: PlanRunnerOptions = {}) {
+    this.options = options
+  }
+
+  async run(plan: AgentPlan): Promise<PlanResult> {
+    validatePlan(plan)
+    await this.emit({ type: "plan.started", planId: plan.id, message: plan.goal })
+    const workflow = new WorkflowRunner({
+      ...(this.options.signal === undefined ? {} : { signal: this.options.signal }),
+      ...(plan.maxSteps === undefined ? {} : { maxSteps: plan.maxSteps }),
+      ...(plan.maxDepth === undefined ? {} : { maxDepth: plan.maxDepth }),
+      onEvent: async (event) => this.options.onEvent?.(event),
+    })
+    const step: WorkflowStep = {
+      type: "sequence",
+      steps: plan.phases.map((phase) => ({
+        type: "task" as const,
+        id: phase.id,
+        run: async (context) => {
+          await this.emit({
+            type: "plan.phase.started",
+            planId: plan.id,
+            phaseId: phase.id,
+            message: phase.title,
+          })
+          const output = await context.run(phase.step)
+          await this.emit({ type: "plan.phase.completed", planId: plan.id, phaseId: phase.id })
+          return output
+        },
+      })),
+    }
+    const result = await workflow.run(step)
+    await this.emit({
+      type: result.ok ? "plan.completed" : "plan.failed",
+      planId: plan.id,
+      ...(result.error === undefined ? {} : { message: result.error }),
+    })
+    return { ...result, planId: plan.id, goal: plan.goal }
+  }
+
+  private async emit(event: PlanEvent): Promise<void> {
+    await this.options.onEvent?.(event)
+  }
+}
+
+function validatePlan(plan: AgentPlan): void {
+  if (!/^[a-z][a-z0-9._:-]{0,63}$/.test(plan.id)) throw new TypeError("plan: id is invalid")
+  if (!plan.goal || plan.goal.length > 4_096) throw new TypeError("plan: goal is empty or too long")
+  if (plan.phases.length === 0 || plan.phases.length > 128)
+    throw new RangeError("plan: phases must be between 1 and 128")
+  const ids = new Set<string>()
+  for (const phase of plan.phases) {
+    if (!/^[a-z][a-z0-9._:-]{0,63}$/.test(phase.id) || !phase.title || phase.title.length > 256)
+      throw new TypeError(`plan: invalid phase ${phase.id}`)
+    if (ids.has(phase.id)) throw new TypeError(`plan: duplicate phase ${phase.id}`)
+    ids.add(phase.id)
+  }
+}

package/src/presets.ts

@@ -0,0 +1,90 @@
+import type { SubagentSpec } from "./subagents.ts"
+
+export type AgentPresetName =
+  | "planner"
+  | "implementer"
+  | "test-fixer"
+  | "reviewer"
+  | "security-reviewer"
+  | "final-verifier"
+
+export interface AgentPreset extends Omit<SubagentSpec, "id" | "prompt"> {
+  readonly name: AgentPresetName
+  readonly summary: string
+}
+
+const PRESETS: Readonly<Record<AgentPresetName, AgentPreset>> = Object.freeze({
+  planner: {
+    name: "planner",
+    role: "planner",
+    summary: "Break a task into bounded, verifiable phases.",
+    capabilities: Object.freeze(["read"]),
+    maxDepth: 1,
+    timeoutMs: 120_000,
+  },
+  implementer: {
+    name: "implementer",
+    role: "implementer",
+    summary: "Apply a narrowly scoped implementation and report changed files.",
+    capabilities: Object.freeze(["read", "write", "process"]),
+    maxDepth: 1,
+    timeoutMs: 600_000,
+  },
+  "test-fixer": {
+    name: "test-fixer",
+    role: "test-fixer",
+    summary: "Reproduce and repair a failing test within the task boundary.",
+    capabilities: Object.freeze(["read", "write", "process"]),
+    maxDepth: 1,
+    timeoutMs: 600_000,
+  },
+  reviewer: {
+    name: "reviewer",
+    role: "reviewer",
+    summary: "Review a proposed change for correctness and regressions.",
+    capabilities: Object.freeze(["read", "process"]),
+    maxDepth: 1,
+    timeoutMs: 240_000,
+  },
+  "security-reviewer": {
+    name: "security-reviewer",
+    role: "security-reviewer",
+    summary: "Review capabilities, trust boundaries, secrets, and process execution.",
+    capabilities: Object.freeze(["read", "process"]),
+    maxDepth: 1,
+    timeoutMs: 240_000,
+  },
+  "final-verifier": {
+    name: "final-verifier",
+    role: "final-verifier",
+    summary: "Run the configured verification gates and return structured evidence.",
+    capabilities: Object.freeze(["read", "process"]),
+    maxDepth: 1,
+    timeoutMs: 300_000,
+  },
+})
+
+export const AGENT_PRESETS = PRESETS
+
+export function getAgentPreset(name: AgentPresetName): AgentPreset {
+  return PRESETS[name]
+}
+
+export function createPresetSpec(
+  name: AgentPresetName,
+  prompt: string,
+  id = `${name}-${Date.now().toString(36)}`,
+): SubagentSpec {
+  const preset = getAgentPreset(name)
+  if (!prompt || prompt.length > 16_384)
+    throw new TypeError("agent preset: prompt is empty or too long")
+  if (!/^[a-z][a-z0-9._:-]{0,63}$/.test(id)) throw new TypeError("agent preset: id is invalid")
+  return {
+    id,
+    role: preset.role,
+    prompt,
+    ...(preset.capabilities === undefined ? {} : { capabilities: preset.capabilities }),
+    ...(preset.maxDepth === undefined ? {} : { maxDepth: preset.maxDepth }),
+    ...(preset.timeoutMs === undefined ? {} : { timeoutMs: preset.timeoutMs }),
+  }
+}

package/src/process.ts

@@ -0,0 +1,47 @@
+export interface BoundedText {
+  readonly text: string
+  readonly truncated: boolean
+}
+
+export async function readBoundedText(
+  stream: ReadableStream<Uint8Array> | null | undefined | number,
+  maxBytes: number,
+): Promise<BoundedText> {
+  if (stream === null || stream === undefined || typeof stream === "number")
+    return { text: "", truncated: false }
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+    throw new RangeError("bounded process output: maxBytes must be positive")
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  const chunks: string[] = []
+  let total = 0
+  let truncated = false
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) {
+        chunks.push(decoder.decode())
+        break
+      }
+      if (value === undefined) continue
+      const remaining = maxBytes - total
+      if (remaining <= 0) {
+        truncated = true
+        await reader.cancel()
+        break
+      }
+      if (value.byteLength > remaining) {
+        chunks.push(decoder.decode(value.subarray(0, remaining), { stream: true }))
+        chunks.push(decoder.decode())
+        truncated = true
+        await reader.cancel()
+        break
+      }
+      total += value.byteLength
+      chunks.push(decoder.decode(value, { stream: true }))
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  return { text: chunks.join(""), truncated }
+}