@vauban-org/agent-sdk 0.16.0

package/src/orchestration/ooda/react-loop.ts

@@ -0,0 +1,192 @@
+/**
+ * ReactLoop — Reason + Act tool-calling loop for the act phase.
+ *
+ * Thought → Action → Observation loop with maxStep guard. Model-agnostic:
+ * accepts an `LLMCompletionFn` that decouples from any specific provider.
+ *
+ * Used within the `act` phase of an OODA cycle when the agent needs multi-step
+ * reasoning with tool calls (ReAct pattern).
+ *
+ * Loop stops on:
+ *   - Final answer (no tool call in response)
+ *   - maxSteps reached
+ *   - LLM error
+ *   - AbortSignal fired
+ *
+ * @public
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────────
+
+export interface ToolCall {
+  /** Tool name. */
+  tool: string;
+  /** Tool arguments — arbitrary JSON-serializable value. */
+  args: Record<string, unknown>;
+}
+
+export interface ReactStep {
+  /** Step index (0-based). */
+  index: number;
+  /** The LLM's reasoning / thought before the tool call. */
+  thought: string;
+  /** The tool call extracted from the LLM response, if any. */
+  action?: ToolCall;
+  /** The result of executing the tool, if a tool was called. */
+  observation?: string;
+  /** Error message if the tool call failed. */
+  error?: string;
+}
+
+export interface ReactResult {
+  /** Final answer from the LLM. */
+  answer: string;
+  /** All steps taken during the loop. */
+  steps: ReactStep[];
+  /** Total steps executed. */
+  totalSteps: number;
+  /** Whether the loop was stopped by maxSteps. */
+  truncated: boolean;
+}
+
+/**
+ * LLM completion function — model-agnostic interface.
+ *
+ * Accepts a list of messages and returns the LLM's response text.
+ * Tool calls are parsed from the response text (JSON blocks or structured
+ * API tool calls — implementation decides).
+ */
+export type LLMCompletionFn = (
+  messages: ReactMessage[]
+) => Promise<LLMReactResponse>;
+
+export interface ReactMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  /** Tool call ID (for 'tool' role messages). */
+  tool_call_id?: string;
+  /** Tool name (for 'assistant' messages with tool calls). */
+  name?: string;
+}
+
+export interface LLMReactResponse {
+  /** The full response text. */
+  content: string;
+  /** Parsed tool calls, if any. */
+  toolCalls?: ToolCall[];
+  /** Whether this is a final answer (no tool calls). */
+  isFinal: boolean;
+}
+
+export interface ReactLoopOptions {
+  /** Max steps before forced stop (default: 10). */
+  maxSteps?: number;
+  /** System prompt for the LLM. */
+  systemPrompt: string;
+  /** Initial user message / task description. */
+  task: string;
+  /** LLM completion function. */
+  llm: LLMCompletionFn;
+  /** Execute a tool call and return the result. */
+  executeTool: (call: ToolCall) => Promise<string>;
+  /** AbortSignal for cancellation. */
+  signal?: AbortSignal;
+  /** 10KB limit on parsed tool call JSON to prevent DoS. */
+  maxToolCallSize?: number;
+  /** Allowed tool names. Unlisted tools get an error feedback. */
+  allowedTools?: string[];
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_STEPS = 10;
+const DEFAULT_MAX_TOOL_CALL_SIZE = 10_240; // 10KB
+
+// ─── Loop ───────────────────────────────────────────────────────────────────────
+
+/**
+ * Run a ReAct (Reasoning + Acting) loop.
+ *
+ * ```
+ * Thought → Action → Observation → Thought → ... → Final Answer
+ * ```
+ */
+export async function reactLoop(opts: ReactLoopOptions): Promise<ReactResult> {
+  const maxSteps = opts.maxSteps ?? DEFAULT_MAX_STEPS;
+  const maxToolCallSize = opts.maxToolCallSize ?? DEFAULT_MAX_TOOL_CALL_SIZE;
+  const allowedTools = opts.allowedTools;
+
+  const steps: ReactStep[] = [];
+  const messages: ReactMessage[] = [
+    { role: "system", content: opts.systemPrompt },
+    { role: "user", content: opts.task },
+  ];
+
+  for (let i = 0; i < maxSteps; i++) {
+    if (opts.signal?.aborted) {
+      return { answer: "", steps, totalSteps: i, truncated: true };
+    }
+
+    // Thought → Action
+    const response = await opts.llm(messages);
+    steps.push({
+      index: i,
+      thought: response.content,
+      action: response.toolCalls?.[0],
+    });
+
+    // Final answer — no tool call
+    if (response.isFinal || !response.toolCalls || response.toolCalls.length === 0) {
+      return { answer: response.content, steps, totalSteps: i + 1, truncated: false };
+    }
+
+    const toolCall = response.toolCalls[0];
+
+    // Validate tool call size
+    const toolJson = JSON.stringify(toolCall);
+    if (toolJson.length > maxToolCallSize) {
+      steps[i].error = `Tool call exceeds ${maxToolCallSize}B limit`;
+      steps[i].observation = `Error: tool call too large (${toolJson.length}B > ${maxToolCallSize}B limit)`;
+      messages.push(
+        { role: "assistant", content: response.content, name: toolCall.tool },
+        { role: "tool", content: steps[i].observation!, tool_call_id: `call_${i}` }
+      );
+      continue;
+    }
+
+    // Check allowed tools
+    if (allowedTools && !allowedTools.includes(toolCall.tool)) {
+      steps[i].error = `Tool "${toolCall.tool}" not in allowed list`;
+      steps[i].observation = `Error: tool "${toolCall.tool}" is not allowed. Available tools: ${allowedTools.join(", ")}`;
+      messages.push(
+        { role: "assistant", content: response.content, name: toolCall.tool },
+        { role: "tool", content: steps[i].observation!, tool_call_id: `call_${i}` }
+      );
+      continue;
+    }
+
+    // Observation — execute tool
+    try {
+      const observation = await opts.executeTool(toolCall);
+      steps[i].observation = observation;
+    } catch (err) {
+      steps[i].error = err instanceof Error ? err.message : String(err);
+      steps[i].observation = `Error executing tool "${toolCall.tool}": ${steps[i].error}`;
+    }
+
+    // Feed observation back into the conversation
+    messages.push(
+      { role: "assistant", content: response.content, name: toolCall.tool },
+      { role: "tool", content: steps[i].observation!, tool_call_id: `call_${i}` }
+    );
+  }
+
+  // Truncated — max steps reached
+  const lastStep = steps[steps.length - 1];
+  return {
+    answer: lastStep?.thought ?? "",
+    steps,
+    totalSteps: maxSteps,
+    truncated: true,
+  };
+}

package/src/orchestration/ooda/reflexion.ts

@@ -0,0 +1,98 @@
+/**
+ * Reflexion Memory — Brain-stored lessons for future cycles.
+ *
+ * Safety constraints (non-negotiable):
+ *   - confidence MUST be > 0.6 for retrieval (prevents low-quality lessons from
+ *     poisoning future decisions).
+ *   - TTL defaults to 30 days (stale lessons expire).
+ *   - Every entry carries `sourceCycleId` and `outcomeType` for traceability.
+ *   - Brain stores with category="forge_reflexion", tags=["reflexion", "agent:<id>"].
+ *
+ * A single incorrect reflection persisting in a long-running agent is
+ * catastrophic — severity scales with agent lifetime. Confidence weighting
+ * + TTL guard against reflexion poisoning.
+ *
+ * @public
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────────
+
+export interface ReflexionEntry {
+  /** The lesson learned. */
+  content: string;
+  /** Confidence score (0.0 - 1.0). MUST be provided. */
+  confidence: number;
+  /** The cycle that generated this lesson. */
+  sourceCycleId: string;
+  /** What happened: "succeeded" | "failed" | "partial". */
+  outcomeType: "succeeded" | "failed" | "partial";
+  /** Time-to-live in milliseconds (default: 30 days). */
+  ttlMs?: number;
+}
+
+export interface ReflexionQuery {
+  agentId: string;
+  /** Only match entries for this outcome type. */
+  outcomeType?: "succeeded" | "failed" | "partial";
+  /** Max entries to return (default: 5). */
+  limit?: number;
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────────────
+
+const MIN_CONFIDENCE = 0.6;
+const DEFAULT_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+// ─── Store / Query ──────────────────────────────────────────────────────────────
+
+/**
+ * Store a reflexion entry via a BrainPort-compatible archival function.
+ *
+ * The `archiver` is typically `brain.archiveKnowledge()` or
+ * `semantic.archive()`.
+ */
+export async function storeReflexion(
+  entry: ReflexionEntry,
+  agentId: string,
+  archiver: (input: {
+    content: string;
+    category?: string;
+    tags?: string[];
+    confidence?: number;
+    metadata?: Record<string, unknown>;
+  }) => Promise<unknown>
+): Promise<void> {
+  await archiver({
+    content: entry.content,
+    category: "forge_reflexion",
+    tags: ["reflexion", `agent:${agentId}`],
+    confidence: entry.confidence,
+    metadata: {
+      sourceCycleId: entry.sourceCycleId,
+      outcomeType: entry.outcomeType,
+      ttlMs: entry.ttlMs ?? DEFAULT_TTL_MS,
+    },
+  });
+}
+
+/**
+ * Query reflexion memory.
+ *
+ * ONLY returns entries with confidence > 0.6 AND within TTL window.
+ * The `querier` is typically `brain.queryKnowledge()` or `semantic.query()`.
+ */
+export async function queryReflexionMemory(
+  query: ReflexionQuery,
+  querier: (q: string, filters?: Record<string, unknown>) => Promise<ReflexionEntry[]>
+): Promise<ReflexionEntry[]> {
+  const results = await querier(`reflexion ${query.agentId} ${query.outcomeType ?? ""}`, {
+    category: "forge_reflexion",
+    tags: ["reflexion", `agent:${query.agentId}`],
+    limit: query.limit ?? 5,
+  });
+
+  return results.filter((entry) => {
+    if (entry.confidence < MIN_CONFIDENCE) return false;
+    return true;
+  }).slice(0, query.limit ?? 5);
+}

package/src/orchestration/ooda/resource-limits.ts

@@ -0,0 +1,123 @@
+/**
+ * OODA resource limits runtime — sprint-525:quick-2.
+ *
+ * `ResourceLimitsRunner` is the runtime helper enforcing the
+ * `ResourceLimits` interface declared in `./types.ts` (quick-1).
+ * Hard caps on phase wall-clock, step count per cycle, and process heap
+ * usage. Defaults are conservative; agents with heavier workloads MUST
+ * raise them explicitly via the constructor — there is no implicit
+ * "unlimited" mode.
+ *
+ * Usage:
+ *   const runner = new ResourceLimitsRunner({ phaseTimeoutMs: 90_000 });
+ *   const ac = runner.createPhaseAbortController();
+ *   await runPhase(observePayload, { signal: ac.signal });
+ *   runner.enforceStepCount(steps.length);
+ *   runner.checkHeap();
+ *
+ * @public
+ */
+
+export interface ResourceLimitsOpts {
+  /** Hard wall-clock limit per OODA phase. Default: 60_000 ms. */
+  phaseTimeoutMs: number;
+  /** Max steps allowed per OODA cycle. Default: 200. */
+  maxStepsPerCycle: number;
+  /** Soft heap warning threshold (MiB). Default: 256. */
+  maxHeapMb: number;
+  /** Optional warn sink for heap excess (defaults to console.warn). */
+  onHeapExceeded?: (info: { rssMb: number; heapMb: number; max: number }) => void;
+}
+
+const DEFAULTS: ResourceLimitsOpts = {
+  phaseTimeoutMs: 60_000,
+  maxStepsPerCycle: 200,
+  maxHeapMb: 256,
+};
+
+export class StepCountExceededError extends Error {
+  readonly code = "OODA_STEP_COUNT_EXCEEDED";
+  constructor(currentCount: number, max: number) {
+    super(`[ooda] step count ${currentCount} exceeds max ${max} per cycle`);
+    this.name = "StepCountExceededError";
+  }
+}
+
+export class ResourceLimitsRunner {
+  readonly phaseTimeoutMs: number;
+  readonly maxStepsPerCycle: number;
+  readonly maxHeapMb: number;
+  private readonly onHeapExceeded?: ResourceLimitsOpts["onHeapExceeded"];
+
+  constructor(opts: Partial<ResourceLimitsOpts> = {}) {
+    const merged = { ...DEFAULTS, ...opts };
+    if (merged.phaseTimeoutMs <= 0) {
+      throw new Error("[ooda/resource-limits] phaseTimeoutMs must be > 0");
+    }
+    if (merged.maxStepsPerCycle <= 0) {
+      throw new Error("[ooda/resource-limits] maxStepsPerCycle must be > 0");
+    }
+    if (merged.maxHeapMb <= 0) {
+      throw new Error("[ooda/resource-limits] maxHeapMb must be > 0");
+    }
+    this.phaseTimeoutMs = merged.phaseTimeoutMs;
+    this.maxStepsPerCycle = merged.maxStepsPerCycle;
+    this.maxHeapMb = merged.maxHeapMb;
+    this.onHeapExceeded = merged.onHeapExceeded;
+  }
+
+  /**
+   * Build an AbortController whose signal trips after `phaseTimeoutMs`.
+   * The host is responsible for forwarding the signal to async work
+   * (fetch, MCP calls, child Promise.race, …) so the abort actually
+   * propagates.
+   */
+  createPhaseAbortController(): AbortController {
+    const ac = new AbortController();
+    const timer = setTimeout(() => {
+      ac.abort(new Error(`[ooda] phase timeout after ${this.phaseTimeoutMs}ms`));
+    }, this.phaseTimeoutMs);
+    // Don't keep the event loop alive purely for this watchdog.
+    if (typeof timer === "object" && timer && "unref" in timer) {
+      (timer as { unref?: () => void }).unref?.();
+    }
+    // Cancel the timer on natural abort to free the timer slot.
+    ac.signal.addEventListener("abort", () => clearTimeout(timer), {
+      once: true,
+    });
+    return ac;
+  }
+
+  /**
+   * Throw if `currentCount` exceeds `maxStepsPerCycle`. Caller increments
+   * the counter as steps are committed and calls this before the next
+   * step starts.
+   */
+  enforceStepCount(currentCount: number): void {
+    if (currentCount > this.maxStepsPerCycle) {
+      throw new StepCountExceededError(currentCount, this.maxStepsPerCycle);
+    }
+  }
+
+  /**
+   * Sample the process heap and warn if it exceeds `maxHeapMb`. Pure
+   * observability — never throws (a hard kill is the OS' job).
+   */
+  checkHeap(): void {
+    if (typeof process === "undefined" || typeof process.memoryUsage !== "function") {
+      return;
+    }
+    const mem = process.memoryUsage();
+    const heapMb = mem.heapUsed / (1024 * 1024);
+    const rssMb = mem.rss / (1024 * 1024);
+    if (heapMb > this.maxHeapMb) {
+      const info = { rssMb, heapMb, max: this.maxHeapMb };
+      if (this.onHeapExceeded) {
+        this.onHeapExceeded(info);
+      } else {
+        // eslint-disable-next-line no-console -- intentional fallback when no sink wired
+        console.warn("[ooda/resource-limits] heap exceeded", info);
+      }
+    }
+  }
+}

package/src/orchestration/ooda/run-step-persistence.ts

@@ -0,0 +1,137 @@
+/**
+ * OODA run_step persistence helpers — sprint-525:quick-2.
+ *
+ * Mirrors the pattern from src/router/execution-pipeline.ts (sprint-521):
+ *   insertRunStep  → INSERT row with status='pending', returns stepId
+ *   completeRunStep → UPDATE status='done' + leaf_hash_poseidon (Poseidon JCS)
+ *   errorRunStep    → UPDATE status='error' + error_message
+ *
+ * Decoupled from the command-center monolith: imports computeLeafHash
+ * via the SDK's own poseidon module (shipped sprint-521:quick-13).
+ *
+ * The DbClient interface is the minimal pg.Pool/pg.Client subset already
+ * used by `agent-run-tracker.ts` — keeps the SDK pg-free at install time.
+ *
+ * @public
+ */
+
+import { computeLeafHash } from "@vauban-org/proof-core";
+import type { DbClient } from "../../tracking/agent-run-tracker.js";
+import type { OODAPhaseKind } from "./types.js";
+
+export interface InsertRunStepInput {
+  type: OODAPhaseKind;
+  /** Human-readable phase tag (e.g. "observe", "orient", "decide", "act"). */
+  phase: string;
+  stepIndex: number;
+  payload?: Record<string, unknown>;
+  parentStepId?: string;
+}
+
+/**
+ * Insert a `run_step` row in `pending` state and return the freshly
+ * minted UUID. Caller is responsible for finishing it via
+ * `completeRunStep` / `errorRunStep`.
+ */
+export async function insertRunStep(
+  db: DbClient,
+  runId: string,
+  input: InsertRunStepInput
+): Promise<{ stepId: string }> {
+  if (typeof runId !== "string" || runId.length === 0) {
+    throw new Error("[ooda] insertRunStep: runId must be a non-empty string");
+  }
+  if (!Number.isInteger(input.stepIndex) || (input.stepIndex as number) < 0) {
+    throw new Error(
+      "[ooda] insertRunStep: stepIndex must be a non-negative integer"
+    );
+  }
+
+  const payloadJson = JSON.stringify(input.payload ?? {});
+
+  const res = await db.query<{ id: string }>(
+    `INSERT INTO run_step
+       (run_id, step_index, parent_step_id, type, phase, status, started_at, payload)
+     VALUES
+       ($1, $2, $3, $4, $5, 'pending', now(), $6::jsonb)
+     RETURNING id`,
+    [
+      runId,
+      input.stepIndex,
+      input.parentStepId ?? null,
+      input.type,
+      input.phase,
+      payloadJson,
+    ]
+  );
+
+  const row = res.rows[0];
+  if (!row) {
+    throw new Error("[ooda] insertRunStep: insert returned no row");
+  }
+  return { stepId: row.id };
+}
+
+/**
+ * Mark a `run_step` row as `done`, attach its final payload, and write
+ * the Poseidon leaf hash for cryptographic accountability.
+ *
+ * The leaf hash is computed from the FINAL payload (not the pending one),
+ * keeping the on-disk hash in sync with the canonical state at completion.
+ */
+export async function completeRunStep(
+  db: DbClient,
+  stepId: string,
+  payload: Record<string, unknown>
+): Promise<{ leafHash: string }> {
+  if (typeof stepId !== "string" || stepId.length === 0) {
+    throw new Error(
+      "[ooda] completeRunStep: stepId must be a non-empty string"
+    );
+  }
+  if (
+    payload === null ||
+    typeof payload !== "object" ||
+    Array.isArray(payload)
+  ) {
+    throw new Error("[ooda] completeRunStep: payload must be a plain object");
+  }
+
+  const leafHash = computeLeafHash(payload);
+
+  await db.query(
+    `UPDATE run_step
+        SET status = 'done',
+            finished_at = now(),
+            payload = $2::jsonb,
+            leaf_hash_poseidon = $3
+      WHERE id = $1`,
+    [stepId, JSON.stringify(payload), leafHash]
+  );
+
+  return { leafHash };
+}
+
+/**
+ * Mark a `run_step` row as `error` with the given error message.
+ * Idempotent w.r.t. multiple error calls — last-write-wins on the message.
+ */
+export async function errorRunStep(
+  db: DbClient,
+  stepId: string,
+  error: Error
+): Promise<void> {
+  if (typeof stepId !== "string" || stepId.length === 0) {
+    throw new Error("[ooda] errorRunStep: stepId must be a non-empty string");
+  }
+  const message = error instanceof Error ? error.message : String(error);
+
+  await db.query(
+    `UPDATE run_step
+        SET status = 'error',
+            finished_at = now(),
+            error_message = $2
+      WHERE id = $1`,
+    [stepId, message]
+  );
+}

package/src/orchestration/ooda/skills.ts

@@ -0,0 +1,60 @@
+/**
+ * OODA Skill Registry — interface only (sprint-525:quick-1 foundation).
+ *
+ * Implementations land in sprint-525:quick-5. Skills are pure (or
+ * side-effect-bearing) callable units invoked from inside OODA phase
+ * functions. The `dryRunMocks` map lets tests + dry-run mode replace
+ * any skill execution with a deterministic mock keyed by skill name.
+ *
+ * The SkillRegistry is intentionally untyped at the value level to keep
+ * the SDK barrel compatible with arbitrary downstream skill libraries.
+ * A typed lookup helper can be layered on top in 0.7.x.
+ *
+ * @public
+ */
+
+import type { DbClient } from "../../tracking/agent-run-tracker.js";
+import type { LoggerPort } from "../../ports/logger.js";
+
+/**
+ * Context handed to each skill invocation.
+ *
+ * `isReplay` MUST be honored by skills that have side-effects: when true,
+ * the skill must short-circuit and emit no observable mutation (no LLM
+ * call, no HTTP, no DB INSERT). This guarantees replay safety for the
+ * OODA cycle log.
+ */
+export interface SkillContext {
+  readonly isReplay: boolean;
+  readonly dryRunMocks: Record<string, (input: unknown) => unknown>;
+  readonly db: DbClient;
+  readonly logger: LoggerPort;
+}
+
+/**
+ * Skill — single named callable unit invoked from an OODA phase.
+ *
+ * `inputSchema` is typed `unknown` here to keep the registry value-type
+ * homogeneous. Concrete skill libraries may use Zod (already a SDK dep)
+ * to refine the input — but validation is enforced inside `execute`.
+ */
+export interface Skill<I = unknown, O = unknown> {
+  readonly name: string;
+  /**
+   * Runtime validator/parser for the skill input. Concrete skill libs
+   * typically wire `z.ZodType<I>` here; the registry stays untyped.
+   */
+  readonly inputSchema: { parse: (raw: unknown) => I };
+  execute(input: I, ctx: SkillContext): Promise<O>;
+}
+
+/**
+ * SkillRegistry — name → skill map. Used by OODA phases to look up and
+ * invoke skills without coupling to concrete implementations.
+ */
+export type SkillRegistry = Record<string, Skill>;
+
+/**
+ * Empty registry — convenience for tests and minimal agents.
+ */
+export const EMPTY_SKILL_REGISTRY: SkillRegistry = Object.freeze({});