@vauban-org/agent-sdk 0.16.0

package/src/orchestration/ooda/agent.ts

@@ -0,0 +1,1009 @@
+/**
+ * OODAAgentImpl — sequential while+sleep cycle loop with phase persistence,
+ * guards, HITL gate, resource limits, and replay-safe context propagation.
+ *
+ * Implements all 10 anti-patterns enforced by-design (see `./types.ts`).
+ *
+ * @public
+ */
+
+import { randomUUID } from "node:crypto";
+import { SpanStatusCode } from "@opentelemetry/api";
+import type {
+  CycleEvent,
+  CycleStatus,
+  ExecutionMode,
+  OODAAgent,
+  OODAAgentConfig,
+  OODAContext,
+  PhaseDef,
+  ResourceLimits,
+  RiskGuard,
+  SessionGuard,
+} from "./types.js";
+import { DEFAULT_RESOURCE_LIMITS } from "./types.js";
+import { EMPTY_SKILL_REGISTRY } from "./skills.js";
+import { MissingDryRunFlagError } from "../../errors.js";
+import { agentSpan, getTracer } from "../../tracking/gen-ai.js";
+
+/**
+ * Noop logger fallback when host does not inject one.
+ * Prevents TypeError: Cannot read properties of undefined (0.8.1 fix).
+ */
+const NOOP_LOGGER = {
+  info: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+  debug: () => undefined,
+};
+
+/** Internal sleep helper — kept private so tests grep cannot find a global setInterval. */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    if (ms <= 0) {
+      resolve();
+      return;
+    }
+    setTimeout(resolve, ms).unref?.();
+  });
+}
+
+/**
+ * Default in-memory step persister. Hosts MUST inject `insertStepImpl` /
+ * `completeStepImpl` / `errorStepImpl` when persisting to Postgres.
+ *
+ * The default is intentionally trivial: it generates a UUID stepId and
+ * a deterministic-but-fake leaf hash. This keeps the SDK runnable in
+ * tests and dry-run hosts without requiring a DB.
+ */
+function defaultInsertStep(): OODAContext["insertStep"] {
+  return async () => ({ stepId: randomUUID() });
+}
+
+function defaultCompleteStep(): OODAContext["completeStep"] {
+  return async (stepId) => ({ leafHash: `0x${stepId.replace(/-/g, "")}` });
+}
+
+function defaultErrorStep(): OODAContext["errorStep"] {
+  return async () => {};
+}
+
+function defaultNotifySlack(): OODAContext["notifySlack"] {
+  return async () => {};
+}
+
+/**
+ * Race a promise against an `AbortSignal.timeout`-driven rejection.
+ * Anti-pattern #9 enforcement.
+ */
+function withPhaseTimeout<T>(p: Promise<T>, timeoutMs: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const t = setTimeout(() => {
+      reject(new Error(`OODA phase timeout exceeded (${timeoutMs}ms)`));
+    }, timeoutMs);
+    t.unref?.();
+    p.then(
+      (v) => {
+        clearTimeout(t);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(t);
+        reject(e);
+      }
+    );
+  });
+}
+
+/**
+ * Validate phase definitions at construction time.
+ * - observe + orient must be readOnly (anti-pattern #7)
+ * - executionMode must be a known value (anti-pattern #6)
+ */
+function validateConfig(config: OODAAgentConfig): void {
+  if (config.executionMode !== "dry-run" && config.executionMode !== "live") {
+    throw new Error(
+      `OODAAgent: executionMode is REQUIRED ('dry-run' | 'live') — got ${JSON.stringify(
+        config.executionMode
+      )}`
+    );
+  }
+  if (config.phases.observe.readOnly !== true) {
+    throw new Error(
+      "OODAAgent: phases.observe MUST be readOnly:true (anti-pattern #7)"
+    );
+  }
+  if (config.phases.orient.readOnly !== true) {
+    throw new Error(
+      "OODAAgent: phases.orient MUST be readOnly:true (anti-pattern #7)"
+    );
+  }
+  if (!Number.isFinite(config.intervalMs) || config.intervalMs < 0) {
+    throw new Error(
+      `OODAAgent: intervalMs must be >= 0, got ${config.intervalMs}`
+    );
+  }
+}
+
+/**
+ * OODAAgentImpl — concrete implementation. Prefer `createOODAAgent` factory.
+ */
+export class OODAAgentImpl<
+  TConfig = unknown,
+  TObs = unknown,
+  TOrient = unknown,
+  TDecision = unknown,
+  TAction = unknown,
+  TFeedback = unknown
+> implements OODAAgent
+{
+  private readonly _config: OODAAgentConfig<
+    TConfig,
+    TObs,
+    TOrient,
+    TDecision,
+    TAction,
+    TFeedback
+  >;
+  private readonly _limits: Required<ResourceLimits>;
+  private _running = false;
+  private _cyclesCompleted = 0;
+  private _lastCycleAt?: string;
+  private _activeCycle?: Promise<unknown>;
+
+  constructor(
+    config: OODAAgentConfig<
+      TConfig,
+      TObs,
+      TOrient,
+      TDecision,
+      TAction,
+      TFeedback
+    >
+  ) {
+    validateConfig(config as OODAAgentConfig);
+    this._config = config;
+    this._limits = {
+      phaseTimeoutMs:
+        config.resourceLimits?.phaseTimeoutMs ??
+        DEFAULT_RESOURCE_LIMITS.phaseTimeoutMs,
+      maxStepsPerCycle:
+        config.resourceLimits?.maxStepsPerCycle ??
+        DEFAULT_RESOURCE_LIMITS.maxStepsPerCycle,
+      maxHeapMb:
+        config.resourceLimits?.maxHeapMb ?? DEFAULT_RESOURCE_LIMITS.maxHeapMb,
+    };
+  }
+
+  async start(): Promise<void> {
+    if (this._running) return;
+    this._running = true;
+    // Anti-pattern #1 — sequential while + sleep. NEVER setInterval.
+    while (this._running) {
+      this._activeCycle = this.runCycle();
+      await this._activeCycle;
+      this._activeCycle = undefined;
+      if (!this._running) break;
+      await sleep(this._config.intervalMs);
+    }
+  }
+
+  async stop(): Promise<void> {
+    this._running = false;
+    if (this._activeCycle) {
+      try {
+        await this._activeCycle;
+      } catch {
+        // Cycle errors already surfaced via runCycle's logging.
+      }
+    }
+  }
+
+  async triggerCycle(opts: {
+    dryRun: boolean;
+    initialContext?: Record<string, unknown>;
+  }): Promise<{ runId: string; status: CycleStatus }> {
+    if (opts?.dryRun === undefined) {
+      throw new MissingDryRunFlagError();
+    }
+    const overrideMode: ExecutionMode | undefined =
+      opts.dryRun === true ? "dry-run" : undefined;
+    return this.runCycle(overrideMode, opts.initialContext);
+  }
+
+  async *streamCycle(opts: {
+    dryRun: boolean;
+    initialContext?: Record<string, unknown>;
+  }): AsyncGenerator<CycleEvent> {
+    const runId = randomUUID();
+    const cycleIndex = this._cyclesCompleted;
+    const executionMode: ExecutionMode = opts.dryRun
+      ? "dry-run"
+      : this._config.executionMode;
+
+    // ── Event channel ─────────────────────────────────────────────────────
+    // We need to bridge an async-function-based execution (runCycleWithSink)
+    // with an async generator consumer. We do this via a push queue + pull
+    // mechanism: the sink pushes events into the queue; the generator drains
+    // the queue as events arrive.
+    const queue: CycleEvent[] = [];
+    let done = false;
+    let resolveNext: (() => void) | undefined;
+
+    function push(evt: CycleEvent): void {
+      queue.push(evt);
+      if (resolveNext) {
+        const r = resolveNext;
+        resolveNext = undefined;
+        r();
+      }
+    }
+
+    // Run the cycle body in the background; it calls push() for every event.
+    const cyclePromise = this._runCycleWithSink(
+      runId,
+      cycleIndex,
+      executionMode,
+      push,
+      opts.initialContext
+    ).finally(() => {
+      done = true;
+      if (resolveNext) {
+        const r = resolveNext;
+        resolveNext = undefined;
+        r();
+      }
+    });
+
+    // Drain the queue as events arrive.
+    while (!done || queue.length > 0) {
+      if (queue.length > 0) {
+        yield queue.shift() as CycleEvent;
+      } else {
+        // Wait until the next push() or until done is set.
+        await new Promise<void>((res) => {
+          resolveNext = res;
+        });
+      }
+    }
+
+    // Await the cycle promise to surface any unhandled rejection.
+    await cyclePromise;
+  }
+
+  getStatus(): {
+    running: boolean;
+    lastCycleAt?: string;
+    nextCycleAt?: string;
+    cyclesCompleted: number;
+  } {
+    return {
+      running: this._running,
+      lastCycleAt: this._lastCycleAt,
+      cyclesCompleted: this._cyclesCompleted,
+    };
+  }
+
+  // ─── internal ────────────────────────────────────────────────────────────
+
+  private async runCycle(
+    overrideMode?: ExecutionMode,
+    initialContext?: Record<string, unknown>
+  ): Promise<{ runId: string; status: CycleStatus }> {
+    const runId = randomUUID();
+    const cycleIndex = this._cyclesCompleted;
+    const executionMode = overrideMode ?? this._config.executionMode;
+    const isReplay = false;
+    const logger = this._config.logger ?? NOOP_LOGGER;
+
+    // ── OTel: agent-level span for the full cycle ───────────────────────────
+    const tracer = getTracer("vauban-agent-sdk.ooda");
+    const rootSpan = agentSpan(tracer, {
+      agentId: this._config.agentId,
+      agentVersion: this._config.agentVersion ?? "0.0.0",
+      runId,
+    });
+    rootSpan.setAttribute("vauban.ooda.cycle_index", cycleIndex);
+    rootSpan.setAttribute("vauban.ooda.execution_mode", executionMode);
+
+    let stepsThisCycle = 0;
+    const limits = this._limits;
+
+    const baseInsertStep = this._config.insertStepImpl ?? defaultInsertStep();
+    const insertStep: OODAContext["insertStep"] = async (input) => {
+      stepsThisCycle += 1;
+      if (stepsThisCycle > limits.maxStepsPerCycle) {
+        throw new Error(
+          `OODA: maxStepsPerCycle exceeded (${limits.maxStepsPerCycle})`
+        );
+      }
+      return baseInsertStep(input);
+    };
+
+    let liveConfig: TConfig = (this._config.config ??
+      ({} as TConfig)) as TConfig;
+    if (this._config.configLoader) {
+      try {
+        liveConfig = await this._config.configLoader.get(this._config.agentId);
+      } catch (e) {
+        logger.warn(
+          { agentId: this._config.agentId, err: (e as Error).message },
+          "ooda.cycle.config_loader_failed — using static config"
+        );
+      }
+    }
+
+    const ctx: OODAContext<TConfig> = Object.freeze({
+      agentId: this._config.agentId,
+      runId,
+      cycleIndex,
+      executionMode,
+      isReplay,
+      config: liveConfig,
+      configLoader: this._config.configLoader,
+      db: this._config.db,
+      skills: this._config.skills ?? EMPTY_SKILL_REGISTRY,
+      logger,
+      deps: this._config.deps ?? {},
+      insertStep,
+      completeStep: this._config.completeStepImpl ?? defaultCompleteStep(),
+      errorStep: this._config.errorStepImpl ?? defaultErrorStep(),
+      notifySlack: this._config.notifySlackImpl ?? defaultNotifySlack(),
+    });
+
+    // ── Session guards ──────────────────────────────────────────────────────
+    const sessionResult = await this._checkSessionGuards(
+      this._config.sessionGuards ?? []
+    );
+    if (!sessionResult.ok) {
+      logger.info(
+        { runId, agentId: this._config.agentId, reason: sessionResult.reason },
+        "ooda.cycle.skipped.session_guard"
+      );
+      rootSpan.setAttribute("vauban.ooda.status", "skipped");
+      rootSpan.setAttribute(
+        "vauban.ooda.skip_reason",
+        sessionResult.reason ?? "session_guard"
+      );
+      rootSpan.setStatus({ code: SpanStatusCode.OK });
+      rootSpan.end();
+      this._cyclesCompleted += 1;
+      this._lastCycleAt = new Date().toISOString();
+      return { runId, status: "skipped" };
+    }
+
+    // ── Risk guards ─────────────────────────────────────────────────────────
+    const riskResult = await this._checkRiskGuards(
+      this._config.riskGuards ?? [],
+      ctx
+    );
+    if (!riskResult.ok) {
+      logger.info(
+        { runId, agentId: this._config.agentId, reason: riskResult.reason },
+        "ooda.cycle.skipped.risk_guard"
+      );
+      rootSpan.setAttribute("vauban.ooda.status", "skipped");
+      rootSpan.setAttribute(
+        "vauban.ooda.skip_reason",
+        riskResult.reason ?? "risk_guard"
+      );
+      rootSpan.setStatus({ code: SpanStatusCode.OK });
+      rootSpan.end();
+      this._cyclesCompleted += 1;
+      this._lastCycleAt = new Date().toISOString();
+      return { runId, status: "skipped" };
+    }
+
+    // ── Heap watermark ──────────────────────────────────────────────────────
+    const heapMb = process.memoryUsage().heapUsed / (1024 * 1024);
+    if (heapMb > limits.maxHeapMb) {
+      logger.warn(
+        { runId, heapMb, limitMb: limits.maxHeapMb },
+        "ooda.cycle.heap_exceeded"
+      );
+      rootSpan.setAttribute("vauban.ooda.status", "skipped");
+      rootSpan.setAttribute(
+        "vauban.ooda.skip_reason",
+        `heap_exceeded:${heapMb.toFixed(1)}mb`
+      );
+      rootSpan.setStatus({ code: SpanStatusCode.OK });
+      rootSpan.end();
+      this._cyclesCompleted += 1;
+      this._lastCycleAt = new Date().toISOString();
+      return { runId, status: "skipped" };
+    }
+
+    // ── Phase chain ────────────────────────────────────────────────────────
+    try {
+      // Inject initialContext into observe phase for event-driven activation
+      const observeInput: void | Record<string, unknown> = initialContext
+        ? (initialContext as unknown as void)
+        : undefined;
+      const obs = await this._runOodaPhase(
+        this._config.phases.observe,
+        observeInput,
+        ctx as OODAContext,
+        tracer
+      );
+      const oriented = await this._runOodaPhase(
+        this._config.phases.orient,
+        obs as TObs,
+        ctx as OODAContext,
+        tracer
+      );
+      const decision = await this._runOodaPhase(
+        this._config.phases.decide,
+        oriented as TOrient,
+        ctx as OODAContext,
+        tracer
+      );
+      const action = await this._runOodaPhase(
+        this._config.phases.act,
+        decision as TDecision,
+        ctx as OODAContext,
+        tracer,
+        { hitlGate: this._config.phases.act.hitlGate === true }
+      );
+
+      // Optional 6th phase — self-critique between act and feedback
+      const reflectInput: TAction = action as TAction;
+      const feedbackInput: TAction = this._config.phases.reflect
+        ? ((await this._runOodaPhase(
+            this._config.phases.reflect as PhaseDef<
+              TAction & { decision: TDecision },
+              TFeedback
+            >,
+            { ...reflectInput, decision: decision as TDecision },
+            ctx as OODAContext,
+            tracer
+          )) as unknown as TAction)
+        : (action as TAction);
+
+      const feedback = await this._runOodaPhase(
+        this._config.phases.feedback,
+        feedbackInput as TAction,
+        ctx as OODAContext,
+        tracer
+      );
+
+      if (this._config.outcomeMapping) {
+        try {
+          const outcome = this._config.outcomeMapping(feedback as TFeedback);
+          if (outcome) {
+            logger.info(
+              { runId, outcome_type: outcome.outcome_type },
+              "ooda.cycle.outcome"
+            );
+          }
+        } catch (e) {
+          logger.error(
+            { runId, err: (e as Error).message },
+            "ooda.cycle.outcome_mapping_failed"
+          );
+        }
+      }
+
+      rootSpan.setAttribute("vauban.ooda.status", "succeeded");
+      rootSpan.setAttribute("vauban.ooda.steps", stepsThisCycle);
+      rootSpan.setStatus({ code: SpanStatusCode.OK });
+      rootSpan.end();
+      this._cyclesCompleted += 1;
+      this._lastCycleAt = new Date().toISOString();
+      return { runId, status: "succeeded" };
+    } catch (err) {
+      logger.error(
+        {
+          runId,
+          agentId: this._config.agentId,
+          err: (err as Error).message,
+        },
+        "ooda.cycle.failed"
+      );
+      rootSpan.setAttribute("vauban.ooda.status", "failed");
+      rootSpan.setAttribute("vauban.ooda.steps", stepsThisCycle);
+      rootSpan.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: (err as Error).message,
+      });
+      rootSpan.recordException(err as Error);
+      rootSpan.end();
+      this._cyclesCompleted += 1;
+      this._lastCycleAt = new Date().toISOString();
+      return { runId, status: "failed" };
+    }
+  }
+
+  /**
+   * Execute one full cycle, pushing `CycleEvent` to `sink` as they occur.
+   * Used by `streamCycle()` to decouple event emission from async generator
+   * mechanics. Single-pass — each phase runs exactly once.
+   */
+  private async _runCycleWithSink(
+    runId: string,
+    cycleIndex: number,
+    executionMode: ExecutionMode,
+    sink: (evt: CycleEvent) => void,
+    _initialContext?: Record<string, unknown>
+  ): Promise<void> {
+    const cycleStart = Date.now();
+    const isReplay = false;
+    const logger = this._config.logger ?? NOOP_LOGGER;
+
+    // ── OTel: agent-level span for the full stream cycle ────────────────────
+    const tracer = getTracer("vauban-agent-sdk.ooda");
+    const rootSpan = agentSpan(tracer, {
+      agentId: this._config.agentId,
+      agentVersion: this._config.agentVersion ?? "0.0.0",
+      runId,
+    });
+    rootSpan.setAttribute("vauban.ooda.cycle_index", cycleIndex);
+    rootSpan.setAttribute("vauban.ooda.execution_mode", executionMode);
+    rootSpan.setAttribute("vauban.ooda.stream", true);
+
+    // Step counter — anti-pattern #9 (maxStepsPerCycle).
+    let stepsThisCycle = 0;
+    const limits = this._limits;
+
+    const baseInsertStep = this._config.insertStepImpl ?? defaultInsertStep();
+    const insertStep: OODAContext["insertStep"] = async (input) => {
+      stepsThisCycle += 1;
+      if (stepsThisCycle > limits.maxStepsPerCycle) {
+        throw new Error(
+          `OODA: maxStepsPerCycle exceeded (${limits.maxStepsPerCycle})`
+        );
+      }
+      return baseInsertStep(input);
+    };
+
+    // Hot-reload config.
+    let liveConfig: TConfig = (this._config.config ??
+      ({} as TConfig)) as TConfig;
+    if (this._config.configLoader) {
+      try {
+        liveConfig = await this._config.configLoader.get(this._config.agentId);
+      } catch (e) {
+        logger.warn(
+          { agentId: this._config.agentId, err: (e as Error).message },
+          "ooda.stream.config_loader_failed — using static config"
+        );
+      }
+    }
+
+    const ctx: OODAContext<TConfig> = Object.freeze({
+      agentId: this._config.agentId,
+      runId,
+      cycleIndex,
+      executionMode,
+      isReplay,
+      config: liveConfig,
+      configLoader: this._config.configLoader,
+      db: this._config.db,
+      skills: this._config.skills ?? EMPTY_SKILL_REGISTRY,
+      logger,
+      deps: this._config.deps ?? {},
+      insertStep,
+      completeStep: this._config.completeStepImpl ?? defaultCompleteStep(),
+      errorStep: this._config.errorStepImpl ?? defaultErrorStep(),
+      notifySlack: this._config.notifySlackImpl ?? defaultNotifySlack(),
+    });
+
+    // ── Session guards ───────────────────────────────────────────────────
+    const sessionResult = await this._checkSessionGuards(
+      this._config.sessionGuards ?? []
+    );
+    if (!sessionResult.ok) {
+      const reason = sessionResult.reason ?? "session_guard";
+      sink({
+        type: "guard_tripped",
+        runId,
+        cycleIndex,
+        guard: "session",
+        reason,
+        ts: Date.now(),
+      });
+      sink({
+        type: "cycle_skipped",
+        runId,
+        cycleIndex,
+        reason,
+        ts: Date.now(),
+      });
+      rootSpan.setAttribute("vauban.ooda.status", "skipped");
+      rootSpan.setAttribute("vauban.ooda.skip_reason", reason);
+      rootSpan.setStatus({ code: SpanStatusCode.OK });
+      rootSpan.end();
+      this._cyclesCompleted += 1;
+      this._lastCycleAt = new Date().toISOString();
+      return;
+    }
+
+    // ── Risk guards ──────────────────────────────────────────────────────
+    const riskResult = await this._checkRiskGuards(
+      this._config.riskGuards ?? [],
+      ctx
+    );
+    if (!riskResult.ok) {
+      const reason = riskResult.reason ?? "risk_guard";
+      sink({
+        type: "guard_tripped",
+        runId,
+        cycleIndex,
+        guard: "risk",
+        reason,
+        ts: Date.now(),
+      });
+      sink({
+        type: "cycle_skipped",
+        runId,
+        cycleIndex,
+        reason,
+        ts: Date.now(),
+      });
+      rootSpan.setAttribute("vauban.ooda.status", "skipped");
+      rootSpan.setAttribute("vauban.ooda.skip_reason", reason);
+      rootSpan.setStatus({ code: SpanStatusCode.OK });
+      rootSpan.end();
+      this._cyclesCompleted += 1;
+      this._lastCycleAt = new Date().toISOString();
+      return;
+    }
+
+    // ── Heap watermark ────────────────────────────────────────────────────
+    const heapMb = process.memoryUsage().heapUsed / (1024 * 1024);
+    if (heapMb > limits.maxHeapMb) {
+      const reason = `heap_exceeded:${heapMb.toFixed(1)}mb`;
+      sink({
+        type: "guard_tripped",
+        runId,
+        cycleIndex,
+        guard: "heap",
+        reason,
+        ts: Date.now(),
+      });
+      sink({
+        type: "cycle_skipped",
+        runId,
+        cycleIndex,
+        reason,
+        ts: Date.now(),
+      });
+      rootSpan.setAttribute("vauban.ooda.status", "skipped");
+      rootSpan.setAttribute("vauban.ooda.skip_reason", reason);
+      rootSpan.setStatus({ code: SpanStatusCode.OK });
+      rootSpan.end();
+      this._cyclesCompleted += 1;
+      this._lastCycleAt = new Date().toISOString();
+      return;
+    }
+
+    // ── Phase runner (single-pass, emits events via sink) ─────────────────
+    const runPhaseWithSink = async <I, O>(
+      phase: PhaseDef<I, O>,
+      input: I,
+      phaseCtx: OODAContext,
+      phaseOpts?: { hitlGate?: boolean }
+    ): Promise<O> => {
+      const phaseName = phase.type;
+      const phaseSpan = tracer.startSpan(`ooda.phase.${phaseName}`);
+      phaseSpan.setAttribute("vauban.ooda.run_id", runId);
+      phaseSpan.setAttribute("vauban.ooda.phase", phaseName);
+
+      sink({
+        type: "phase_start",
+        runId,
+        cycleIndex,
+        phase: phaseName,
+        ts: Date.now(),
+      });
+      const phaseStart = Date.now();
+
+      const step = await phaseCtx.insertStep({
+        type: phase.type,
+        phase: phaseName,
+        payload: { input_hash: hashPayload(input) },
+      });
+      phaseSpan.setAttribute("vauban.ooda.step_id", step.stepId);
+
+      try {
+        const out = await withPhaseTimeout(
+          phase.fn(input, phaseCtx),
+          this._limits.phaseTimeoutMs
+        );
+
+        if (phaseOpts?.hitlGate === true && this._config.waitForHITL) {
+          sink({
+            type: "hitl_waiting",
+            runId,
+            cycleIndex,
+            stepId: step.stepId,
+            payloadHash: hashPayload(out),
+            ts: Date.now(),
+          });
+          await this._config.waitForHITL({
+            runId: phaseCtx.runId,
+            stepId: step.stepId,
+            payload: out,
+          });
+          sink({
+            type: "hitl_approved",
+            runId,
+            cycleIndex,
+            stepId: step.stepId,
+            ts: Date.now(),
+          });
+        }
+
+        await phaseCtx.completeStep(step.stepId, {
+          output_hash: hashPayload(out),
+        });
+
+        const durationMs = Date.now() - phaseStart;
+        phaseSpan.setAttribute("vauban.ooda.phase_duration_ms", durationMs);
+        phaseSpan.setStatus({ code: SpanStatusCode.OK });
+        phaseSpan.end();
+
+        sink({
+          type: "phase_complete",
+          runId,
+          cycleIndex,
+          phase: phaseName,
+          durationMs,
+          ts: Date.now(),
+        });
+
+        return out;
+      } catch (err) {
+        await phaseCtx.errorStep(step.stepId, err as Error);
+        const durationMs = Date.now() - phaseStart;
+        phaseSpan.setAttribute("vauban.ooda.phase_duration_ms", durationMs);
+        phaseSpan.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: (err as Error).message,
+        });
+        phaseSpan.recordException(err as Error);
+        phaseSpan.end();
+
+        sink({
+          type: "phase_error",
+          runId,
+          cycleIndex,
+          phase: phaseName,
+          error: { message: (err as Error).message },
+          ts: Date.now(),
+        });
+        throw err;
+      }
+    };
+
+    // ── Phase chain ──────────────────────────────────────────────────────
+    try {
+      const obs = await runPhaseWithSink(
+        this._config.phases.observe,
+        undefined as void,
+        ctx as OODAContext
+      );
+      const oriented = await runPhaseWithSink(
+        this._config.phases.orient,
+        obs as TObs,
+        ctx as OODAContext
+      );
+      const decision = await runPhaseWithSink(
+        this._config.phases.decide,
+        oriented as TOrient,
+        ctx as OODAContext
+      );
+      const action = await runPhaseWithSink(
+        this._config.phases.act,
+        decision as TDecision,
+        ctx as OODAContext,
+        { hitlGate: this._config.phases.act.hitlGate === true }
+      );
+
+      // Optional 6th phase — self-critique between act and feedback.
+      // When omitted, move directly from act → feedback.
+      const reflectInput: TAction = action as TAction;
+      const feedbackInput: TAction = this._config.phases.reflect
+        ? ((await runPhaseWithSink(
+            this._config.phases.reflect as PhaseDef<
+              TAction & { decision: TDecision },
+              TFeedback
+            >,
+            { ...reflectInput, decision: decision as TDecision },
+            ctx as OODAContext
+          )) as unknown as TAction)
+        : (action as TAction);
+
+      const feedback = await runPhaseWithSink(
+        this._config.phases.feedback,
+        feedbackInput as TAction,
+        ctx as OODAContext
+      );
+
+      // Outcome mapping (optional, non-fatal in stream mode).
+      if (this._config.outcomeMapping) {
+        try {
+          const outcome = this._config.outcomeMapping(feedback as TFeedback);
+          if (outcome) {
+            logger.info(
+              { runId, outcome_type: outcome.outcome_type },
+              "ooda.stream.outcome"
+            );
+          }
+        } catch (e) {
+          logger.error(
+            { runId, err: (e as Error).message },
+            "ooda.stream.outcome_mapping_failed"
+          );
+        }
+      }
+
+      this._cyclesCompleted += 1;
+      this._lastCycleAt = new Date().toISOString();
+      rootSpan.setAttribute("vauban.ooda.status", "succeeded");
+      rootSpan.setAttribute("vauban.ooda.steps", stepsThisCycle);
+      rootSpan.setAttribute("vauban.ooda.duration_ms", Date.now() - cycleStart);
+      rootSpan.setStatus({ code: SpanStatusCode.OK });
+      rootSpan.end();
+      sink({
+        type: "cycle_complete",
+        runId,
+        cycleIndex,
+        status: "succeeded",
+        durationMs: Date.now() - cycleStart,
+        ts: Date.now(),
+      });
+
+      // ── A4 timestamping (optional, non-blocking) ──────────────────────────
+      // TODO(A-DEMO): rootHash will be provided by the Trace builder once A-DEMO
+      // wires buildChain() into the cycle. Until then, no TSA call is made.
+      //
+      // When rootHash is available (A-DEMO integration), replace the block below:
+      //
+      //   if (this._config.timestamping?.when === 'on-cycle-complete') {
+      //     try {
+      //       await this._config.timestamping.port.request(rootHash);
+      //     } catch (tsaErr) {
+      //       sink({ type: 'timestamp_pending', runId, cycleIndex, rootHash, ts: Date.now() });
+      //       if (this._config.timestamping.queue &&
+      //           this._config.timestamping.queueHmacKeyProvider &&
+      //           this._config.timestamping.queueHmacKeyId) {
+      //         await this._config.timestamping.queue.enqueue(
+      //           { runId, rootHash, queuedAt: Date.now() },
+      //           this._config.timestamping.queueHmacKeyProvider,
+      //           this._config.timestamping.queueHmacKeyId,
+      //         ).catch(() => {}); // best-effort
+      //       }
+      //     }
+      //   }
+    } catch (err) {
+      logger.error(
+        { runId, agentId: this._config.agentId, err: (err as Error).message },
+        "ooda.stream.cycle.failed"
+      );
+      this._cyclesCompleted += 1;
+      this._lastCycleAt = new Date().toISOString();
+      rootSpan.setAttribute("vauban.ooda.status", "failed");
+      rootSpan.setAttribute("vauban.ooda.steps", stepsThisCycle);
+      rootSpan.setAttribute("vauban.ooda.duration_ms", Date.now() - cycleStart);
+      rootSpan.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: (err as Error).message,
+      });
+      rootSpan.recordException(err as Error);
+      rootSpan.end();
+      sink({
+        type: "cycle_error",
+        runId,
+        cycleIndex,
+        error: { message: (err as Error).message },
+        ts: Date.now(),
+      });
+      sink({
+        type: "cycle_complete",
+        runId,
+        cycleIndex,
+        status: "failed",
+        durationMs: Date.now() - cycleStart,
+        ts: Date.now(),
+      });
+    }
+  }
+
+  /**
+   * Run a single OODA phase with OTel span instrumentation. Used by runCycle().
+   */
+  private async _runOodaPhase<I, O>(
+    phase: PhaseDef<I, O>,
+    input: I,
+    ctx: OODAContext,
+    tracer: ReturnType<typeof getTracer>,
+    opts?: { hitlGate?: boolean }
+  ): Promise<O> {
+    const phaseSpan = tracer.startSpan(`ooda.phase.${phase.type}`);
+    phaseSpan.setAttribute("vauban.ooda.run_id", ctx.runId);
+    phaseSpan.setAttribute("vauban.ooda.phase", phase.type);
+    const phaseStart = Date.now();
+
+    const step = await ctx.insertStep({
+      type: phase.type,
+      phase: phase.type,
+      payload: { input_hash: hashPayload(input) },
+    });
+    phaseSpan.setAttribute("vauban.ooda.step_id", step.stepId);
+
+    try {
+      const out = await withPhaseTimeout(
+        phase.fn(input, ctx),
+        this._limits.phaseTimeoutMs
+      );
+
+      if (opts?.hitlGate === true && this._config.waitForHITL) {
+        await this._config.waitForHITL({
+          runId: ctx.runId,
+          stepId: step.stepId,
+          payload: out,
+        });
+      }
+
+      await ctx.completeStep(step.stepId, {
+        output_hash: hashPayload(out),
+      });
+
+      phaseSpan.setAttribute(
+        "vauban.ooda.phase_duration_ms",
+        Date.now() - phaseStart
+      );
+      phaseSpan.setStatus({ code: SpanStatusCode.OK });
+      phaseSpan.end();
+      return out;
+    } catch (err) {
+      await ctx.errorStep(step.stepId, err as Error);
+      phaseSpan.setAttribute(
+        "vauban.ooda.phase_duration_ms",
+        Date.now() - phaseStart
+      );
+      phaseSpan.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: (err as Error).message,
+      });
+      phaseSpan.recordException(err as Error);
+      phaseSpan.end();
+      throw err;
+    }
+  }
+
+  private async _checkSessionGuards(
+    guards: readonly SessionGuard[]
+  ): Promise<{ ok: boolean; reason?: string }> {
+    const now = new Date();
+    for (const g of guards) {
+      const active = await g.isActive(now);
+      if (!active) return { ok: false, reason: `session:${g.name}` };
+    }
+    return { ok: true };
+  }
+
+  private async _checkRiskGuards(
+    guards: readonly RiskGuard[],
+    ctx: OODAContext
+  ): Promise<{ ok: boolean; reason?: string }> {
+    for (const g of guards) {
+      const r = await g.check(ctx);
+      if (!r.proceed) {
+        return { ok: false, reason: `risk:${g.name}:${r.reason ?? "tripped"}` };
+      }
+    }
+    return { ok: true };
+  }
+}
+
+/** Cheap structural hash — just JSON length + first chars, NOT crypto. */
+function hashPayload(v: unknown): string {
+  try {
+    const s = JSON.stringify(v);
+    if (!s) return "null";
+    return `len=${s.length}:${s.slice(0, 32)}`;
+  } catch {
+    return "unserializable";
+  }
+}