@vauban-org/agent-sdk 0.16.0

package/src/orchestration/ooda/guards/rth-session.ts

@@ -0,0 +1,133 @@
+/**
+ * rth-session — NYSE/CME Regular Trading Hours session guard.
+ *
+ * Active: Monday–Friday 09:30–16:00 America/New_York, excluding CME holidays.
+ * CME 2026 holiday list is static JSON — update yearly (see CME calendar:
+ * https://www.cmegroup.com/tools-information/holiday-calendar.html).
+ *
+ * Anti-pattern #5: session guard is consulted on every OODA cycle with the
+ * cycle's `ctx.now` timestamp — no TTL, no caching.
+ *
+ * @public
+ */
+
+import type { SessionGuard } from "../types.js";
+
+// Update yearly — see CME calendar: https://www.cmegroup.com/tools-information/holiday-calendar.html
+const CME_HOLIDAYS_2026: ReadonlySet<string> = new Set([
+  "2026-01-01", // New Year's Day
+  "2026-01-19", // Martin Luther King Jr. Day
+  "2026-02-16", // Presidents' Day
+  "2026-04-03", // Good Friday
+  "2026-05-25", // Memorial Day
+  "2026-06-19", // Juneteenth
+  "2026-07-03", // Independence Day (observed)
+  "2026-09-07", // Labor Day
+  "2026-11-26", // Thanksgiving
+  "2026-12-25", // Christmas
+]);
+
+// RTH window in Eastern Time: 09:30 – 16:00
+const RTH_OPEN_MINUTES = 9 * 60 + 30; // 570
+const RTH_CLOSE_MINUTES = 16 * 60; // 960
+
+export interface RTHSessionOptions {
+  /**
+   * IANA timezone string for Eastern Time.
+   * Override in tests only — production always uses 'America/New_York'.
+   * @defaultValue 'America/New_York'
+   */
+  tz?: string;
+}
+
+/**
+ * Returns a SessionGuard that is active during NYSE/CME Regular Trading Hours:
+ * Monday–Friday 09:30–16:00 America/New_York, excluding CME 2026 holidays.
+ */
+export function rthSession(opts?: RTHSessionOptions): SessionGuard {
+  const tz = opts?.tz ?? "America/New_York";
+
+  return {
+    name: "rth-session",
+
+    async isActive(at: Date): Promise<boolean> {
+      // Resolve date parts in Eastern Time using Intl.DateTimeFormat
+      const parts = getDateParts(at, tz);
+
+      // Weekend check (0=Sunday, 6=Saturday)
+      if (parts.weekday === 0 || parts.weekday === 6) {
+        return false;
+      }
+
+      // CME holiday check — ISO date string in ET
+      const isoDate = formatISODate(parts);
+      if (CME_HOLIDAYS_2026.has(isoDate)) {
+        return false;
+      }
+
+      // RTH window check
+      const minutesFromMidnight = parts.hour * 60 + parts.minute;
+      return (
+        minutesFromMidnight >= RTH_OPEN_MINUTES &&
+        minutesFromMidnight < RTH_CLOSE_MINUTES
+      );
+    },
+  };
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────
+
+interface DateParts {
+  year: number;
+  month: number; // 1-based
+  day: number;
+  hour: number;
+  minute: number;
+  weekday: number; // 0=Sunday, 6=Saturday
+}
+
+function getDateParts(at: Date, tz: string): DateParts {
+  // Use Intl.DateTimeFormat to extract wall-clock components in the target tz.
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    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";
+
+  // Intl weekday "short" in en-US: Sun, Mon, Tue, Wed, Thu, Fri, Sat
+  const weekdayMap: Record<string, number> = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+  };
+
+  const hour = Number(get("hour")) % 24; // "24" → 0 in hour12=false edge case
+
+  return {
+    year: Number(get("year")),
+    month: Number(get("month")),
+    day: Number(get("day")),
+    hour,
+    minute: Number(get("minute")),
+    weekday: weekdayMap[get("weekday")] ?? 0,
+  };
+}
+
+function formatISODate(parts: DateParts): string {
+  const mm = String(parts.month).padStart(2, "0");
+  const dd = String(parts.day).padStart(2, "0");
+  return `${parts.year}-${mm}-${dd}`;
+}

package/src/orchestration/ooda/handoff.ts

@@ -0,0 +1,150 @@
+/**
+ * Multi-agent handoff — Agent → Agent execution with history forwarding.
+ *
+ * Sprint-563: B2 — Multi-agent handoff() + asAgentTool() + handoffChain anti-cycle.
+ *
+ * handoff() wraps AgentsClient.execute with history forwarding (messages[]).
+ * handoffChain: string[] prevents infinite cycles (HandoffCycleError if agent
+ *   appears twice in the chain).
+ * asAgentTool(descriptor, client) → AgentTool capability for MCP consumption.
+ */
+
+import type { CycleEventV011, OODAContext } from "./types.js";
+
+// ─── Handoff types ───────────────────────────────────────────────────────────
+
+export interface HandoffOptions {
+  /** Target agent ID to hand off to. */
+  targetAgentId: string;
+  /** Messages to forward (history). */
+  messages: Array<{ role: string; content: string }>;
+  /** Chain of agents that have already participated (anti-cycle). */
+  handoffChain: string[];
+  /** OODA context from the calling agent. */
+  ctx: OODAContext;
+}
+
+export interface HandoffResult {
+  /** The child run ID created in the target agent. */
+  childRunId: string;
+  /** The handoff chain including the target (for the child to use). */
+  nextChain: string[];
+  /** Whether the handoff was accepted. */
+  accepted: boolean;
+}
+
+export class HandoffCycleError extends Error {
+  constructor(agentId: string, chain: string[]) {
+    super(
+      `Handoff cycle detected: agent "${agentId}" already in chain [${chain.join(" → ")} → ${agentId}]. Aborting.`,
+    );
+    this.name = "HandoffCycleError";
+  }
+}
+
+export interface AgentHandoffClient {
+  execute(agentId: string, input: { messages: Array<{ role: string; content: string }>; handoffChain: string[] }): Promise<{ runId: string }>;
+}
+
+/**
+ * Execute a handoff to another agent. Forwards messages[] and checks for cycles.
+ * Throws HandoffCycleError if the target agent is already in the chain.
+ */
+export async function handoff(
+  opts: HandoffOptions,
+  client: AgentHandoffClient,
+): Promise<HandoffResult> {
+  const { targetAgentId, messages, handoffChain } = opts;
+
+  if (handoffChain.includes(targetAgentId)) {
+    throw new HandoffCycleError(targetAgentId, handoffChain);
+  }
+
+  const result = await client.execute(targetAgentId, {
+    messages,
+    handoffChain: [...handoffChain, targetAgentId],
+  });
+
+  return {
+    childRunId: result.runId,
+    nextChain: [...handoffChain, targetAgentId],
+    accepted: true,
+  };
+}
+
+/**
+ * Build a CycleEventV011 'handoff_initiated' event.
+ */
+export function handoffToEvent(
+  targetAgentId: string,
+  childRunId: string,
+  handoffChain: string[],
+  runId: string,
+  cycleIndex: number,
+): Extract<CycleEventV011, { type: "handoff_initiated" }> {
+  return {
+    type: "handoff_initiated",
+    runId,
+    cycleIndex,
+    targetAgentId,
+    childRunId,
+    handoffChain,
+    ts: Date.now(),
+  };
+}
+
+/**
+ * Convert an agent descriptor into an MCP-compatible AgentTool.
+ * Tools exposed this way can be called by other agents via MCP.
+ */
+export interface AgentDescriptor {
+  agentId: string;
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export async function asAgentTool(
+  descriptor: AgentDescriptor,
+  client: AgentHandoffClient,
+): Promise<{
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (input: { messages: Array<{ role: string; content: string }>; handoffChain?: string[] }) => Promise<{ runId: string }>;
+}> {
+  return {
+    name: `agent_${descriptor.agentId.replace(/[^a-zA-Z0-9_]/g, "_")}`,
+    description: `Handoff to agent: ${descriptor.name} — ${descriptor.description}`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        messages: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              role: { type: "string", enum: ["system", "user", "assistant", "tool"] },
+              content: { type: "string" },
+            },
+            required: ["role", "content"],
+          },
+          description: "Conversation history to forward to the agent",
+        },
+        handoffChain: {
+          type: "array",
+          items: { type: "string" },
+          description: "Chain of agents that have already participated (anti-cycle)",
+        },
+      },
+      required: ["messages"],
+      additionalProperties: false,
+    },
+    async handler(input) {
+      return client.execute(descriptor.agentId, {
+        messages: input.messages,
+        handoffChain: input.handoffChain ?? [],
+      });
+    },
+  };
+}

package/src/orchestration/ooda/hitl-gate.ts

@@ -0,0 +1,166 @@
+/**
+ * OODA HITL gate — sprint-525:quick-2.
+ *
+ * Blocks the OODA `act` phase until a human approves (or rejects) the
+ * pending decision. In `dry-run` execution mode the gate is a no-op
+ * (auto-approve) so simulation runs do not require human attention.
+ *
+ * Live mode persists a row in `hitl_approvals` (status=`pending`) and
+ * polls every 2s until a row reaches `approved` / `rejected` or until
+ * the configured timeout elapses. On timeout, the `onTimeout` policy
+ * decides the verdict.
+ *
+ * The DbClient interface is the same minimal subset used elsewhere in
+ * the SDK (compatible with pg.Pool, pg.Client, and test mocks).
+ *
+ * @public
+ */
+
+import type { DbClient } from "../../tracking/agent-run-tracker.js";
+import type { ExecutionMode } from "./types.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type HITLOnTimeoutPolicy = "reject" | "approve" | "continue-skip";
+
+export interface HITLGateOptions {
+  /** Hard wait before applying onTimeout policy. Default: 5 minutes. */
+  timeoutMs?: number;
+  /** Verdict on timeout. Default: "reject". */
+  onTimeout?: HITLOnTimeoutPolicy;
+  /** Polling interval for live mode. Default: 2000 ms. */
+  pollIntervalMs?: number;
+}
+
+export interface HITLGateArgs {
+  runId: string;
+  agentId: string;
+  decisionPayload: Record<string, unknown>;
+  executionMode: ExecutionMode;
+}
+
+export interface HITLGateVerdict {
+  approved: boolean;
+  rationale?: string;
+  resolvedBy?: string;
+  timedOut: boolean;
+}
+
+// ─── Defaults ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+const DEFAULT_ON_TIMEOUT: HITLOnTimeoutPolicy = "reject";
+
+// ─── Internal row shape ───────────────────────────────────────────────────────
+
+interface HitlRow {
+  id: string;
+  status: "pending" | "approved" | "rejected";
+  rationale: string | null;
+  resolved_by: string | null;
+}
+
+/**
+ * Wait for a HITL approval before allowing the agent to commit the act
+ * phase. In `dry-run` mode this short-circuits to `approved=true` so
+ * simulation runs are non-blocking.
+ *
+ * Live mode contract:
+ *   1. INSERT a row in `hitl_approvals` with status='pending'
+ *   2. Poll every `pollIntervalMs` (default 2s) for status change
+ *   3. Resolve when status transitions to approved/rejected
+ *   4. On timeout: apply onTimeout policy (default 'reject')
+ *
+ * The polling interval is intentionally generous (2s) to avoid DB
+ * pressure under sustained workloads — UX latency is bounded by the
+ * human approval round-trip anyway.
+ */
+export async function waitForHITLApproval(
+  db: DbClient,
+  args: HITLGateArgs,
+  options: HITLGateOptions = {},
+): Promise<HITLGateVerdict> {
+  // Auto-approve in dry-run regardless of DB state.
+  if (args.executionMode === "dry-run") {
+    return { approved: true, timedOut: false, resolvedBy: "dry-run-auto" };
+  }
+
+  if (args.executionMode !== "live") {
+    throw new Error(`[ooda/hitl-gate] invalid executionMode: ${String(args.executionMode)}`);
+  }
+
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const onTimeout = options.onTimeout ?? DEFAULT_ON_TIMEOUT;
+
+  // 1. INSERT pending row (returns id).
+  const insert = await db.query<{ id: string }>(
+    `INSERT INTO hitl_approvals
+       (run_id, agent_id, decision_payload, status, requested_at)
+     VALUES
+       ($1, $2, $3::jsonb, 'pending', now())
+     RETURNING id`,
+    [args.runId, args.agentId, JSON.stringify(args.decisionPayload)],
+  );
+
+  const row = insert.rows[0];
+  if (!row) {
+    throw new Error("[ooda/hitl-gate] insert returned no row");
+  }
+  const hitlId = row.id;
+
+  // 2. Poll loop with hard deadline.
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    const sleepMs = Math.min(pollIntervalMs, Math.max(remaining, 0));
+    await sleep(sleepMs);
+
+    const poll = await db.query<HitlRow>(
+      `SELECT id, status, rationale, resolved_by
+         FROM hitl_approvals
+        WHERE id = $1`,
+      [hitlId],
+    );
+    const current = poll.rows[0];
+    if (!current) {
+      // Row vanished (cancellation) — treat as rejected.
+      return { approved: false, timedOut: false, rationale: "row-missing" };
+    }
+    if (current.status === "approved") {
+      return {
+        approved: true,
+        timedOut: false,
+        rationale: current.rationale ?? undefined,
+        resolvedBy: current.resolved_by ?? undefined,
+      };
+    }
+    if (current.status === "rejected") {
+      return {
+        approved: false,
+        timedOut: false,
+        rationale: current.rationale ?? undefined,
+        resolvedBy: current.resolved_by ?? undefined,
+      };
+    }
+  }
+
+  // 3. Timeout reached — apply policy.
+  const approvedOnTimeout = onTimeout === "approve" || onTimeout === "continue-skip";
+  return {
+    approved: approvedOnTimeout,
+    timedOut: true,
+    rationale: `timeout:${onTimeout}`,
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    if (ms <= 0) {
+      resolve();
+      return;
+    }
+    setTimeout(resolve, ms);
+  });
+}

package/src/orchestration/ooda/index.ts

@@ -0,0 +1,163 @@
+/**
+ * OODA orchestration primitive — public barrel.
+ *
+ * @public
+ */
+
+export type {
+  OODAPhaseKind,
+  ExecutionMode,
+  OODAContext,
+  PhaseDef,
+  SessionGuard,
+  RiskGuard,
+  OutcomeRecord,
+  ResourceLimits,
+  OODAAgentConfig,
+  OODAAgent,
+  CycleStatus,
+  CycleEvent,
+  CycleEventV010,
+  CycleEventV011,
+} from "./types.js";
+export { DEFAULT_RESOURCE_LIMITS } from "./types.js";
+
+export type { Skill, SkillContext, SkillRegistry } from "./skills.js";
+export { EMPTY_SKILL_REGISTRY } from "./skills.js";
+
+export { OODAAgentImpl } from "./agent.js";
+export { createOODAAgent } from "./factory.js";
+
+// Brain context auto-injection for ORIENT (sprint-525:quick-4)
+export type {
+  BrainCallResult,
+  BrainChunk,
+  BrainContextOptions,
+  DegradedResponse,
+  OrientInputWithBrain,
+} from "./brain-context.js";
+export {
+  BrainSkillNotConfiguredError,
+  isDegradedResponse,
+  withBrainContext,
+} from "./brain-context.js";
+
+// Hot-reload config loader (sprint-525:quick-7)
+export type { AgentConfigLoader } from "./agent-config-loader.js";
+export { createAgentConfigLoader } from "./agent-config-loader.js";
+
+// Persistence + HITL gate + EXECUTION_MODE guard + resource runner (sprint-525:quick-2)
+export {
+  insertRunStep,
+  completeRunStep,
+  errorRunStep,
+} from "./run-step-persistence.js";
+export type { InsertRunStepInput } from "./run-step-persistence.js";
+
+export { waitForHITLApproval } from "./hitl-gate.js";
+export type {
+  HITLGateOptions,
+  HITLGateArgs,
+  HITLGateVerdict,
+  HITLOnTimeoutPolicy,
+} from "./hitl-gate.js";
+
+export {
+  assertExecutionMode,
+  readExecutionModeFromEnv,
+} from "./execution-mode-guard.js";
+
+export {
+  ResourceLimitsRunner,
+  StepCountExceededError,
+} from "./resource-limits.js";
+export type { ResourceLimitsOpts } from "./resource-limits.js";
+
+export { recordHITLDecision } from "./audit-log.js";
+export type { HITLDecision } from "./audit-log.js";
+
+// Redis circuit breaker guards (sprint-525:quick-3 + sprint-526:quick-3)
+export {
+  redisCircuitBreaker,
+  tripCircuitBreaker,
+  resetCircuitBreaker,
+} from "./guards/redis-circuit-breaker.js";
+export type {
+  CircuitBreakerResetMode,
+  RedisCircuitBreakerOptions,
+  MinimalRedisClient,
+} from "./guards/redis-circuit-breaker.js";
+
+// Session guards (sprint-525:quick-3 + sprint-526:quick-2)
+export { rthSession } from "./guards/rth-session.js";
+export type { RTHSessionOptions } from "./guards/rth-session.js";
+export { businessHours } from "./guards/business-hours.js";
+export type { BusinessHoursOptions } from "./guards/business-hours.js";
+export { alwaysOn } from "./guards/always-on.js";
+
+// MultiModal observation — sprint-525:quick-6
+export type {
+  ImageMediaType,
+  AudioMediaType,
+  MultiModalObservation,
+  AnthropicTextBlock,
+  AnthropicImageBlock,
+  AnthropicDocumentBlock,
+  AnthropicContentBlock,
+} from "./multimodal.js";
+export { isMultiModal, multiModalToAnthropicContent } from "./multimodal.js";
+
+// ChildAgentPort — sprint-565:2
+export type {
+  ChildAgentPort,
+  ChildAgentOptions,
+  ChildAgentResult,
+} from "./child-agent.js";
+
+// ReactLoop — sprint-565:3
+export type {
+  ToolCall,
+  ReactStep,
+  ReactResult,
+  LLMCompletionFn,
+  ReactMessage,
+  LLMReactResponse,
+  ReactLoopOptions,
+} from "./react-loop.js";
+export { reactLoop } from "./react-loop.js";
+
+// Plan-and-Execute — sprint-565:8a
+export type {
+  PlanStep,
+  Plan,
+  StepResult,
+  PlanExecutionResult,
+} from "./plan-execute.js";
+export { decomposeTask, executeStep } from "./plan-execute.js";
+
+// Reflexion Memory — sprint-565:8a
+export type { ReflexionEntry, ReflexionQuery } from "./reflexion.js";
+export { storeReflexion, queryReflexionMemory } from "./reflexion.js";
+
+// Multi-Agent Debate — sprint-565:8b
+export type {
+  DebateStance,
+  DebateSynthesis,
+  DebateResult,
+  DebateConfig,
+} from "./debate.js";
+export { runDebate } from "./debate.js";
+
+// Inner Monologue — sprint-565:8b
+export type {
+  InnerMonologueInput,
+  InnerMonologueOutput,
+} from "./inner-monologue.js";
+export { SensitiveValue, innerMonologue } from "./inner-monologue.js";
+
+// CronExpression scheduling — sprint-565:5
+export { cronSessionGuard } from "./cron-schedule.js";
+
+// EconomicObserver — sprint-565:9
+export type { EconomicObserver } from "./economic-observer.js";
+export { economicObserverGuard } from "./economic-observer.js";