@vauban-org/agent-sdk 0.16.0

package/src/orchestration/ooda/errors.ts

@@ -0,0 +1,32 @@
+/**
+ * OODA boot errors — dependency validation (plan v6 §3.7).
+ *
+ * @public
+ */
+
+/**
+ * Thrown at boot when a required dependency (e.g. `deps.llm`) is missing
+ * and `SDK_STRICT_DEPS` mode is enabled (default: true).
+ */
+export class MissingDependencyError extends Error {
+  readonly port: string;
+
+  constructor(port: string) {
+    super(`OODAAgent requires deps.${port}. BYOM is mandatory in strict mode.`);
+    this.name = "MissingDependencyError";
+    this.port = port;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Thrown when the `deps` object is structurally invalid (e.g. wrong type
+ * for a known port, conflicting constraints).
+ */
+export class DepsValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DepsValidationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/orchestration/ooda/execution-mode-guard.ts

@@ -0,0 +1,37 @@
+/**
+ * EXECUTION_MODE guard — sprint-525:quick-2 (anti-pattern #6).
+ *
+ * Refuses to boot an OODA agent without an explicit execution mode.
+ * Forces the operator to make a deliberate choice between safe
+ * simulation (`dry-run`) and on-line action (`live`) — no implicit
+ * default that could leak side-effects in test environments.
+ *
+ * @public
+ */
+
+import type { ExecutionMode } from "./types.js";
+
+/**
+ * Assert that `mode` is a valid `ExecutionMode`. Throws an Error with
+ * an actionable message otherwise — typically caught and logged by
+ * the agent boot path so the operator immediately sees what to set.
+ */
+export function assertExecutionMode(mode: unknown): asserts mode is ExecutionMode {
+  if (mode !== "dry-run" && mode !== "live") {
+    throw new Error(`OODA agent requires EXECUTION_MODE: 'dry-run' | 'live'. Got: ${String(mode)}`);
+  }
+}
+
+/**
+ * Convenience reader: pull EXECUTION_MODE from a process-like env bag
+ * and assert it. Centralises the "fail fast at boot" pattern for
+ * downstream agents that read from `process.env`.
+ */
+export function readExecutionModeFromEnv(
+  env: Record<string, string | undefined>,
+  varName = "EXECUTION_MODE",
+): ExecutionMode {
+  const raw = env[varName];
+  assertExecutionMode(raw);
+  return raw;
+}

package/src/orchestration/ooda/factory.ts

@@ -0,0 +1,48 @@
+/**
+ * createOODAAgent — public factory with boot-time dependency validation.
+ *
+ * Plan v6 §3.7: strict deps validation at construction.
+ * - `SDK_STRICT_DEPS=false`: legacy mode — warn only, do not throw.
+ * - `SDK_STRICT_DEPS` absent or any other value: strict mode — throw `MissingDependencyError`.
+ *
+ * @public
+ */
+
+import { OODAAgentImpl } from "./agent.js";
+import { MissingDependencyError } from "./errors.js";
+import type { OODAAgent, OODAAgentConfig } from "./types.js";
+
+export function createOODAAgent<
+  TConfig = unknown,
+  TObs = unknown,
+  TOrient = unknown,
+  TDecision = unknown,
+  TAction = unknown,
+  TFeedback = unknown
+>(
+  config: OODAAgentConfig<TConfig, TObs, TOrient, TDecision, TAction, TFeedback>
+): OODAAgent {
+  // 0.17: default=legacy (opt-in via SDK_STRICT_DEPS=true). 1.0: default=strict.
+  const strict = process.env["SDK_STRICT_DEPS"] === "true";
+
+  if (!config.deps) {
+    if (strict) {
+      throw new MissingDependencyError("llm");
+    }
+    // Legacy mode: warn only — will throw in SDK 1.0
+    console.warn(
+      "[agent-sdk] OODAAgentConfig.deps missing — legacy mode. Will throw in 1.0."
+    );
+  } else if (strict && !config.deps.llm) {
+    throw new MissingDependencyError("llm");
+  }
+
+  return new OODAAgentImpl<
+    TConfig,
+    TObs,
+    TOrient,
+    TDecision,
+    TAction,
+    TFeedback
+  >(config);
+}

package/src/orchestration/ooda/guardrails.ts

@@ -0,0 +1,172 @@
+/**
+ * LLM Guardrails — pre/post phase enforcement with Poseidon-provable violations.
+ *
+ * Sprint-563: B1 — LLM Guardrails pre/post + violations Vauban Proof Stack.
+ *
+ * Guards run before (pre-phase) or after (post-phase) each OODA phase.
+ * Pre-guards are BLOCKING — phase.fn does NOT execute if guard trips.
+ * Post-guards inspect output — reject phase result if violation detected.
+ *
+ * Violations produce a Poseidon hash via proofPort → anchorable on L3.
+ * CycleEventV011 'guardrail_violated' is emitted with proofHash + timing.
+ */
+
+import type { OODAContext, CycleEventV011 } from "./types.js";
+
+export type GuardrailTiming = "pre-phase" | "post-phase";
+
+export interface GuardrailDef<TInput = unknown, TOutput = unknown> {
+  /** Guard name (e.g. "no-pii-in-output"). */
+  readonly name: string;
+  /** When the guard executes. */
+  readonly timing: GuardrailTiming;
+  /**
+   * Check function. Returns { pass: false, reason, proofHash? } on violation.
+   * `input` is the phase input (pre-phase) or output (post-phase).
+   */
+  check(input: TInput | TOutput, ctx: OODAContext): Promise<GuardrailResult>;
+}
+
+export interface GuardrailResult {
+  pass: boolean;
+  reason?: string;
+  /** Poseidon hash of the violation payload for L3 anchoring. */
+  proofHash?: string;
+}
+
+export interface GuardrailViolation {
+  name: string;
+  timing: GuardrailTiming;
+  phase: string;
+  reason: string;
+  proofHash?: string;
+}
+
+/**
+ * Run pre-guards. Returns the first violation, or null if all pass.
+ * Pre-guard violations are BLOCKING — the phase does not execute.
+ */
+export async function runPreGuards<TInput>(
+  guards: readonly GuardrailDef<TInput, unknown>[],
+  input: TInput,
+  ctx: OODAContext,
+): Promise<GuardrailViolation | null> {
+  for (const guard of guards) {
+    if (guard.timing !== "pre-phase") continue;
+    const result = await guard.check(input, ctx);
+    if (!result.pass) {
+      return {
+        name: guard.name,
+        timing: guard.timing,
+        phase: "(pre-phase)",
+        reason: result.reason ?? "Guard tripped",
+        proofHash: result.proofHash,
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Run post-guards. Returns the first violation, or null if all pass.
+ * Post-guard violations REJECT the phase output.
+ */
+export async function runPostGuards<TOutput>(
+  guards: readonly GuardrailDef<unknown, TOutput>[],
+  output: TOutput,
+  ctx: OODAContext,
+): Promise<GuardrailViolation | null> {
+  for (const guard of guards) {
+    if (guard.timing !== "post-phase") continue;
+    const result = await guard.check(output, ctx);
+    if (!result.pass) {
+      return {
+        name: guard.name,
+        timing: guard.timing,
+        phase: "(post-phase)",
+        reason: result.reason ?? "Guard tripped",
+        proofHash: result.proofHash,
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Build a CycleEventV011 'guardrail_violated' event from a violation.
+ */
+export function guardrailViolationToEvent(
+  violation: GuardrailViolation,
+  runId: string,
+  cycleIndex: number,
+): Extract<CycleEventV011, { type: "guardrail_violated" }> {
+  return {
+    type: "guardrail_violated",
+    runId,
+    cycleIndex,
+    phase: violation.phase,
+    timing: violation.timing,
+    proofHash: violation.proofHash ?? "",
+    reason: violation.reason,
+    ts: Date.now(),
+  };
+}
+
+// ─── Built-in guardrails ─────────────────────────────────────────────────────
+
+/**
+ * PII guard — detects credit card numbers in output.
+ * Post-phase only, runs after LLM calls.
+ */
+export const PII_GUARD: GuardrailDef<string> = {
+  name: "no-pii-in-output",
+  timing: "post-phase",
+  async check(output: string) {
+    // Luhn-like detection: 13-19 digit sequences (credit card PAN range)
+    const ccPattern = /\b[0-9]{13,19}\b/g;
+    const matches = output.match(ccPattern);
+    if (matches) {
+      const hasLuhn = matches.some((m) => {
+        let sum = 0;
+        let alt = false;
+        for (let i = m.length - 1; i >= 0; i--) {
+          let n = parseInt(m[i]!, 10);
+          if (alt) {
+            n *= 2;
+            if (n > 9) n -= 9;
+          }
+          sum += n;
+          alt = !alt;
+        }
+        return sum % 10 === 0;
+      });
+      if (hasLuhn) {
+        return {
+          pass: false,
+          reason: "Potential credit card number detected in LLM output",
+        };
+      }
+    }
+    return { pass: true };
+  },
+};
+
+/**
+ * Max output length guard — prevents runaway LLM responses.
+ * Pre-phase only (applied to input size before LLM call).
+ */
+export function createMaxInputLengthGuard(maxChars: number): GuardrailDef<string> {
+  return {
+    name: `max-input-${maxChars}`,
+    timing: "pre-phase",
+    async check(input: string) {
+      if (input.length > maxChars) {
+        return {
+          pass: false,
+          reason: `Input length ${input.length} exceeds maximum ${maxChars} characters`,
+        };
+      }
+      return { pass: true };
+    },
+  };
+}

package/src/orchestration/ooda/guards/always-on.ts

@@ -0,0 +1,21 @@
+/**
+ * always-on session guard — 24/7 no-op.
+ *
+ * For cron-style agents that run unconditionally (e.g. daily-digest, heartbeat).
+ * Satisfies the SessionGuard interface without gating anything.
+ *
+ * @public
+ */
+
+import type { SessionGuard } from "../types.js";
+
+/**
+ * Returns a SessionGuard that is always active.
+ * Use for agents that must run regardless of time-of-day or calendar.
+ */
+export function alwaysOn(): SessionGuard {
+  return {
+    name: "always-on",
+    isActive: async (_at: Date): Promise<boolean> => true,
+  };
+}

package/src/orchestration/ooda/guards/business-hours.ts

@@ -0,0 +1,134 @@
+/**
+ * business-hours — configurable time-window session guard.
+ *
+ * For non-trading agents that run within a defined business window:
+ *   - dreams agent: 02:00–05:00 UTC daily
+ *   - narrator agent: 08:00–09:00 UTC Mon–Fri
+ *   - Any ops agent bounded by a regional work schedule
+ *
+ * Anti-pattern #5: guard is consulted on every OODA cycle — no caching.
+ *
+ * @public
+ */
+
+import type { SessionGuard } from "../types.js";
+
+export interface BusinessHoursOptions {
+  /**
+   * IANA timezone string (e.g. 'Europe/Paris', 'UTC', 'America/New_York').
+   * @defaultValue 'UTC'
+   */
+  tz?: string;
+
+  /**
+   * Days of week when the window is active.
+   * 1=Monday, 2=Tuesday, ..., 7=Sunday (ISO 8601 convention).
+   * @example [1,2,3,4,5] // Mon–Fri
+   */
+  daysOfWeek: number[];
+
+  /**
+   * Window start time in 24-hour 'HH:MM' format (inclusive).
+   * @example '09:00'
+   */
+  windowStart: string;
+
+  /**
+   * Window end time in 24-hour 'HH:MM' format (exclusive).
+   * @example '18:00'
+   */
+  windowEnd: string;
+}
+
+/**
+ * Returns a SessionGuard active within the specified business-hours window.
+ *
+ * The window is evaluated in the given timezone — pass 'UTC' for UTC-anchored
+ * agents (e.g. dreams 02:00–05:00 UTC).
+ *
+ * @throws {Error} if `windowStart` / `windowEnd` are not valid 'HH:MM' strings.
+ */
+export function businessHours(opts: BusinessHoursOptions): SessionGuard {
+  const tz = opts.tz ?? "UTC";
+  const startMinutes = parseHHMM(opts.windowStart, "windowStart");
+  const endMinutes = parseHHMM(opts.windowEnd, "windowEnd");
+  const activeDays = new Set(opts.daysOfWeek);
+
+  const name = `business-hours:${tz}:${opts.windowStart}-${opts.windowEnd}`;
+
+  return {
+    name,
+
+    async isActive(at: Date): Promise<boolean> {
+      const parts = getDateParts(at, tz);
+
+      // ISO day-of-week: 1=Mon … 7=Sun
+      if (!activeDays.has(parts.isoDow)) {
+        return false;
+      }
+
+      const minutesFromMidnight = parts.hour * 60 + parts.minute;
+      return (
+        minutesFromMidnight >= startMinutes &&
+        minutesFromMidnight < endMinutes
+      );
+    },
+  };
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────
+
+interface DateParts {
+  hour: number;
+  minute: number;
+  /** ISO day-of-week: 1=Mon, 7=Sun */
+  isoDow: number;
+}
+
+function getDateParts(at: Date, tz: string): DateParts {
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+    weekday: "short",
+  });
+
+  const parts = fmt.formatToParts(at);
+  const get = (type: string): string =>
+    parts.find((p) => p.type === type)?.value ?? "0";
+
+  // en-US "short" weekday → ISO day-of-week mapping
+  const isoMap: Record<string, number> = {
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+    Sun: 7,
+  };
+
+  const hour = Number(get("hour")) % 24;
+  const minute = Number(get("minute"));
+  const isoDow = isoMap[get("weekday")] ?? 1;
+
+  return { hour, minute, isoDow };
+}
+
+function parseHHMM(value: string, fieldName: string): number {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(value);
+  if (!match) {
+    throw new Error(
+      `businessHours: invalid ${fieldName} '${value}' — expected 'HH:MM'`,
+    );
+  }
+  const h = Number(match[1]);
+  const m = Number(match[2]);
+  if (h > 23 || m > 59) {
+    throw new Error(
+      `businessHours: ${fieldName} '${value}' out of range (00:00–23:59)`,
+    );
+  }
+  return h * 60 + m;
+}

package/src/orchestration/ooda/guards/cme-holidays-2026.json

@@ -0,0 +1 @@
+["2026-01-01", "2026-01-19", "2026-02-16", "2026-04-03", "2026-05-25", "2026-06-19", "2026-07-03", "2026-09-07", "2026-11-26", "2026-12-25"]

package/src/orchestration/ooda/guards/index.ts

@@ -0,0 +1,27 @@
+/**
+ * OODA built-in guards barrel.
+ *
+ * Re-exports all guard factories and their public types.
+ * Import path: '@vauban-org/agent-sdk' → (future barrel update) or
+ * direct: '@vauban-org/agent-sdk/src/orchestration/ooda/guards/index.js'
+ *
+ * @public
+ */
+
+export {
+  redisCircuitBreaker,
+  tripCircuitBreaker,
+  resetCircuitBreaker,
+  type CircuitBreakerResetMode,
+  type RedisCircuitBreakerOptions,
+  type MinimalRedisClient,
+} from "./redis-circuit-breaker.js";
+
+export { rthSession, type RTHSessionOptions } from "./rth-session.js";
+
+export {
+  businessHours,
+  type BusinessHoursOptions,
+} from "./business-hours.js";
+
+export { alwaysOn } from "./always-on.js";

package/src/orchestration/ooda/guards/redis-circuit-breaker.ts

@@ -0,0 +1,172 @@
+/**
+ * redis-circuit-breaker — Redis-backed OODA RiskGuard.
+ *
+ * V5 anti-pattern #4 fix: resetVia is EXPLICIT ('cron-rth' | 'admin-endpoint' |
+ * 'never') — NOT TTL-based blind expiry. A tripped circuit stays tripped until
+ * an explicit reset action fires (cron job at RTH open, admin endpoint call, or
+ * never — for manual-only recovery).
+ *
+ * Redis key: `cb:<name>:tripped` = "1" when tripped, absent when clear.
+ *
+ * Decoupled from src/router/circuit-breaker.ts — the agent SDK must not import
+ * from the CC server layer. This is a standalone, minimal implementation.
+ *
+ * @public
+ */
+
+import type { RiskGuard, OODAContext } from "../types.js";
+
+// ─── Public types ─────────────────────────────────────────────────────────
+
+/**
+ * How the circuit breaker is reset after being tripped.
+ *
+ * - `cron-rth`       : reset by a cron job aligned with RTH session open
+ *                      (e.g. 09:30 ET Mon-Fri — implemented externally).
+ * - `admin-endpoint` : reset only via an explicit admin API call.
+ * - `never`          : manual Redis delete only — no automated reset.
+ *
+ * Anti-pattern #4: NO TTL-based blind reset. The key never expires on its own.
+ */
+export type CircuitBreakerResetMode =
+  | "cron-rth"
+  | "admin-endpoint"
+  | "never";
+
+export interface RedisCircuitBreakerOptions {
+  /** Unique name per agent+rule — becomes the Redis key segment. */
+  name: string;
+  /**
+   * Redis URL. Defaults to `process.env.REDIS_URL`.
+   * Inject a custom client factory via `redisClientFactory` for tests.
+   */
+  redisUrl?: string;
+  /**
+   * Number of consecutive failures before the circuit trips.
+   * Not auto-tripped by the guard itself (tripping is done by callers via
+   * `tripCircuitBreaker`). This field is informational / for external
+   * monitoring tooling.
+   */
+  failureThreshold: number;
+  /**
+   * V5 anti-pattern #4: explicit reset mode — NOT TTL aveugle.
+   * Included in the `reason` string for observability.
+   */
+  resetVia: CircuitBreakerResetMode;
+  /**
+   * Optional Redis client factory — inject for unit tests.
+   * Factory receives the resolved Redis URL and returns a minimal client.
+   *
+   * @internal
+   */
+  _redisClientFactory?: (url: string) => MinimalRedisClient;
+}
+
+/**
+ * Minimal Redis client interface — satisfied by ioredis and Map-based mocks.
+ */
+export interface MinimalRedisClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<unknown>;
+  del(key: string): Promise<unknown>;
+  quit(): Promise<unknown>;
+}
+
+// ─── Guard factory ────────────────────────────────────────────────────────
+
+/**
+ * Returns a RiskGuard that blocks the OODA cycle when the named circuit
+ * breaker is tripped in Redis.
+ *
+ * The guard itself is read-only — it never trips or resets the breaker.
+ * Use `tripCircuitBreaker` / `resetCircuitBreaker` from external code
+ * (failure handlers, admin endpoints, cron jobs).
+ */
+export function redisCircuitBreaker(
+  opts: RedisCircuitBreakerOptions,
+): RiskGuard {
+  const redisKey = `cb:${opts.name}:tripped`;
+
+  return {
+    name: `redis-cb:${opts.name}`,
+
+    async check(_ctx: OODAContext): Promise<{ proceed: boolean; reason?: string }> {
+      const url = opts.redisUrl ?? process.env["REDIS_URL"] ?? "redis://localhost:6379";
+      const client = opts._redisClientFactory
+        ? opts._redisClientFactory(url)
+        : await createIoRedisClient(url);
+
+      try {
+        const val = await client.get(redisKey);
+        if (val === "1") {
+          return {
+            proceed: false,
+            reason: `Circuit breaker '${opts.name}' tripped (resetVia=${opts.resetVia})`,
+          };
+        }
+        return { proceed: true };
+      } finally {
+        await client.quit().catch(() => undefined);
+      }
+    },
+  };
+}
+
+// ─── Trip / reset helpers ─────────────────────────────────────────────────
+
+/**
+ * Trip the named circuit breaker in Redis.
+ * The key has NO expiry — reset is always explicit (anti-pattern #4).
+ */
+export async function tripCircuitBreaker(
+  redisUrl: string,
+  name: string,
+  redisClientFactory?: (url: string) => MinimalRedisClient,
+): Promise<void> {
+  const client = redisClientFactory
+    ? redisClientFactory(redisUrl)
+    : await createIoRedisClient(redisUrl);
+
+  try {
+    await client.set(`cb:${name}:tripped`, "1");
+  } finally {
+    await client.quit().catch(() => undefined);
+  }
+}
+
+/**
+ * Reset the named circuit breaker in Redis (remove the trip key).
+ * Called by cron-rth jobs, admin endpoints, or manual ops.
+ */
+export async function resetCircuitBreaker(
+  redisUrl: string,
+  name: string,
+  redisClientFactory?: (url: string) => MinimalRedisClient,
+): Promise<void> {
+  const client = redisClientFactory
+    ? redisClientFactory(redisUrl)
+    : await createIoRedisClient(redisUrl);
+
+  try {
+    await client.del(`cb:${name}:tripped`);
+  } finally {
+    await client.quit().catch(() => undefined);
+  }
+}
+
+// ─── ioredis client factory ───────────────────────────────────────────────
+
+async function createIoRedisClient(url: string): Promise<MinimalRedisClient> {
+  // Dynamic import keeps ioredis as a peer dep — tests can inject a mock factory
+  // without pulling the full ioredis module.
+  const { default: IORedis } = await import("ioredis");
+  const client = new IORedis(url, {
+    // Fail-fast: if Redis is unreachable, throw immediately rather than queuing.
+    enableOfflineQueue: false,
+    connectTimeout: 3_000,
+    maxRetriesPerRequest: 1,
+    lazyConnect: true,
+  });
+  await client.connect();
+  return client;
+}