@vauban-org/agent-sdk 0.16.0

package/src/orchestration/ooda/audit-log.ts

@@ -0,0 +1,57 @@
+/**
+ * OODA HITL audit-log helper — sprint-525:quick-2.
+ *
+ * Records a human's verdict on a HITL approval request. This is the
+ * "resolve" side of the gate persisted by `waitForHITLApproval`: the
+ * gate INSERTs a `pending` row, this helper UPDATEs it to the final
+ * decision so the polling loop can observe the transition.
+ *
+ * The dashboard or operator UI calls this exactly once per request.
+ * The UPDATE is gated on `status='pending'` so a double-resolve from
+ * concurrent UIs is a no-op for the second writer.
+ *
+ * @public
+ */
+
+import type { DbClient } from "../../tracking/agent-run-tracker.js";
+
+export type HITLDecision = "approved" | "rejected";
+
+/**
+ * Record a HITL verdict in `hitl_approvals`. Returns silently — the
+ * polling gate observes the row transition on its next tick.
+ *
+ * Concurrent calls: only the first one transitions the row (status
+ * filter on UPDATE). Subsequent callers find no `pending` row and the
+ * UPDATE simply affects 0 rows.
+ */
+export async function recordHITLDecision(
+  db: DbClient,
+  hitlId: string,
+  decision: HITLDecision,
+  resolverUserId: string,
+  rationale?: string,
+): Promise<void> {
+  if (typeof hitlId !== "string" || hitlId.length === 0) {
+    throw new Error("[ooda/audit-log] hitlId must be a non-empty string");
+  }
+  if (decision !== "approved" && decision !== "rejected") {
+    throw new Error(
+      `[ooda/audit-log] decision must be 'approved' | 'rejected'. Got: ${String(decision)}`,
+    );
+  }
+  if (typeof resolverUserId !== "string" || resolverUserId.length === 0) {
+    throw new Error("[ooda/audit-log] resolverUserId must be a non-empty string");
+  }
+
+  await db.query(
+    `UPDATE hitl_approvals
+        SET status = $2,
+            resolved_by = $3,
+            rationale = $4,
+            resolved_at = now()
+      WHERE id = $1
+        AND status = 'pending'`,
+    [hitlId, decision, resolverUserId, rationale ?? null],
+  );
+}

package/src/orchestration/ooda/brain-context.ts

@@ -0,0 +1,269 @@
+/**
+ * Brain context auto-injection for the OODA ORIENT phase — sprint-525:quick-4.
+ *
+ * D1+D2 systemic fix: instead of every OODA agent calling Brain manually
+ * during ORIENT, this primitive wraps the orient phase function so that:
+ *
+ *   1. A Brain query is built from the observe input (`options.query(input)`).
+ *   2. The `query_knowledge` skill (or an injected `fetchBrainContext`) is
+ *      called once, returning top-K chunks above `minSimilarity`.
+ *   3. The chunks + their entry IDs are injected into the orient input as
+ *      `OrientInputWithBrain<TObs>` — orient code stays decoupled from
+ *      Brain MCP wiring.
+ *   4. `mcp_call_hash` + `retrieval_proof_hash` are emitted via the OODA
+ *      context's step-recording side-effect (a retrieval `run_step` row),
+ *      so `assembleRunCertificate` populates `brain_context_refs`
+ *      automatically — no per-agent boilerplate.
+ *
+ * Replay safety: when `ctx.isReplay === true`, the wrapper consults the
+ * injected `replayChunks` (if provided) and emits no MCP call. This keeps
+ * deterministic re-execution stable.
+ *
+ * @public
+ */
+
+import type { OODAContext } from "./types.js";
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+/**
+ * A single chunk returned from a Brain retrieval. `entry_id` is the only
+ * field consumed by certificate assembly; the rest is forwarded to the
+ * wrapped orient phase.
+ */
+export interface BrainChunk {
+  readonly entry_id: string;
+  readonly content: string;
+  readonly similarity: number;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result of a Brain MCP call wrapped by `callBrainTool` (server-side).
+ * Re-exported in this module for SDK consumers that build their own
+ * `fetchBrainContext` impl.
+ */
+export interface BrainCallResult<T> {
+  readonly result: T;
+  readonly mcp_call_hash: string;
+  readonly retrieval_proof_hash: string;
+}
+
+/**
+ * Returned by the circuit breaker when Brain is unreachable (open circuit).
+ * All downstream decisions MUST carry `[UNGROUNDED: brain]` markers.
+ */
+export interface DegradedResponse {
+  readonly status: "degraded";
+  readonly fallback: "UNGROUNDED";
+  readonly reason: string;
+  readonly stale_since: string;
+}
+
+/**
+ * Discriminator: narrow a fetch result to DegradedResponse or BrainCallResult.
+ */
+export function isDegradedResponse(r: unknown): r is DegradedResponse {
+  return (
+    typeof r === "object" &&
+    r !== null &&
+    "status" in r &&
+    (r as DegradedResponse).status === "degraded"
+  );
+}
+
+/**
+ * Configuration for the wrapper.
+ *
+ * `enabled: false` short-circuits to an empty context — orient still
+ * receives `OrientInputWithBrain` but with `brainContext: []`.
+ */
+export interface BrainContextOptions<TInput> {
+  readonly enabled: boolean;
+  /** Build the Brain query string from the observe phase output. */
+  readonly query: (input: TInput) => string;
+  /** Default 5. Bounded by the BrainPort `query_knowledge` page size. */
+  readonly topK?: number;
+  /** Default 0.7. Chunks below this similarity are filtered out. */
+  readonly minSimilarity?: number;
+  /**
+   * Host-injected Brain MCP fetcher. When omitted and `enabled === true`,
+   * the wrapper throws — encouraging callers to wire a `BrainPort`-backed
+   * adapter at boot time. The fetcher must:
+   *   - Throw `BrainSkillNotConfiguredError` when BRAIN_MCP_URL is unset.
+   *   - Return `BrainCallResult` with the two hashes computed via
+   *     JCS-canonicalized SHA-256 (RFC 8785).
+   */
+  readonly fetchBrainContext?: (
+    query: string,
+    topK: number
+  ) => Promise<BrainCallResult<BrainChunk[]> | DegradedResponse>;
+  /**
+   * Optional deterministic replay fixture. When `ctx.isReplay === true`,
+   * the wrapper returns these chunks instead of calling Brain.
+   */
+  readonly replayChunks?: BrainChunk[];
+}
+
+/**
+ * The augmented input the wrapped orient phase receives. `raw` is the
+ * original observe output; `brainContext` is the filtered chunk list;
+ * `brainContextRefs` is the ordered, deduped list of entry IDs that
+ * `assembleRunCertificate` will lift onto the proof certificate.
+ */
+export interface OrientInputWithBrain<TObs> {
+  readonly raw: TObs;
+  readonly brainContext: BrainChunk[];
+  readonly brainContextRefs: string[];
+}
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+export class BrainSkillNotConfiguredError extends Error {
+  constructor() {
+    super(
+      "Brain skill requires BRAIN_MCP_URL env var. " +
+        "See https://command.vauban.tech/docs/sdk/brain-config"
+    );
+    this.name = "BrainSkillNotConfiguredError";
+  }
+}
+
+// ─── Defaults ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_TOP_K = 5;
+const DEFAULT_MIN_SIMILARITY = 0.7;
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Filter chunks by `minSimilarity`, sort by descending similarity, then
+ * truncate to `topK`. Pure — no side-effects.
+ */
+function filterAndRank(
+  chunks: readonly BrainChunk[],
+  topK: number,
+  minSimilarity: number
+): BrainChunk[] {
+  return chunks
+    .filter((c) => c.similarity >= minSimilarity)
+    .slice()
+    .sort((a, b) => b.similarity - a.similarity)
+    .slice(0, topK);
+}
+
+/**
+ * Deduplicate entry IDs while preserving first-seen order.
+ */
+function dedupePreserveOrder(ids: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const id of ids) {
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push(id);
+    }
+  }
+  return out;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Wraps an orient phase function to auto-inject Brain context.
+ *
+ * The wrapped function:
+ *   1. Inserts a `retrieval` step (pending).
+ *   2. Calls `fetchBrainContext` (unless disabled or replaying).
+ *   3. Filters/sorts/truncates chunks per config.
+ *   4. Completes the retrieval step with `mcp_call_hash` + entry IDs in
+ *      the payload — `assembleRunCertificate` lifts entry IDs onto the
+ *      certificate's `brain_context_refs`.
+ *   5. Invokes the inner orient with `OrientInputWithBrain<TObs>`.
+ *
+ * Strict typing: the inner orient remains parametric in `TObs`/`TOrient`,
+ * so existing OODA `PhaseDef<TObs, TOrient>` consumers can adopt this
+ * wrapper without rewriting types — they swap the `fn` field for the
+ * wrapper's return value.
+ */
+export function withBrainContext<TObs, TOrient>(
+  options: BrainContextOptions<TObs>,
+  orientFn: (
+    input: OrientInputWithBrain<TObs>,
+    ctx: OODAContext
+  ) => Promise<TOrient>
+): (input: TObs, ctx: OODAContext) => Promise<TOrient> {
+  const topK = options.topK ?? DEFAULT_TOP_K;
+  const minSimilarity = options.minSimilarity ?? DEFAULT_MIN_SIMILARITY;
+
+  return async (input, ctx) => {
+    // Fast path: disabled → orient receives an empty context, no step row.
+    if (!options.enabled) {
+      return orientFn(
+        { raw: input, brainContext: [], brainContextRefs: [] },
+        ctx
+      );
+    }
+
+    const query = options.query(input);
+    const { stepId } = await ctx.insertStep({
+      type: "retrieval",
+      phase: "orient.brain-context",
+      payload: { query, topK, minSimilarity },
+    });
+
+    let chunks: BrainChunk[];
+    let mcpCallHash: string | null = null;
+    let retrievalProofHash: string | null = null;
+    let degradedResponse: DegradedResponse | null = null;
+
+    try {
+      if (ctx.isReplay) {
+        chunks = filterAndRank(options.replayChunks ?? [], topK, minSimilarity);
+      } else {
+        if (!options.fetchBrainContext) {
+          throw new BrainSkillNotConfiguredError();
+        }
+        const call = await options.fetchBrainContext(query, topK);
+
+        // Circuit breaker: Brain is down → return empty context instead of crashing
+        if (isDegradedResponse(call)) {
+          degradedResponse = call;
+          chunks = [];
+        } else {
+          mcpCallHash = call.mcp_call_hash;
+          retrievalProofHash = call.retrieval_proof_hash;
+          chunks = filterAndRank(call.result, topK, minSimilarity);
+        }
+      }
+    } catch (err) {
+      await ctx.errorStep(
+        stepId,
+        err instanceof Error ? err : new Error(String(err))
+      );
+      throw err;
+    }
+
+    const brainContextRefs = dedupePreserveOrder(chunks.map((c) => c.entry_id));
+
+    // Complete the retrieval step. The OODA host owns mcp_call_hash
+    // column writing; the SDK contract is to surface it via payload so
+    // the host adapter (insertStepImpl/completeStepImpl) can lift it onto
+    // the run_step row when persisting.
+    await ctx.completeStep(stepId, {
+      query,
+      brain_entry_ids: brainContextRefs,
+      mcp_call_hash: mcpCallHash,
+      retrieval_proof_hash: retrievalProofHash,
+      chunk_count: chunks.length,
+      ...(degradedResponse
+        ? { degraded: true, fallback: degradedResponse.fallback }
+        : {}),
+    });
+
+    return orientFn(
+      { raw: input, brainContext: chunks, brainContextRefs },
+      ctx
+    );
+  };
+}

package/src/orchestration/ooda/child-agent.ts

@@ -0,0 +1,60 @@
+/**
+ * ChildAgentPort — Supervisor-Worker pattern for multi-agent orchestration.
+ *
+ * Async-first design: `spawnAsync` returns a `workerId` immediately; the worker
+ * publishes a `worker.completed` CloudEvent on the bus when done. The supervisor
+ * picks it up in its next `observe()` cycle — never blocking.
+ *
+ * `spawnSync` is available for short tasks (< 10s) but should be used sparingly.
+ *
+ * Cycle detection: `maxChainDepth` (default 3) prevents infinite agent chains.
+ * If `handoffChain.length >= maxChainDepth`, the port throws `HandoffCycleError`.
+ *
+ * @public
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────────
+
+export interface ChildAgentOptions {
+  /** Target agent identifier. */
+  agentId: string;
+  /** Task payload — arbitrary JSON-serializable record. */
+  task: Record<string, unknown>;
+  /** Max wait time for spawnSync (default: 10_000 ms). */
+  timeoutMs?: number;
+  /** Chain of agent IDs that have handed off to this worker. */
+  handoffChain?: string[];
+  /** Max chain depth before HandoffCycleError (default: 3). */
+  maxChainDepth?: number;
+}
+
+export interface ChildAgentResult {
+  workerId: string;
+  status: "accepted" | "completed" | "failed" | "timeout";
+  output?: unknown;
+  error?: string;
+}
+
+// ─── Port ───────────────────────────────────────────────────────────────────────
+
+export interface ChildAgentPort {
+  /**
+   * Fire-and-forget: spawn a worker, get workerId immediately.
+   *
+   * The worker publishes a `worker.completed` CloudEvent on the event bus
+   * when done. The supervisor picks it up in its next observe() cycle.
+   *
+   * Throws `HandoffCycleError` if `handoffChain.length >= maxChainDepth`.
+   */
+  spawnAsync(opts: ChildAgentOptions): Promise<{ workerId: string }>;
+
+  /**
+   * Await result synchronously. Use only for short tasks (< 10s).
+   *
+   * Blocks the supervisor cycle during worker execution. Prefer `spawnAsync`
+   * for all non-trivial work.
+   *
+   * Throws `HandoffCycleError` if `handoffChain.length >= maxChainDepth`.
+   */
+  spawnSync(opts: ChildAgentOptions): Promise<ChildAgentResult>;
+}

package/src/orchestration/ooda/cron-schedule.ts

@@ -0,0 +1,115 @@
+/**
+ * CronExpression scheduling — SessionGuard based on cron expressions.
+ *
+ * Replaces fixed-interval scheduling with cron-based patterns:
+ * "every Monday 9am", "first day of month", "every weekday at 8am".
+ *
+ * The `cronSessionGuard(expr)` returns a `SessionGuard` compatible with
+ * the existing OODA guard system — zero boilerplate wiring.
+ *
+ * @public
+ */
+
+import type { SessionGuard } from "./types.js";
+
+// ─── Cron Parser ────────────────────────────────────────────────────────────────
+
+/**
+ * Minimal cron expression parser (5-field: minute hour day-of-month month day-of-week).
+ *
+ * Supports wildcards, specific values, ranges, steps, and lists.
+ * Does NOT support L, W, hash, question mark, or year field.
+ */
+function parseField(field: string, min: number, max: number): Set<number> {
+  const values = new Set<number>();
+
+  if (field === "*") {
+    for (let i = min; i <= max; i++) values.add(i);
+    return values;
+  }
+
+  const parts = field.split(",");
+  for (const part of parts) {
+    const [range, stepStr] = part.split("/");
+    const step = stepStr ? parseInt(stepStr, 10) : 1;
+
+    let rangeMin: number;
+    let rangeMax: number;
+
+    if (range === "*") {
+      rangeMin = min;
+      rangeMax = max;
+    } else if (range.includes("-")) {
+      const [a, b] = range.split("-");
+      rangeMin = parseInt(a, 10);
+      rangeMax = parseInt(b, 10);
+    } else {
+      rangeMin = parseInt(range, 10);
+      rangeMax = rangeMin;
+    }
+
+    for (let i = rangeMin; i <= rangeMax; i += step) {
+      if (i >= min && i <= max) values.add(i);
+    }
+  }
+
+  return values;
+}
+
+interface CronFields {
+  minutes: Set<number>;
+  hours: Set<number>;
+  daysOfMonth: Set<number>;
+  months: Set<number>;
+  daysOfWeek: Set<number>;
+}
+
+function parseCronExpression(expr: string): CronFields {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`Invalid cron expression "${expr}": expected 5 fields, got ${parts.length}`);
+  }
+
+  return {
+    minutes: parseField(parts[0], 0, 59),
+    hours: parseField(parts[1], 0, 23),
+    daysOfMonth: parseField(parts[2], 1, 31),
+    months: parseField(parts[3], 1, 12),
+    daysOfWeek: parseField(parts[4], 0, 6), // 0=Sunday
+  };
+}
+
+function cronMatches(expr: string, date: Date): boolean {
+  const fields = parseCronExpression(expr);
+  return (
+    fields.minutes.has(date.getUTCMinutes()) &&
+    fields.hours.has(date.getUTCHours()) &&
+    fields.daysOfMonth.has(date.getUTCDate()) &&
+    fields.months.has(date.getUTCMonth() + 1) &&
+    fields.daysOfWeek.has(date.getUTCDay())
+  );
+}
+
+// ─── Session Guard ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a SessionGuard from a cron expression.
+ *
+ * The guard returns `isActive: true` when the current time matches the
+ * cron expression. This gates whether a cycle should run at all.
+ *
+ * @example
+ * ```typescript
+ * // Run every weekday at 9:00 AM UTC
+ * const guard = cronSessionGuard("0 9 * * 1-5");
+ * ```
+ */
+export function cronSessionGuard(expr: string): SessionGuard {
+  // Validate at construction time
+  parseCronExpression(expr);
+
+  return {
+    name: `cron:${expr}`,
+    isActive: async (at: Date) => cronMatches(expr, at),
+  };
+}

package/src/orchestration/ooda/debate.ts

@@ -0,0 +1,100 @@
+/**
+ * Multi-Agent Debate — Dual LLM in orient/decide phases.
+ *
+ * Pattern: Strategist (thesis) + Skeptic (antithesis) → Synthesizer → synthesis.
+ *
+ * The debate engine runs two adversarial LLM stances against each other
+ * and produces a consensus score + plan. Used for high-stakes decisions
+ * where a single LLM's blind spots are unacceptable (legal review,
+ * financial allocation, security decisions).
+ *
+ * Reference: command-center/docs/specs/debate-engine-spec.md
+ *
+ * @public
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────────
+
+export interface DebateStance {
+  /** The argument / position. */
+  content: string;
+  /** Confidence score (0.0 - 1.0). */
+  confidence: number;
+  /** Key points supporting this stance. */
+  keyPoints: string[];
+  /** Identified risks or weaknesses. */
+  risks: string[];
+}
+
+export interface DebateSynthesis {
+  /** Synthesized conclusion. */
+  conclusion: string;
+  /** Consensus score (0.0 = total disagreement, 1.0 = full agreement). */
+  consensusScore: number;
+  /** Recommended action. */
+  recommendation: string;
+  /** Key trade-offs identified. */
+  tradeoffs: string[];
+  /** Whether HITL escalation is recommended. */
+  hitlRecommended: boolean;
+}
+
+export interface DebateResult {
+  thesis: DebateStance;
+  antithesis: DebateStance;
+  synthesis: DebateSynthesis;
+  /** Number of debate rounds. */
+  rounds: number;
+}
+
+export interface DebateConfig {
+  /** The question or decision to debate. */
+  question: string;
+  /** Context / background information. */
+  context?: string;
+  /** Max debate rounds (default: 1). */
+  maxRounds?: number;
+  /** LLM function for the strategist (thesis). */
+  strategist: (question: string, context?: string) => Promise<DebateStance>;
+  /** LLM function for the skeptic (antithesis). */
+  skeptic: (question: string, thesis: DebateStance, context?: string) => Promise<DebateStance>;
+  /** LLM function for the synthesizer. */
+  synthesizer: (question: string, thesis: DebateStance, antithesis: DebateStance, context?: string) => Promise<DebateSynthesis>;
+}
+
+// ─── Engine ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Run a multi-agent debate.
+ *
+ * 1. Strategist proposes thesis
+ * 2. Skeptic challenges with antithesis
+ * 3. Synthesizer merges into consensus + recommendation
+ *
+ * If `maxRounds > 1`, the thesis and antithesis are fed back for refinement.
+ */
+export async function runDebate(config: DebateConfig): Promise<DebateResult> {
+  const maxRounds = config.maxRounds ?? 1;
+
+  let thesis = await config.strategist(config.question, config.context);
+  let antithesis = await config.skeptic(config.question, thesis, config.context);
+
+  // Multi-round refinement
+  for (let round = 1; round < maxRounds; round++) {
+    // Refine thesis against antithesis
+    thesis = await config.strategist(
+      `${config.question}\n\nCounterarguments to address:\n${antithesis.content}`,
+      config.context
+    );
+    // Refine antithesis against refined thesis
+    antithesis = await config.skeptic(
+      `${config.question}\n\nUpdated thesis to challenge:\n${thesis.content}`,
+      thesis,
+      config.context
+    );
+  }
+
+  const synthesis = await config.synthesizer(config.question, thesis, antithesis, config.context);
+
+  return { thesis, antithesis, synthesis, rounds: maxRounds };
+}

package/src/orchestration/ooda/economic-observer.ts

@@ -0,0 +1,77 @@
+/**
+ * EconomicObserver — Cost/value guard for autonomous agents.
+ *
+ * Tracks per-agent token costs vs. outcome value over a 7-day rolling window.
+ * Agents with negative ROI get throttled (cycle skipped with reason
+ * `economic_observer:negative_roi`).
+ *
+ * The SDK defines ONLY the interface + guard factory — pure, no DB.
+ * Forge implements `PostgresEconomicObserver` backed by TimescaleDB.
+ *
+ * Throttle logic:
+ *   if cost_7d > value_7d * 0.5 AND cycles > 20 → throttle (skip cycle).
+ *   Cycles under 20 always run (cold-start grace period).
+ *
+ * @public
+ */
+
+import type { RiskGuard, OODAContext } from "./types.js";
+
+// ─── Interface ──────────────────────────────────────────────────────────────────
+
+export interface EconomicObserver {
+  /**
+   * Record a completed cycle's cost and value.
+   *
+   * Called after the feedback phase produces an OutcomeRecord.
+   * `confidence` weights the outcome value: effective_value = valueCents * confidence.
+   */
+  recordCycle(
+    agentId: string,
+    tokenCostUsd: number,
+    outcomeValueCents: number,
+    confidence: number
+  ): Promise<void>;
+
+  /**
+   * Check whether this agent should be throttled (skipped).
+   *
+   * Returns true if the agent's 7-day rolling cost exceeds 50% of its
+   * 7-day rolling value AND it has completed more than 20 cycles.
+   */
+  shouldThrottle(agentId: string): Promise<boolean>;
+
+  /**
+   * Get statistics for the 7-day rolling window.
+   */
+  getStats(agentId: string): Promise<{
+    cost7d: number;
+    value7d: number;
+    roi: number;
+    cycles: number;
+  }>;
+}
+
+// ─── Guard Factory ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a RiskGuard from an EconomicObserver.
+ *
+ * Returns a guard compatible with `OODAAgentConfig.riskGuards` —
+ * zero boilerplate wiring into the OODA loop.
+ */
+export function economicObserverGuard(
+  observer: EconomicObserver,
+  agentId: string
+): RiskGuard {
+  return {
+    name: "economic_observer",
+    check: async (_ctx: OODAContext) => {
+      const throttled = await observer.shouldThrottle(agentId);
+      return {
+        proceed: !throttled,
+        reason: throttled ? "economic_observer:negative_roi" : undefined,
+      };
+    },
+  };
+}