@vauban-org/agent-sdk 0.16.0

package/src/orchestration/ooda/inner-monologue.ts

@@ -0,0 +1,99 @@
+/**
+ * Inner Monologue — Private reasoning scratchpad for the decide phase.
+ *
+ * The monologue is a private reasoning trace that is:
+ *   - NEVER stored in Brain
+ *   - NEVER included in span attributes
+ *   - NEVER logged to OTel traces
+ *
+ * Content is wrapped in `SensitiveValue<T>` that throws on `toString()`,
+ * with an explicit `reveal()` method gated behind `executionMode === "debug"`.
+ *
+ * Inner monologue can contain financial reasoning, vulnerability analysis,
+ * or strategic deliberation — leaking it to traces or Brain is a security
+ * boundary violation. Enforced at the type level, not convention.
+ *
+ * @public
+ */
+
+// ─── SensitiveValue ─────────────────────────────────────────────────────────────
+
+/**
+ * Wraps a value that MUST NOT be logged, traced, or stored.
+ *
+ * `toString()` throws intentionally — prevents accidental leakage via
+ * template literals, JSON.stringify, or log formatters.
+ */
+export class SensitiveValue<T> {
+  readonly #value: T;
+  readonly #label: string;
+
+  constructor(value: T, label = "sensitive") {
+    this.#value = value;
+    this.#label = label;
+  }
+
+  /** Intentionally throws — prevents accidental leakage. */
+  toString(): string {
+    throw new Error(`SensitiveValue<${this.#label}>: use reveal() with explicit debug mode check`);
+  }
+
+  /** JSON.stringify trap — prevents serialization. */
+  toJSON(): never {
+    throw new Error(`SensitiveValue<${this.#label}>: cannot be serialized`);
+  }
+
+  /**
+   * Reveal the inner value.
+   *
+   * Gate this behind `executionMode === "debug"` — never expose in
+   * production traces, logs, or Brain archives.
+   */
+  reveal(): T {
+    return this.#value;
+  }
+
+  get label(): string {
+    return this.#label;
+  }
+}
+
+// ─── Inner Monologue ────────────────────────────────────────────────────────────
+
+export interface InnerMonologueInput {
+  /** The observation or orient output to reason about. */
+  observation: unknown;
+  /** Agent configuration / context. */
+  config?: unknown;
+  /** Previous monologues from this cycle (for chain-of-thought). */
+  previous?: string[];
+}
+
+export interface InnerMonologueOutput {
+  /** The reasoning trace — wrapped as SensitiveValue. */
+  reasoning: SensitiveValue<string>;
+  /** Key insights extracted (safe for Brain archival). */
+  insights: string[];
+  /** Decision confidence (0.0 - 1.0). */
+  confidence: number;
+}
+
+/**
+ * Generate an inner monologue — private reasoning that MUST NOT leak.
+ *
+ * The `reasoner` function receives the input and returns the monologue.
+ * The returned `reasoning` is wrapped in `SensitiveValue<string>`.
+ *
+ * Use `reveal()` only in debug execution mode — never in production.
+ */
+export async function innerMonologue(
+  input: InnerMonologueInput,
+  reasoner: (input: InnerMonologueInput) => Promise<{ reasoning: string; insights: string[]; confidence: number }>
+): Promise<InnerMonologueOutput> {
+  const result = await reasoner(input);
+  return {
+    reasoning: new SensitiveValue(result.reasoning, "inner-monologue"),
+    insights: result.insights,
+    confidence: result.confidence,
+  };
+}

package/src/orchestration/ooda/learn.ts

@@ -0,0 +1,146 @@
+/**
+ * Learning loop — shadow mode skill extraction from agent traces.
+ *
+ * Sprint-564: C2 — extractSkillFromTrace via LLM-as-optimizer.
+ *
+ * Trigger composite: toolCallCount >= 4 && roi > 0 && durationMs > 5000 && !wasReplay.
+ * NEVER inject learned skills into prod without explicit feature flag + signal stat sig.
+ * Golden fixtures snapshot tests detect drift in extraction quality.
+ *
+ * ANTI-AUDITABLE: learning loop is opt-in shadow mode only. Never active in production
+ * without explicit founder approval (CH7 Audit safe).
+ */
+
+import type { OODAContext, CycleEvent } from "./types.js";
+
+export interface SkillLedger {
+  add?(name: string, skill: { description: string; chainOfThought: string; source: string; confidence: number }): void;
+}
+
+export interface LearningTrigger {
+  toolCallCount: number;
+  roi: number;
+  durationMs: number;
+  wasReplay: boolean;
+}
+
+export interface ExtractedSkill {
+  name: string;
+  description: string;
+  chainOfThought: string;
+  confidence: number;
+  /** Whether this skill passed the golden fixtures gate. */
+  verified: boolean;
+}
+
+export interface LearnOptions {
+  /** Feature flag — must be explicitly enabled. Default: false. */
+  enabled: boolean;
+  /** Minimum confidence to accept a learned skill (0-1). Default: 0.85. */
+  minConfidence?: number;
+  /** Skill ledger to inject learned skills into. */
+  ledger?: SkillLedger;
+  /** LLM call for skill extraction. */
+  extractor?: (trace: string) => Promise<ExtractedSkill | null>;
+}
+
+/**
+ * Determine if learning should trigger for a completed cycle.
+ */
+export function shouldLearn(trigger: LearningTrigger): boolean {
+  return (
+    trigger.toolCallCount >= 4 &&
+    trigger.roi > 0 &&
+    trigger.durationMs > 5000 &&
+    !trigger.wasReplay
+  );
+}
+
+/**
+ * Extract a skill from a completed trace. Uses LLM-as-optimizer (Claude, not GEPA Python).
+ * Returns null if extraction fails or confidence below threshold.
+ * NEVER injects into SkillLedger without feature flag gate.
+ */
+export async function extractSkillFromTrace(
+  events: CycleEvent[],
+  _ctx: OODAContext,
+  opts: LearnOptions,
+): Promise<ExtractedSkill | null> {
+  if (!opts.enabled) return null;
+  if (!opts.extractor) return null;
+
+  const traceSummary = summarizeTrace(events);
+  if (!traceSummary) return null;
+
+  try {
+    const skill = await opts.extractor(traceSummary);
+    if (!skill) return null;
+
+    const minConf = opts.minConfidence ?? 0.85;
+    if (skill.confidence < minConf) return null;
+
+    // Gate: inject into SkillLedger ONLY if feature flag enabled
+    if (opts.ledger && skill.verified) {
+      opts.ledger.add?.(skill.name, {
+        description: skill.description,
+        chainOfThought: skill.chainOfThought,
+        source: "learning-loop",
+        confidence: skill.confidence,
+      });
+    }
+
+    return skill;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Summarize a trace into a compact text representation for the LLM extractor.
+ */
+function summarizeTrace(events: CycleEvent[]): string | null {
+  const phaseStarts = events.filter((e) => e.type === "phase_start");
+  const phaseCompletes = events.filter((e) => e.type === "phase_complete");
+  const cycleComplete = events.find((e) => e.type === "cycle_complete");
+
+  if (phaseStarts.length === 0) return null;
+
+  const lines: string[] = ["Trace summary:"];
+  for (let i = 0; i < phaseStarts.length; i++) {
+    const start = phaseStarts[i]!;
+    const complete = phaseCompletes.find(
+      (e) => "phase" in e && e.phase === ("phase" in start ? start.phase : ""),
+    );
+    lines.push(
+      `  ${i + 1}. ${"phase" in start ? start.phase : "unknown"}${complete ? ` (${"durationMs" in complete ? complete.durationMs : "?"}ms)` : ""}`,
+    );
+  }
+
+  if (cycleComplete && "status" in cycleComplete) {
+    lines.push(`Status: ${cycleComplete.status}`);
+    if ("durationMs" in cycleComplete) {
+      lines.push(`Total duration: ${cycleComplete.durationMs}ms`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ─── Golden fixtures ─────────────────────────────────────────────────────────
+
+export const GOLDEN_FIXTURES: ReadonlyArray<{
+  trace: string;
+  expectedSkillName: string;
+}> = [
+  {
+    trace: `Trace summary:
+  1. observe (50ms)
+  2. orient (200ms)
+  3. decide (100ms)
+  4. act (150ms)
+  5. feedback (80ms)
+Status: succeeded
+Total duration: 580ms`,
+    expectedSkillName: "expense_classification",
+  },
+];

package/src/orchestration/ooda/multimodal.ts

@@ -0,0 +1,174 @@
+/**
+ * MultiModalObservation — sprint-525:quick-6
+ *
+ * Typed container for observations that include non-text content (image, audio,
+ * document).  The ORIENT phase detects multimodal observations via `isMultiModal`
+ * and converts them to the Anthropic Messages API content-block format so Claude
+ * Opus 4 can process vision/audio inputs natively.
+ *
+ * Anthropic Messages API reference:
+ * https://docs.anthropic.com/api/messages
+ *
+ * @public
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A base64-encoded image source (jpg / png / gif / webp) or an external URL.
+ * Matches the Anthropic `image` content block `source` field.
+ */
+export type ImageMediaType = "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+
+/**
+ * Audio media types supported by Claude's audio input capability.
+ */
+export type AudioMediaType = "audio/ogg" | "audio/wav" | "audio/mp3" | "audio/mpeg" | "audio/webm";
+
+/**
+ * A multimodal observation may carry text alongside any combination of image,
+ * audio, and document inputs.  All non-text fields are optional; at least one
+ * must be present for `isMultiModal` to return `true`.
+ */
+export interface MultiModalObservation {
+  /** Plain-text portion of the observation (always included when available). */
+  text?: string;
+  /** Base64-encoded image (jpg / png / gif / webp). */
+  imageBase64?: string;
+  /** MIME type for `imageBase64`. Defaults to `image/jpeg` if absent. */
+  imageMediaType?: ImageMediaType;
+  /** Base64-encoded audio clip (ogg / wav / mp3 / webm). */
+  audioBase64?: string;
+  /** MIME type for `audioBase64`. Defaults to `audio/ogg` if absent. */
+  audioMediaType?: AudioMediaType;
+  /** Publicly accessible URL to a PDF document. */
+  documentUrl?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Anthropic content-block types (subset of Messages API)
+// These mirror the official SDK types exactly so no extra dependency is needed.
+// ---------------------------------------------------------------------------
+
+/** Plain-text content block. */
+export interface AnthropicTextBlock {
+  type: "text";
+  text: string;
+}
+
+/** Base64 image content block (Messages API). */
+export interface AnthropicImageBlock {
+  type: "image";
+  source: {
+    type: "base64";
+    media_type: ImageMediaType;
+    data: string;
+  };
+}
+
+/** URL-referenced document content block (Messages API). */
+export interface AnthropicDocumentBlock {
+  type: "document";
+  source: {
+    type: "url";
+    url: string;
+  };
+}
+
+/** Discriminated union of all supported Anthropic content blocks. */
+export type AnthropicContentBlock =
+  | AnthropicTextBlock
+  | AnthropicImageBlock
+  | AnthropicDocumentBlock;
+
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` when the observation contains at least one non-text channel
+ * (image, audio, or document).
+ *
+ * The ORIENT phase calls this before deciding whether to use a vision-capable
+ * model.  Text-only observations short-circuit to a lightweight completion.
+ */
+export function isMultiModal(obs: unknown): obs is MultiModalObservation {
+  return (
+    typeof obs === "object" &&
+    obs !== null &&
+    ("imageBase64" in obs || "audioBase64" in obs || "documentUrl" in obs)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Conversion
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps a `MultiModalObservation` to an ordered array of Anthropic Messages API
+ * content blocks suitable for inclusion in a `messages[].content` array.
+ *
+ * Ordering (Anthropic recommends text first, then media):
+ *   1. `text` → `TextBlock`
+ *   2. `imageBase64` → `ImageBlock` (base64 source)
+ *   3. `documentUrl` → `DocumentBlock` (URL source)
+ *
+ * Audio note: the Anthropic Messages API does not yet expose a first-class
+ * audio content block in the public spec (as of April 2026).  Audio is
+ * surfaced as a text block carrying a data-URI so callers can substitute their
+ * own handler when native audio support ships.
+ *
+ * @throws {TypeError} when `obs` carries neither text nor any media field.
+ */
+export function multiModalToAnthropicContent(
+  obs: MultiModalObservation,
+): AnthropicContentBlock[] {
+  const blocks: AnthropicContentBlock[] = [];
+
+  // 1. Text block (always first)
+  if (obs.text !== undefined && obs.text.length > 0) {
+    blocks.push({ type: "text", text: obs.text });
+  }
+
+  // 2. Image block
+  if (obs.imageBase64 !== undefined) {
+    blocks.push({
+      type: "image",
+      source: {
+        type: "base64",
+        media_type: obs.imageMediaType ?? "image/jpeg",
+        data: obs.imageBase64,
+      },
+    });
+  }
+
+  // 3. Audio — surfaced as text data-URI pending native API support
+  if (obs.audioBase64 !== undefined) {
+    const mimeType: AudioMediaType = obs.audioMediaType ?? "audio/ogg";
+    blocks.push({
+      type: "text",
+      text: `data:${mimeType};base64,${obs.audioBase64}`,
+    });
+  }
+
+  // 4. Document block (URL source)
+  if (obs.documentUrl !== undefined) {
+    blocks.push({
+      type: "document",
+      source: {
+        type: "url",
+        url: obs.documentUrl,
+      },
+    });
+  }
+
+  if (blocks.length === 0) {
+    throw new TypeError(
+      "MultiModalObservation must carry at least one non-empty field (text, imageBase64, audioBase64, or documentUrl)",
+    );
+  }
+
+  return blocks;
+}

package/src/orchestration/ooda/phase-routing.ts

@@ -0,0 +1,74 @@
+/**
+ * Phase-level model routing — per-phase model selection with fallback cascade.
+ *
+ * Sprint-563: B4 — PhaseModelConfig + ModelSpec.fallback + resolveForPhase.
+ *
+ * Each OODA phase can specify its own model, independent of other phases.
+ * When a provider fails (429/503), the fallback cascade tries the next model.
+ * resolveForPhase(phaseModels, phase) returns the resolved ModelSpec.
+ */
+
+import type { OODAPhaseKind } from "./types.js";
+
+export interface ModelSpec {
+  /** Provider identifier (e.g. "anthropic", "groq", "litellm"). */
+  provider: string;
+  /** Model name (e.g. "claude-sonnet-4-6", "llama-3.3-70b"). */
+  model: string;
+  /** Fallback cascade — tried in order on failure. */
+  fallback?: ModelSpec[];
+  /** Whether to track cost for this spec (default true). */
+  costTracking?: boolean;
+  /** Temperature override for this model. */
+  temperature?: number;
+  /** Top-p override for this model. */
+  topP?: number;
+}
+
+export interface PhaseModelConfig {
+  /** Per-phase model mapping. Undefined phases use the default model. */
+  phases: Partial<Record<OODAPhaseKind, ModelSpec>>;
+  /** Default model for phases without explicit config. */
+  defaultModel: ModelSpec;
+}
+
+/**
+ * Resolve the ModelSpec for a given phase. Falls back to defaultModel if
+ * the phase has no explicit config.
+ */
+export function resolveForPhase(
+  config: PhaseModelConfig,
+  phase: OODAPhaseKind,
+): ModelSpec {
+  return config.phases[phase] ?? config.defaultModel;
+}
+
+/**
+ * Get the full fallback chain for a phase — the primary model first,
+ * then its fallback cascade, then defaultModel + its cascade.
+ */
+export function getFallbackChain(
+  config: PhaseModelConfig,
+  phase: OODAPhaseKind,
+): ModelSpec[] {
+  const primary = config.phases[phase];
+  const chain: ModelSpec[] = [];
+
+  if (primary) {
+    chain.push(primary);
+    if (primary.fallback) chain.push(...primary.fallback);
+  }
+
+  // Always append default as last resort
+  chain.push(config.defaultModel);
+  if (config.defaultModel.fallback) chain.push(...config.defaultModel.fallback);
+
+  // Deduplicate by provider+model
+  const seen = new Set<string>();
+  return chain.filter((spec) => {
+    const key = `${spec.provider}:${spec.model}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/src/orchestration/ooda/plan-execute.ts

@@ -0,0 +1,87 @@
+/**
+ * Plan-and-Execute pattern — decompose a task in `decide`, execute step by step in `act`.
+ *
+ * decomposeTask() converts an orient output into a sequence of ordered steps.
+ * executeStep() runs one step with tool access, producing a step result.
+ *
+ * @public
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────────
+
+export interface PlanStep {
+  /** Step index (0-based). */
+  index: number;
+  /** Human-readable step description. */
+  description: string;
+  /** Tool expected to be used (optional hint). */
+  tool?: string;
+  /** Step-specific parameters. */
+  params?: Record<string, unknown>;
+}
+
+export interface Plan {
+  /** Overall goal. */
+  goal: string;
+  /** Ordered execution steps. */
+  steps: PlanStep[];
+  /** Estimated total cost in tokens. */
+  estimatedTokens?: number;
+}
+
+export interface StepResult {
+  stepIndex: number;
+  status: "completed" | "failed" | "skipped";
+  output?: unknown;
+  error?: string;
+  durationMs: number;
+}
+
+export interface PlanExecutionResult {
+  plan: Plan;
+  results: StepResult[];
+  completedSteps: number;
+  failedSteps: number;
+  totalDurationMs: number;
+}
+
+// ─── Decompose ──────────────────────────────────────────────────────────────────
+
+/**
+ * Convert a task description into a structured plan.
+ *
+ * The `decomposer` function is an LLM call that takes a task description
+ * and returns a Plan with ordered steps. Implementations should use
+ * structured output (Zod schema) for reliable parsing.
+ */
+export async function decomposeTask(
+  task: string,
+  decomposer: (task: string) => Promise<Plan>
+): Promise<Plan> {
+  return decomposer(task);
+}
+
+// ─── Execute ────────────────────────────────────────────────────────────────────
+
+/**
+ * Execute a single plan step.
+ *
+ * Returns a StepResult with status, output, and timing.
+ */
+export async function executeStep(
+  step: PlanStep,
+  executor: (step: PlanStep) => Promise<unknown>
+): Promise<StepResult> {
+  const start = Date.now();
+  try {
+    const output = await executor(step);
+    return { stepIndex: step.index, status: "completed", output, durationMs: Date.now() - start };
+  } catch (err) {
+    return {
+      stepIndex: step.index,
+      status: "failed",
+      error: err instanceof Error ? err.message : String(err),
+      durationMs: Date.now() - start,
+    };
+  }
+}