@vauban-org/agent-sdk 0.16.0

package/src/metrics/create-agent-metrics.ts

@@ -0,0 +1,231 @@
+/**
+ * Prometheus metrics factory for SDK agents.
+ *
+ * Promoted from forge/src/agents/shared/metrics.ts (Vague 1.B.4).
+ *
+ * prom-client is an optional peer dependency. If absent, all metrics are
+ * no-op stubs so consumers that do not use Prometheus can still import this
+ * module without errors.
+ *
+ * @public @since 0.18.0
+ */
+
+import { createRequire } from "node:module";
+
+// ─── prom-client types (type-only, peer dep) ──────────────────────────────────
+
+// Type-only imports — erased at compile time. The actual module is loaded
+// lazily via createRequire so the factory works even when prom-client is absent.
+type PromClient = typeof import("prom-client");
+type Registry = import("prom-client").Registry;
+type Counter<L extends string> = import("prom-client").Counter<L>;
+type Histogram<L extends string> = import("prom-client").Histogram<L>;
+
+// ─── Lazy prom-client loader ──────────────────────────────────────────────────
+
+let _prom: PromClient | null | undefined;
+
+/**
+ * Load prom-client synchronously once, cache result.
+ * Returns null if prom-client is not installed.
+ */
+function loadPromClient(): PromClient | null {
+  if (_prom !== undefined) return _prom;
+  try {
+    const req = createRequire(import.meta.url);
+    _prom = req("prom-client") as PromClient;
+  } catch {
+    _prom = null;
+  }
+  return _prom;
+}
+
+// ─── No-op stubs ──────────────────────────────────────────────────────────────
+
+/** Minimal no-op counter. Safe to call `.inc()` / `.labels()` without effect. */
+function noopCounter<L extends string>(): Counter<L> {
+  const stub = {
+    inc: () => undefined,
+    labels: () => stub as unknown as ReturnType<Counter<L>["labels"]>,
+    reset: () => undefined,
+    remove: () => undefined,
+  };
+  return stub as unknown as Counter<L>;
+}
+
+/** Minimal no-op histogram. Safe to call `.observe()` / `.startTimer()` without effect. */
+function noopHistogram<L extends string>(): Histogram<L> {
+  const stub = {
+    observe: () => undefined,
+    startTimer: () => () => 0 as number,
+    labels: () => stub as unknown as ReturnType<Histogram<L>["labels"]>,
+    reset: () => undefined,
+    remove: () => undefined,
+    zero: () => undefined,
+  };
+  return stub as unknown as Histogram<L>;
+}
+
+// ─── Public interfaces ────────────────────────────────────────────────────────
+
+/**
+ * Standard metrics exposed by every SDK agent.
+ *
+ * Label sets follow Prometheus conventions: snake_case, no spaces.
+ *
+ * @public
+ */
+export interface AgentMetrics {
+  /** Incremented when an OODA cycle begins. */
+  cycleStarted: Counter<"agent_id">;
+  /** Incremented when an OODA cycle finishes; `outcome` = "success" | "error" | "skipped". */
+  cycleCompleted: Counter<"agent_id" | "outcome">;
+  /** Duration of an OODA cycle by phase ("observe"|"orient"|"decide"|"act"|"total"). */
+  cycleDuration: Histogram<"agent_id" | "phase">;
+  /** Incremented when a HITL approval request is sent. */
+  hitlRequested: Counter<"agent_id">;
+  /** Incremented when a HITL request resolves; `decision` = "approved" | "rejected" | "timeout". */
+  hitlResolved: Counter<"agent_id" | "decision">;
+  /** Incremented for every LLM API call attempted. */
+  llmCallCount: Counter<"agent_id" | "provider">;
+  /** Total tokens used; `direction` = "input" | "output". */
+  llmTokensUsed: Counter<"agent_id" | "provider" | "direction">;
+  /** Cumulative LLM cost in USD (Counter, never resets). */
+  llmCostUsd: Counter<"agent_id" | "provider">;
+}
+
+/**
+ * Options for `createAgentMetrics`.
+ *
+ * @public
+ */
+export interface CreateAgentMetricsOptions {
+  /**
+   * prom-client Registry to register metrics on.
+   * Defaults to a fresh isolated Registry per call so multiple consumers do
+   * not collide on the global default registry.
+   * Pass your own Registry to aggregate with other metrics.
+   */
+  registry?: Registry;
+  /**
+   * Metric name prefix (must end with `_`).
+   * @default "agent_"
+   * @example "forge_"
+   */
+  prefix?: string;
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+/**
+ * Create a set of standard Prometheus metrics for an SDK agent.
+ *
+ * If prom-client is not installed (optional peer dependency), returns no-op
+ * stubs so the call site does not need to handle `null`.
+ *
+ * @example
+ * ```ts
+ * import { createAgentMetrics } from "@vauban-org/agent-sdk/metrics";
+ *
+ * const m = createAgentMetrics({ prefix: "forge_" });
+ * m.cycleStarted.inc({ agent_id: "my-agent" });
+ * ```
+ *
+ * @public
+ */
+export function createAgentMetrics(
+  opts: CreateAgentMetricsOptions = {}
+): AgentMetrics {
+  const prefix = opts.prefix ?? "agent_";
+  const prom = loadPromClient();
+
+  if (prom === null) {
+    return {
+      cycleStarted: noopCounter<"agent_id">(),
+      cycleCompleted: noopCounter<"agent_id" | "outcome">(),
+      cycleDuration: noopHistogram<"agent_id" | "phase">(),
+      hitlRequested: noopCounter<"agent_id">(),
+      hitlResolved: noopCounter<"agent_id" | "decision">(),
+      llmCallCount: noopCounter<"agent_id" | "provider">(),
+      llmTokensUsed: noopCounter<"agent_id" | "provider" | "direction">(),
+      llmCostUsd: noopCounter<"agent_id" | "provider">(),
+    };
+  }
+
+  const registry = opts.registry ?? new prom.Registry();
+
+  function counter<L extends string>(
+    name: string,
+    help: string,
+    labelNames: L[]
+  ): Counter<L> {
+    return new prom!.Counter({
+      name: `${prefix}${name}`,
+      help,
+      labelNames,
+      registers: [registry],
+    });
+  }
+
+  function histogram<L extends string>(
+    name: string,
+    help: string,
+    labelNames: L[],
+    buckets?: number[]
+  ): Histogram<L> {
+    return new prom!.Histogram({
+      name: `${prefix}${name}`,
+      help,
+      labelNames,
+      buckets: buckets ?? prom!.linearBuckets(0, 500, 12),
+      registers: [registry],
+    });
+  }
+
+  return {
+    cycleStarted: counter<"agent_id">(
+      "cycle_started_total",
+      "OODA cycles started",
+      ["agent_id"]
+    ),
+    cycleCompleted: counter<"agent_id" | "outcome">(
+      "cycle_completed_total",
+      "OODA cycles completed",
+      ["agent_id", "outcome"]
+    ),
+    cycleDuration: histogram<"agent_id" | "phase">(
+      "cycle_duration_ms",
+      "OODA cycle duration in milliseconds",
+      ["agent_id", "phase"]
+    ),
+    hitlRequested: counter<"agent_id">(
+      "hitl_requested_total",
+      "HITL requests sent",
+      ["agent_id"]
+    ),
+    hitlResolved: counter<"agent_id" | "decision">(
+      "hitl_resolved_total",
+      "HITL requests resolved",
+      ["agent_id", "decision"]
+    ),
+    llmCallCount: counter<"agent_id" | "provider">(
+      "llm_calls_total",
+      "LLM API calls",
+      ["agent_id", "provider"]
+    ),
+    llmTokensUsed: counter<"agent_id" | "provider" | "direction">(
+      "llm_tokens_total",
+      "LLM tokens consumed",
+      ["agent_id", "provider", "direction"]
+    ),
+    llmCostUsd: counter<"agent_id" | "provider">(
+      "llm_cost_usd_total",
+      "Cumulative LLM cost in USD",
+      ["agent_id", "provider"]
+    ),
+  };
+}
+
+// ─── Re-export Registry type for convenience ──────────────────────────────────
+
+export type { Registry };

package/src/orchestration/bulkhead.ts

@@ -0,0 +1,145 @@
+/**
+ * Bulkhead worker pool — bounded concurrency with FIFO queue and metrics.
+ *
+ * Sprint-468 (command-center:sprint-468:bulkhead).
+ *
+ * createBulkhead returns a typed worker-pool object with:
+ *   - run(fn)   — enqueue a zero-argument task; resolves/rejects per task
+ *   - metrics() — live snapshot: active, queued, rejected, completed
+ *
+ * This is the orchestration-layer variant of resilience/bulkhead.ts.
+ * The key difference is the factory pattern (one pool, many tasks) vs. the
+ * resilience variant that wraps a single fixed function. Use this when the
+ * pool itself is a resource to manage (e.g. DB connection pool, LLM slots).
+ *
+ * Queue discipline: FIFO. Tasks enter the queue in submission order and
+ * acquire a worker slot in the same order.
+ *
+ * Fast-reject: when `rejectOnFull` is true (default) and the queue is at
+ * `maxQueue` capacity, new submissions throw `BulkheadQueueFullError`
+ * synchronously (before awaiting). When `rejectOnFull` is false, callers
+ * block indefinitely until a slot opens — useful for back-pressure scenarios.
+ */
+
+export class BulkheadQueueFullError extends Error {
+  constructor(active: number, queued: number, maxConcurrent: number, maxQueue: number) {
+    super(
+      `Bulkhead full — active=${active}/${maxConcurrent}, queued=${queued}/${maxQueue}`,
+    );
+    this.name = "BulkheadQueueFullError";
+  }
+}
+
+export interface BulkheadOptions {
+  /** Maximum number of concurrently executing tasks. */
+  maxConcurrent: number;
+  /** Maximum queue depth. Defaults to `maxConcurrent * 10`. */
+  maxQueue?: number;
+  /**
+   * When true (default): reject immediately when the queue is full.
+   * When false: block the caller indefinitely (unbounded wait).
+   */
+  rejectOnFull?: boolean;
+}
+
+export interface BulkheadMetrics {
+  /** Currently executing task count. */
+  active: number;
+  /** Tasks waiting in the queue. */
+  queued: number;
+  /** Tasks rejected because the queue was full (lifetime counter). */
+  rejected: number;
+  /** Tasks that completed successfully or with an error (lifetime counter). */
+  completed: number;
+}
+
+export interface BulkheadPool<T> {
+  /**
+   * Submit a zero-argument async task to the pool.
+   *
+   * Returns a Promise that resolves/rejects with the task's outcome.
+   * May throw `BulkheadQueueFullError` synchronously when rejectOnFull=true
+   * and the queue is at capacity.
+   */
+  run(fn: () => Promise<T>): Promise<T>;
+
+  /** Live metrics snapshot (no allocation beyond the returned object). */
+  metrics(): BulkheadMetrics;
+}
+
+/**
+ * Create a typed bulkhead worker pool.
+ *
+ * @example
+ * ```ts
+ * const pool = createBulkhead<string>({ maxConcurrent: 3, maxQueue: 10 });
+ * const result = await pool.run(() => fetchSomething());
+ * console.log(pool.metrics()); // { active: 0, queued: 0, rejected: 0, completed: 1 }
+ * ```
+ */
+export function createBulkhead<T>(opts: BulkheadOptions): BulkheadPool<T> {
+  const maxConcurrent = opts.maxConcurrent;
+  const maxQueue = opts.maxQueue ?? maxConcurrent * 10;
+  const rejectOnFull = opts.rejectOnFull !== false; // default true
+
+  let active = 0;
+  let rejected = 0;
+  let completed = 0;
+  const queue: Array<() => void> = [];
+
+  function tryDequeue(): void {
+    if (active >= maxConcurrent) return;
+    const next = queue.shift();
+    if (next) {
+      active += 1;
+      next();
+    }
+  }
+
+  function acquire(): Promise<void> {
+    if (active < maxConcurrent) {
+      active += 1;
+      return Promise.resolve();
+    }
+    if (rejectOnFull && queue.length >= maxQueue) {
+      rejected += 1;
+      return Promise.reject(
+        new BulkheadQueueFullError(active, queue.length, maxConcurrent, maxQueue),
+      );
+    }
+    // Either not rejectOnFull, or queue has room — enqueue.
+    return new Promise<void>((resolve, reject) => {
+      if (queue.length >= maxQueue) {
+        // Reached here only when rejectOnFull=false but queue just filled
+        // concurrently before we could enqueue. Reject as safety valve.
+        rejected += 1;
+        reject(new BulkheadQueueFullError(active, queue.length, maxConcurrent, maxQueue));
+        return;
+      }
+      queue.push(() => {
+        resolve();
+      });
+    });
+  }
+
+  function release(): void {
+    active -= 1;
+    completed += 1;
+    tryDequeue();
+  }
+
+  return {
+    async run(fn: () => Promise<T>): Promise<T> {
+      await acquire();
+      try {
+        return await fn();
+      } finally {
+        release();
+      }
+    },
+
+    metrics(): BulkheadMetrics {
+      return { active, queued: queue.length, rejected, completed };
+    },
+  };
+}

package/src/orchestration/idempotency.ts

@@ -0,0 +1,137 @@
+/**
+ * Idempotency primitives for orchestration-layer deduplication.
+ *
+ * Sprint-468 (command-center:sprint-468:idempotency-keys).
+ *
+ * Three utilities:
+ *   - computeIdempotencyKey  — SHA-256 fingerprint of a semantic payload
+ *   - withIdempotency        — in-memory call deduplication by key
+ *   - addIdempotencyHeader   — HTTP header injection for downstream services
+ *
+ * These operate at the orchestration layer (agent dispatch, pipeline step)
+ * rather than at the port level. Use the resilience/idempotent.ts primitive
+ * for direct port-wrapping; use these when you need explicit key management
+ * or HTTP propagation.
+ */
+
+import { createHash } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// computeIdempotencyKey
+// ---------------------------------------------------------------------------
+
+export interface IdempotencyKeyPayload {
+  content: string;
+  author: string;
+  category: string;
+}
+
+/**
+ * Derive a stable SHA-256 hex key from a semantic payload.
+ *
+ * Fields are ordered deterministically (alphabetical) before hashing so
+ * that object construction order does not affect the result.
+ *
+ * @param payload - Semantic payload with content, author, and category.
+ * @returns 64-character lowercase hex string.
+ */
+export function computeIdempotencyKey(payload: IdempotencyKeyPayload): string {
+  const h = createHash("sha256");
+  // Deterministic field order — alphabet: author < category < content
+  h.update(payload.author);
+  h.update("\x1f");
+  h.update(payload.category);
+  h.update("\x1f");
+  h.update(payload.content);
+  return h.digest("hex");
+}
+
+// ---------------------------------------------------------------------------
+// withIdempotency
+// ---------------------------------------------------------------------------
+
+export interface WithIdempotencyOptions {
+  /** Entry TTL in ms. Default: 5 minutes. */
+  ttlMs?: number;
+}
+
+interface CacheEntry<T> {
+  promise: Promise<T>;
+  expiresAt: number;
+}
+
+/**
+ * Deduplicate concurrent or repeated async calls using an in-memory Map.
+ *
+ * While a call identified by `key` is in-flight, subsequent calls with the
+ * same key attach to the same Promise (fan-out dedup). Once the call
+ * settles, the result is cached for `ttlMs` ms so that replay requests
+ * within the window also receive the same value without re-invoking.
+ *
+ * Failures are NOT cached: a failed call is immediately evicted so it can
+ * be retried.
+ *
+ * The shared cache Map is module-scoped by default. Pass an explicit Map
+ * for per-instance isolation (e.g. in tests or multi-tenant agents).
+ *
+ * @param call  - Zero-argument factory returning a Promise.
+ * @param key   - Stable deduplication key (from computeIdempotencyKey or any string).
+ * @param opts  - Optional TTL override.
+ * @param store - Optional shared Map (module-level singleton by default).
+ */
+
+const _defaultStore = new Map<string, CacheEntry<unknown>>();
+
+export function withIdempotency<T>(
+  call: () => Promise<T>,
+  key: string,
+  opts?: WithIdempotencyOptions,
+  store?: Map<string, CacheEntry<unknown>>,
+): Promise<T> {
+  const cache = (store ?? _defaultStore) as Map<string, CacheEntry<T>>;
+  const ttlMs = opts?.ttlMs ?? 5 * 60_000;
+  const now = Date.now();
+
+  const existing = cache.get(key);
+  if (existing !== undefined && existing.expiresAt > now) {
+    return existing.promise;
+  }
+
+  const promise = call().then(
+    (value) => {
+      // Refresh TTL on success so replays within window are cheap.
+      cache.set(key, { promise: Promise.resolve(value), expiresAt: Date.now() + ttlMs });
+      return value;
+    },
+    (err: unknown) => {
+      // Evict on failure — allow retry.
+      cache.delete(key);
+      return Promise.reject(err);
+    },
+  );
+
+  // Store the in-flight promise immediately so concurrent callers attach.
+  cache.set(key, { promise, expiresAt: now + ttlMs });
+  return promise;
+}
+
+// ---------------------------------------------------------------------------
+// addIdempotencyHeader
+// ---------------------------------------------------------------------------
+
+/**
+ * Inject an `X-Idempotency-Key` header into a plain headers record.
+ *
+ * Returns a new object — does not mutate the input. Safe to call in a
+ * pipeline step that builds the options for a downstream `fetch` call.
+ *
+ * @param headers - Existing headers object (may be empty).
+ * @param key     - Idempotency key (from computeIdempotencyKey or any string).
+ * @returns New headers object with X-Idempotency-Key added.
+ */
+export function addIdempotencyHeader(
+  headers: Record<string, string>,
+  key: string,
+): Record<string, string> {
+  return { ...headers, "X-Idempotency-Key": key };
+}

package/src/orchestration/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Orchestration primitives — public barrel.
+ *
+ * Exports:
+ *   - OODA agent loop (sprint-525 Bloc 5a)
+ *   - Idempotency key utilities (sprint-468:idempotency-keys)
+ *   - Bulkhead worker pool (sprint-468:bulkhead)
+ *
+ * @public
+ */
+
+export * from "./ooda/index.js";
+
+// Idempotency key utilities (sprint-468:idempotency-keys)
+export type { IdempotencyKeyPayload, WithIdempotencyOptions } from "./idempotency.js";
+export {
+  computeIdempotencyKey,
+  withIdempotency,
+  addIdempotencyHeader,
+} from "./idempotency.js";
+
+// Bulkhead worker pool (sprint-468:bulkhead)
+export { BulkheadQueueFullError, createBulkhead } from "./bulkhead.js";
+export type { BulkheadOptions as OrchestrationBulkheadOptions, BulkheadMetrics, BulkheadPool } from "./bulkhead.js";

package/src/orchestration/ooda/agent-config-loader.ts

@@ -0,0 +1,118 @@
+/**
+ * AgentConfigLoader — hot-reload config cache for OODA agents.
+ *
+ * Reads per-agent runtime configuration from the `agent_config` table with an
+ * in-memory TTL cache (default 30s). Each OODA cycle calls `get(agentId)` at
+ * the start; after the TTL expires the next call transparently re-fetches from
+ * the DB. No restart required for config changes.
+ *
+ * Column strategy:
+ *   - `config` (new schema) — preferred when present.
+ *   - `extra` (sprint-472 legacy) — backward-compat fallback.
+ *
+ * The `columnName` option allows the host to pin the column explicitly.
+ *
+ * @public
+ */
+
+import type { DbClient } from "../../tracking/agent-run-tracker.js";
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+/**
+ * Minimal contract for a hot-reload config cache.
+ *
+ * @typeParam T - Shape of the agent configuration object.
+ */
+export interface AgentConfigLoader<T = Record<string, unknown>> {
+  /**
+   * Return config for `agentId`. Serves from cache when within TTL;
+   * otherwise fetches from `agent_config` table and refreshes the cache.
+   *
+   * If no row exists for `agentId`, returns `defaultConfig` (or `{}` if
+   * none was provided).
+   */
+  get(agentId: string): Promise<T>;
+
+  /**
+   * Evict `agentId` from the cache. The next `get` call will re-fetch
+   * from the database regardless of TTL.
+   */
+  invalidate(agentId: string): void;
+}
+
+// ─── Internal types ───────────────────────────────────────────────────────────
+
+interface CacheEntry<T> {
+  config: T;
+  expiresAt: number; // ms since epoch
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+/**
+ * Create a hot-reload config loader backed by the `agent_config` table.
+ *
+ * @example
+ * ```typescript
+ * const loader = createAgentConfigLoader<MyConfig>({
+ *   db,
+ *   ttlMs: 30_000,
+ *   defaultConfig: { kelly_cap: 0.2, conviction_min: 0.6 },
+ * });
+ *
+ * // At cycle start:
+ * const cfg = await loader.get(agentId);
+ * ```
+ */
+export function createAgentConfigLoader<T = Record<string, unknown>>(opts: {
+  /** Postgres-compatible DB client (pg.Pool, pg.Client, or test mock). */
+  db: DbClient;
+  /** Cache TTL in milliseconds. Default: 30 000 (30s). */
+  ttlMs?: number;
+  /** Returned when no row exists for the requested agentId. */
+  defaultConfig?: T;
+  /**
+   * Which JSONB column to read from `agent_config`.
+   * - `'extra'` — sprint-472 legacy column (default when omitted).
+   * - `'config'` — new column (set if schema was migrated to add it).
+   */
+  columnName?: "config" | "extra";
+}): AgentConfigLoader<T> {
+  const ttlMs = opts.ttlMs ?? 30_000;
+  const defaultConfig = (opts.defaultConfig ?? {}) as T;
+  const column = opts.columnName ?? "extra";
+  const cache = new Map<string, CacheEntry<T>>();
+
+  async function fetch(agentId: string): Promise<T> {
+    const result = await opts.db.query<Record<string, unknown>>(
+      `SELECT ${column} AS cfg FROM agent_config WHERE agent_id = $1`,
+      [agentId],
+    );
+    if (!result.rows.length) {
+      return defaultConfig;
+    }
+    const raw = result.rows[0].cfg;
+    if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+      return defaultConfig;
+    }
+    return raw as T;
+  }
+
+  return {
+    async get(agentId: string): Promise<T> {
+      const now = Date.now();
+      const entry = cache.get(agentId);
+      if (entry !== undefined && entry.expiresAt > now) {
+        return entry.config;
+      }
+      const config = await fetch(agentId);
+      cache.set(agentId, { config, expiresAt: now + ttlMs });
+      return config;
+    },
+
+    invalidate(agentId: string): void {
+      cache.delete(agentId);
+    },
+  };
+}