@vauban-org/agent-sdk 0.16.0

package/src/outcomes/types.ts

@@ -0,0 +1,88 @@
+/**
+ * Outcomes module — wire types for /api/outcomes/* REST endpoints.
+ *
+ * All monetary amounts are integer cents (signed). Negative = cost.
+ * Route implementation lives in command-center /api/outcomes/* (sprint-522:quick-4).
+ */
+
+/**
+ * Open-ended outcome type discriminant.
+ * Canonical values: trade_pnl, forecast_accurate, knowledge_consolidated,
+ * cost_savings, lead_qualified, sprint_completed, etc.
+ */
+export type OutcomeType = string;
+
+/** A single measurable business result attributed to an agent run. */
+export interface Outcome {
+  id: string;
+  agent_id: string;
+  /** UUID of the agent_run row that produced this outcome. Nullable when created offline. */
+  agent_run_id: string | null;
+  outcome_type: OutcomeType;
+  /** Signed integer cents. Positive = value created, negative = cost incurred. */
+  value_cents: number;
+  /** ISO 4217 currency code. Defaults to 'USD'. */
+  currency: string;
+  /** ISO 8601 timestamp of when the outcome occurred. */
+  occurred_at: string;
+  /**
+   * True when the monetary value has not yet been back-filled from an
+   * authoritative source (e.g. trade P&L still pending settlement).
+   */
+  is_pending_backfill: boolean;
+  metadata?: Record<string, unknown> | null;
+}
+
+/** Aggregated outcome statistics for a given time window. */
+export interface OutcomeSummary {
+  period: { from: string; to: string };
+  /** Sum of positive value_cents over the period. */
+  total_value_cents: number;
+  /** Absolute sum of negative value_cents (stored as positive). */
+  total_cost_cents: number;
+  /** total_value_cents / total_cost_cents. Null when cost == 0. */
+  value_to_cost_ratio: number | null;
+  /** (total_value_cents - total_cost_cents) / total_cost_cents * 100. Null when cost == 0. */
+  net_roi_pct: number | null;
+  outcome_count: number;
+  attributed_count: number;
+  /** Outcomes where is_pending_backfill = true. */
+  pending_attribution_count: number;
+}
+
+/** Per-agent ROI breakdown for a time window. */
+export interface RoiPerAgent {
+  agent_id: string;
+  period: { from: string; to: string };
+  value_cents: number;
+  cost_cents: number;
+  /** Null when cost_cents == 0. */
+  net_roi_pct: number | null;
+  outcome_count: number;
+  /** pending_count / outcome_count. 0 when outcome_count == 0. */
+  pending_ratio: number;
+  /** Week-over-week delta in net_roi_pct. Null when prior week data unavailable. */
+  wow_delta_pct: number | null;
+}
+
+/** CFO-ready burn-rate and initiative breakdown view. */
+export interface CfoView {
+  period: { from: string; to: string };
+  /** Average daily spend in cents over the period. */
+  burn_rate_per_day_cents: number;
+  /** burn_rate_per_day_cents * 30. */
+  projected_30d_cents: number;
+  by_initiative: Array<{
+    initiative_id: string;
+    spent_cents: number;
+    /** Null when no budget is assigned to the initiative. */
+    budget_cents: number | null;
+    /** spent_cents / budget_cents * 100. Null when budget_cents is null. */
+    pct: number | null;
+  }>;
+  /**
+   * Sum of value_cents for is_pending_backfill=true rows.
+   * Lower-bound estimate of unrealised value.
+   */
+  pending_value_estimate_cents: number;
+}

package/src/patterns/_shared/brain-logger.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared non-blocking Brain archive helper for orchestration patterns.
+ *
+ * Returns void (not Promise<void>) — explicit fire-and-forget contract.
+ * Callers that accidentally await this get a compile-time warning since
+ * void is not meaningfully awaitable.
+ *
+ * @internal — do not re-export from any public pattern barrel.
+ */
+import type { BrainPort, BrainEntryInput } from "../../ports/brain.js";
+
+export function logToBrain(
+  brain: BrainPort | undefined | null,
+  entry: BrainEntryInput,
+): void {
+  if (!brain) return;
+  brain.archiveKnowledge(entry).catch(() => undefined);
+}

package/src/patterns/circuit-breaker/index.ts

@@ -0,0 +1,8 @@
+export { createSessionCircuitBreaker } from "./session-cb.js";
+export type {
+  SessionCircuitBreaker,
+  CircuitBreakerConfig,
+  CircuitBreakerThresholds,
+  CircuitSnapshot,
+  CircuitState,
+} from "./types.js";

package/src/patterns/circuit-breaker/session-cb.ts

@@ -0,0 +1,198 @@
+/**
+ * Pattern A: Session-Level Circuit Breaker — factory.
+ * @public
+ */
+import { logToBrain } from "../_shared/brain-logger.js";
+import type {
+  CircuitBreakerConfig,
+  CircuitSnapshot,
+  CircuitState,
+  SessionCircuitBreaker,
+} from "./types.js";
+import type { OODAContext } from "../../orchestration/ooda/types.js";
+
+const NOOP = {
+  debug: () => undefined,
+  info: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+};
+
+export function createSessionCircuitBreaker(
+  config: CircuitBreakerConfig,
+): SessionCircuitBreaker {
+  const {
+    name,
+    thresholds = {},
+    resetAfterMs = 60_000,
+    brain,
+    onTrip,
+    _now = Date.now,
+  } = config;
+  const logger = config.logger ?? NOOP;
+
+  const maxTokens            = thresholds.maxTokens            ?? 50_000;
+  const maxConsecutiveErrors = thresholds.maxConsecutiveErrors ?? 5;
+  const maxActionCount       = thresholds.maxActionCount       ?? 200;
+  const maxElapsedMs         = thresholds.maxElapsedMs         ?? 3_600_000;
+  const maxCostUsd           = thresholds.maxCostUsd           ?? 10.0;
+
+  let state: CircuitState = "closed";
+  let tripReason: string | undefined;
+  let openedAt: number | undefined;
+  const sessionStart = _now();
+  let tokenCount = 0;
+  let consecutiveErrors = 0;
+  let actionCount = 0;
+  let estimatedCostUsd = 0;
+
+  function snap(): CircuitSnapshot {
+    return {
+      state,
+      tokenCount,
+      consecutiveErrors,
+      actionCount,
+      elapsedMs: _now() - sessionStart,
+      estimatedCostUsd,
+      tripReason,
+      openedAt,
+    };
+  }
+
+  function doTrip(reason: string): void {
+    if (state === "open") return; // idempotent
+    state = "open";
+    tripReason = reason;
+    openedAt = _now();
+    logger.warn(
+      { name, reason },
+      `[session-cb:${name}] OPEN: ${reason}`,
+    );
+    logToBrain(brain, {
+      content: `Session CB '${name}' tripped OPEN. ${reason}`,
+      content_type: "event",
+      author: `session-cb:${name}`,
+      category: "incident",
+      tags: ["circuit-breaker", "session", name, "tripped"],
+      confidence: 0.95,
+      metadata: snap() as unknown as Record<string, unknown>,
+    });
+    try {
+      onTrip?.(snap());
+    } catch {
+      /* suppress */
+    }
+  }
+
+  function checkThresholds(): string | null {
+    if (tokenCount > maxTokens)
+      return `tokenCount(${tokenCount}) > maxTokens(${maxTokens})`;
+    if (consecutiveErrors >= maxConsecutiveErrors)
+      return `consecutiveErrors(${consecutiveErrors}) >= ${maxConsecutiveErrors}`;
+    if (actionCount > maxActionCount)
+      return `actionCount(${actionCount}) > maxActionCount(${maxActionCount})`;
+    const elapsed = _now() - sessionStart;
+    if (elapsed > maxElapsedMs)
+      return `elapsedMs(${elapsed}) > maxElapsedMs(${maxElapsedMs})`;
+    if (estimatedCostUsd > maxCostUsd)
+      return `costUsd($${estimatedCostUsd.toFixed(4)}) > maxCostUsd($${maxCostUsd})`;
+    return null;
+  }
+
+  async function check(
+    _ctx: OODAContext,
+  ): Promise<{ proceed: boolean; reason?: string }> {
+    const now = _now();
+    if (state === "open") {
+      const elapsed =
+        openedAt !== undefined ? now - openedAt : resetAfterMs;
+      if (elapsed < resetAfterMs) {
+        return {
+          proceed: false,
+          reason: `session-cb:${name} OPEN (${tripReason ?? "threshold breach"})`,
+        };
+      }
+      state = "half-open";
+      // Reset consecutiveErrors so the inherited count from before the trip
+      // does not immediately re-trip the probe via checkThresholds().
+      consecutiveErrors = 0;
+      logger.info({ name }, `[session-cb:${name}] HALF-OPEN probe`);
+    }
+    // In half-open state we allow the probe through without re-checking
+    // accumulated metrics (tokens, actions, cost) — only recordError() during
+    // the probe can re-trip. Threshold re-check only applies to closed state.
+    if (state !== "half-open") {
+      const violation = checkThresholds();
+      if (violation !== null) {
+        doTrip(violation);
+        return {
+          proceed: false,
+          reason: `session-cb:${name} tripped: ${violation}`,
+        };
+      }
+    }
+    return { proceed: true };
+  }
+
+  return {
+    name: `session-cb:${name}`,
+    check,
+    recordTokens(count: number, costUsd?: number): void {
+      tokenCount += count;
+      if (costUsd !== undefined) estimatedCostUsd += costUsd;
+      if (state === "closed") {
+        const v = checkThresholds();
+        if (v) doTrip(v);
+      }
+    },
+    recordError(): void {
+      consecutiveErrors += 1;
+      if (state === "half-open") {
+        doTrip(`probe failed (errors=${consecutiveErrors})`);
+        return;
+      }
+      if (state === "closed") {
+        const v = checkThresholds();
+        if (v) doTrip(v);
+      }
+    },
+    recordSuccess(): void {
+      // NOTE: does NOT re-check thresholds — token/action/cost counters are
+      // not reset by success; only consecutiveErrors is cleared.
+      if (state === "half-open") {
+        state = "closed";
+        consecutiveErrors = 0;
+        tripReason = undefined;
+        openedAt = undefined;
+        logger.info({ name }, `[session-cb:${name}] CLOSED (probe success)`);
+        logToBrain(brain, {
+          content: `Session CB '${name}' recovered to CLOSED after probe success.`,
+          content_type: "event",
+          author: `session-cb:${name}`,
+          category: "development",
+          tags: ["circuit-breaker", "session", name, "recovered"],
+          confidence: 0.9,
+        });
+      } else {
+        consecutiveErrors = 0;
+      }
+    },
+    recordAction(): void {
+      actionCount += 1;
+      if (state === "closed") {
+        const v = checkThresholds();
+        if (v) doTrip(v);
+      }
+    },
+    reset(): void {
+      state = "closed";
+      tokenCount = 0;
+      consecutiveErrors = 0;
+      actionCount = 0;
+      estimatedCostUsd = 0;
+      tripReason = undefined;
+      openedAt = undefined;
+    },
+    snapshot: snap,
+  };
+}

package/src/patterns/circuit-breaker/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Pattern A: Session-Level Circuit Breaker — types.
+ *
+ * DISTINCT from `resilience/circuit-breaker.ts` which wraps async functions.
+ * This pattern tracks SESSION METRICS (tokens, errors, actions, cost, time)
+ * and integrates as a RiskGuard for the OODA cycle.
+ *
+ * State machine: closed → open (threshold breach) → half-open (after
+ * resetAfterMs) → closed (probe success via recordSuccess()).
+ *
+ * IMPORTANT: record* methods must be called manually from phase functions.
+ * The OODA loop does NOT auto-feed these metrics.
+ *
+ * @public
+ */
+import type { RiskGuard } from "../../orchestration/ooda/types.js";
+import type { BrainPort } from "../../ports/brain.js";
+import type { LoggerPort } from "../../ports/logger.js";
+
+export type CircuitState = "closed" | "open" | "half-open";
+
+export interface CircuitSnapshot {
+  readonly state: CircuitState;
+  readonly tokenCount: number;
+  readonly consecutiveErrors: number;
+  readonly actionCount: number;
+  readonly elapsedMs: number;
+  readonly estimatedCostUsd: number;
+  readonly tripReason?: string;
+  readonly openedAt?: number;
+}
+
+export interface CircuitBreakerThresholds {
+  /** Max cumulative tokens before trip. Default: 50_000 */
+  readonly maxTokens?: number;
+  /** Max consecutive errors before trip. Default: 5 */
+  readonly maxConsecutiveErrors?: number;
+  /** Max action count per session. Default: 200 */
+  readonly maxActionCount?: number;
+  /** Max session elapsed ms. Default: 3_600_000 (1h) */
+  readonly maxElapsedMs?: number;
+  /** Max estimated cost USD. Default: 10.0 */
+  readonly maxCostUsd?: number;
+}
+
+export interface CircuitBreakerConfig {
+  readonly name: string;
+  readonly thresholds?: CircuitBreakerThresholds;
+  /** Time to stay OPEN before half-open probe. Default: 60_000 ms */
+  readonly resetAfterMs?: number;
+  readonly brain?: BrainPort;
+  readonly logger?: LoggerPort;
+  /** Called synchronously when circuit trips. Must not throw. */
+  readonly onTrip?: (snapshot: CircuitSnapshot) => void;
+  /** Injectable clock for tests. Default: Date.now */
+  readonly _now?: () => number;
+}
+
+/**
+ * Session-level circuit breaker. Implements RiskGuard + metric recording.
+ *
+ * Add to OODAAgentConfig.riskGuards. Phase functions call record* methods.
+ */
+export interface SessionCircuitBreaker extends RiskGuard {
+  recordTokens(count: number, costUsd?: number): void;
+  recordError(): void;
+  /** Record a successful action. Resets consecutiveErrors. Closes half-open probe. */
+  recordSuccess(): void;
+  recordAction(): void;
+  reset(): void;
+  snapshot(): CircuitSnapshot;
+}

package/src/patterns/escalation/index.ts

@@ -0,0 +1,8 @@
+export { createEscalationPyramid } from "./pyramid.js";
+export type {
+  EscalationPyramid,
+  EscalationPyramidConfig,
+  EscalationLevel,
+  ActionDeclaration,
+  EscalationDecision,
+} from "./types.js";

package/src/patterns/escalation/pyramid.ts

@@ -0,0 +1,125 @@
+/**
+ * Pattern C: Escalation Pyramid — factory implementation.
+ * @public
+ */
+import { logToBrain } from "../_shared/brain-logger.js";
+import type {
+  EscalationDecision,
+  EscalationLevel,
+  EscalationPyramid,
+  EscalationPyramidConfig,
+} from "./types.js";
+import type { OODAContext } from "../../orchestration/ooda/types.js";
+
+const NOOP = {
+  debug: () => undefined,
+  info: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+};
+
+const UNKNOWN_DEFAULT: EscalationLevel = "L3_hitl_required";
+
+export function createEscalationPyramid(
+  config: EscalationPyramidConfig,
+): EscalationPyramid {
+  const l1 = config.l1ConfidenceThreshold ?? 0.85;
+  const l2 = config.l2ConfidenceThreshold ?? 0.60;
+  if (l2 >= l1) {
+    throw new Error(
+      `[escalation:${config.name}] l2ConfidenceThreshold(${l2}) must be < l1ConfidenceThreshold(${l1})`,
+    );
+  }
+  const logger = config.logger ?? NOOP;
+
+  const declared = new Map<string, EscalationLevel>(
+    config.declarations.map((d) => [d.actionType, d.level]),
+  );
+  const overrides = new Map<string, EscalationLevel>();
+
+  function getNominal(actionType: string): EscalationLevel {
+    return overrides.get(actionType) ?? declared.get(actionType) ?? UNKNOWN_DEFAULT;
+  }
+
+  function escalate(
+    nominal: EscalationLevel,
+    confidence: number,
+    isDryRun: boolean,
+  ): EscalationLevel {
+    if (isDryRun) return "L1_autonomous";
+    switch (nominal) {
+      case "L1_autonomous":
+        return confidence < l1 ? "L2_async_review" : "L1_autonomous";
+      case "L2_async_review":
+        return confidence < l2 ? "L3_hitl_required" : "L2_async_review";
+      case "L3_hitl_required":
+        return "L3_hitl_required";
+    }
+  }
+
+  return {
+    async canProceed(
+      actionType: string,
+      confidence: number,
+      ctx: OODAContext,
+    ): Promise<EscalationDecision> {
+      const nominal = getNominal(actionType);
+      const isDryRun = ctx.executionMode === "dry-run";
+      const effectiveLevel = escalate(nominal, confidence, isDryRun);
+      const proceed = effectiveLevel !== "L3_hitl_required";
+
+      const reason = isDryRun
+        ? `dry-run → L1_autonomous`
+        : nominal === effectiveLevel
+          ? `'${actionType}' at ${nominal} (confidence=${confidence.toFixed(3)})`
+          : `'${actionType}' escalated ${nominal} → ${effectiveLevel} (confidence=${confidence.toFixed(3)})`;
+
+      const decision: EscalationDecision = { proceed, effectiveLevel, reason };
+
+      logger.info(
+        { pyramid: config.name, actionType, confidence, effectiveLevel, proceed },
+        `[escalation:${config.name}] ${reason}`,
+      );
+
+      logToBrain(config.brain, {
+        content: `Escalation '${config.name}': ${reason}`,
+        content_type: "decision",
+        author: `escalation:${config.name}`,
+        category: "decision",
+        tags: ["escalation-pyramid", config.name, effectiveLevel, actionType],
+        confidence,
+        metadata: {
+          actionType,
+          confidence,
+          nominal,
+          effectiveLevel,
+          proceed,
+          agentId: ctx.agentId,
+          runId: ctx.runId,
+        },
+      });
+
+      if (!proceed) {
+        logger.warn(
+          { pyramid: config.name, actionType },
+          `[escalation:${config.name}] L3 block on '${actionType}'`,
+        );
+        try {
+          config.onHitlRequired?.(actionType, confidence, decision, ctx);
+        } catch {
+          /* suppress */
+        }
+      }
+
+      return decision;
+    },
+
+    override(actionType: string, level: EscalationLevel): void {
+      overrides.set(actionType, level);
+    },
+
+    clearOverride(actionType: string): void {
+      overrides.delete(actionType);
+    },
+  };
+}

package/src/patterns/escalation/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Pattern C: Escalation Pyramid — types.
+ *
+ * Declares action autonomy levels and validates before execution.
+ * Confidence-based escalation: insufficient confidence escalates the level.
+ * Unknown action types default to L3 (fail-safe).
+ * dry-run always resolves to L1 (no real effects).
+ *
+ * NOTE: `confidence` must be provided by the agent's DECIDE phase.
+ * The SDK does not infer it automatically from the LLM.
+ *
+ * @public
+ */
+import type { BrainPort } from "../../ports/brain.js";
+import type { LoggerPort } from "../../ports/logger.js";
+import type { OODAContext } from "../../orchestration/ooda/types.js";
+
+export type EscalationLevel =
+  | "L1_autonomous"
+  | "L2_async_review"
+  | "L3_hitl_required";
+
+export interface ActionDeclaration {
+  readonly actionType: string;
+  readonly level: EscalationLevel;
+}
+
+export interface EscalationDecision {
+  readonly proceed: boolean;
+  readonly effectiveLevel: EscalationLevel;
+  readonly reason: string;
+}
+
+export interface EscalationPyramidConfig {
+  readonly name: string;
+  readonly declarations: ReadonlyArray<ActionDeclaration>;
+  /** Min confidence for L1 without escalating to L2. Default: 0.85 */
+  readonly l1ConfidenceThreshold?: number;
+  /** Min confidence for L2 without escalating to L3. Default: 0.60 */
+  readonly l2ConfidenceThreshold?: number;
+  readonly brain?: BrainPort;
+  readonly logger?: LoggerPort;
+  /** Called when effectiveLevel = L3. Must not throw. */
+  readonly onHitlRequired?: (
+    actionType: string,
+    confidence: number,
+    decision: EscalationDecision,
+    ctx: OODAContext,
+  ) => void;
+}
+
+export interface EscalationPyramid {
+  canProceed(
+    actionType: string,
+    confidence: number,
+    ctx: OODAContext,
+  ): Promise<EscalationDecision>;
+  /** Runtime override without redeployment. */
+  override(actionType: string, level: EscalationLevel): void;
+  /** Remove override — restores declared level (or L3 default). */
+  clearOverride(actionType: string): void;
+}

package/src/patterns/quality-gate/gate.ts

@@ -0,0 +1,102 @@
+/**
+ * Pattern B: Quality Gate — factory implementation.
+ * @public
+ */
+import { logToBrain } from "../_shared/brain-logger.js";
+import type {
+  QualityGate,
+  QualityGateConfig,
+  QualityRouting,
+  QualityScore,
+} from "./types.js";
+
+const NOOP = {
+  debug: () => undefined,
+  info: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+};
+
+export function createQualityGate<T>(
+  config: QualityGateConfig<T>,
+): QualityGate<T> {
+  if (config.evaluators.length === 0) {
+    throw new Error(
+      `[quality-gate:${config.name}] evaluators must not be empty`,
+    );
+  }
+  const autoProceed = config.autoProceedThreshold ?? 0.8;
+  const asyncReview = config.asyncReviewThreshold ?? 0.5;
+  if (asyncReview >= autoProceed) {
+    throw new Error(
+      `[quality-gate:${config.name}] asyncReviewThreshold(${asyncReview}) must be < autoProceedThreshold(${autoProceed})`,
+    );
+  }
+  const logger = config.logger ?? NOOP;
+
+  return {
+    async evaluate(subject: T): Promise<QualityScore> {
+      const dims: Array<{ name: string; score: number; weight: number }> = [];
+      let totalWeight = 0;
+      let weightedSum = 0;
+
+      for (const ev of config.evaluators) {
+        const w = ev.weight ?? 1;
+        let s = 0;
+        try {
+          const raw = await ev.evaluate(subject);
+          // NaN/Infinity guard — misbehaving evaluators score 0 without propagating
+          s = Number.isFinite(raw) ? Math.max(0, Math.min(1, raw)) : 0;
+        } catch (err) {
+          logger.error(
+            { evaluator: ev.name, err },
+            `[quality-gate:${config.name}] evaluator '${ev.name}' threw — scoring 0`,
+          );
+        }
+        dims.push({ name: ev.name, score: s, weight: w });
+        totalWeight += w;
+        weightedSum += s * w;
+      }
+
+      const overall = totalWeight > 0 ? weightedSum / totalWeight : 0;
+      const routing: QualityRouting =
+        overall >= autoProceed
+          ? "auto"
+          : overall >= asyncReview
+            ? "async_review"
+            : "hitl_block";
+
+      const score: QualityScore = { overall, routing, dimensions: dims };
+
+      logger.info(
+        { gate: config.name, overall, routing },
+        `[quality-gate:${config.name}] ${overall.toFixed(3)} → ${routing}`,
+      );
+
+      // category: "operations" — these are production quality metrics, not debug logs
+      logToBrain(config.brain, {
+        content: `Quality gate '${config.name}': overall=${overall.toFixed(3)} routing=${routing}. ${dims.map((d) => `${d.name}=${d.score.toFixed(3)}`).join(", ")}`,
+        content_type: "metric",
+        author: `quality-gate:${config.name}`,
+        category: "operations",
+        tags: ["quality-gate", config.name, routing],
+        confidence: overall,
+        metadata: { score: score as unknown as Record<string, unknown> },
+      });
+
+      if (routing === "hitl_block") {
+        logger.warn(
+          { gate: config.name, overall },
+          `[quality-gate:${config.name}] hitl_block triggered`,
+        );
+        try {
+          config.onHitlBlock?.(score, subject);
+        } catch {
+          /* suppress */
+        }
+      }
+
+      return score;
+    },
+  };
+}

package/src/patterns/quality-gate/index.ts

@@ -0,0 +1,8 @@
+export { createQualityGate } from "./gate.js";
+export type {
+  QualityGate,
+  QualityGateConfig,
+  QualityScore,
+  QualityRouting,
+  QualityEvaluator,
+} from "./types.js";