@vauban-org/agent-sdk 0.16.0

package/src/templates/reasoning-agent.ts

@@ -0,0 +1,251 @@
+/**
+ * ReasoningAgent Template — Tier 2 (LLM + Reflexion + Inner Monologue).
+ *
+ * Promoted from forge/src/agents/shared/templates/reasoning-agent.ts (Vague 1.B.7).
+ *
+ * For agents that need reasoning but not multi-agent debate or supervisor-worker:
+ *   - CFO IA, Chief of Staff IA, Prospector, Lead Qualifier, Outreach Writer,
+ *     Churn Predictor, Contract Generator.
+ *
+ * Pattern: observe → orient (LLM + Reflexion) → decide (LLM) →
+ *          act → reflect (self-critique, optional) → feedback.
+ *
+ * Extended thinking (Anthropic): pass `thinkingBudget` to enable budget_tokens
+ * in orient/decide phases via `deps.llm` with extended thinking support.
+ *
+ * Differences from Forge template:
+ * - AgentDependencies removed — uses AgentFactoryDeps (SDK-native)
+ * - buildSkills / createForgeAgent replaced by createAgentFromConfig (SDK)
+ * - `thinkingBudget` is an SDK-native concept (Anthropic extended thinking)
+ *   exposed via `ctx.deps.llm` metadata — no hardcoded model names here
+ * - Forge-specific couplings (slackWebhookUrl, litellmUrl) removed
+ *
+ * @public @since 0.20.0
+ */
+
+import { createAgentFromConfig } from "../factory/agent-factory.js";
+import type { AgentFactoryDeps } from "../factory/agent-factory.js";
+import type { OODAAgent, OODAContext } from "../orchestration/ooda/types.js";
+import type {
+  SessionGuard,
+  RiskGuard,
+  OutcomeRecord,
+} from "../orchestration/ooda/types.js";
+
+// ─── Options ──────────────────────────────────────────────────────────────────
+
+/**
+ * ReasoningAgentOptions — typed configuration for Tier 2 agents.
+ *
+ * Type parameters chain OODA phase I/O:
+ * - `TObs`      — observation output
+ * - `TOrient`   — orientation output (after LLM + Reflexion)
+ * - `TDecision` — decision output (LLM-powered)
+ * - `TAction`   — action output
+ * - `TFeedback` — feedback output
+ *
+ * @public
+ */
+export interface ReasoningAgentOptions<
+  TObs,
+  TOrient,
+  TDecision,
+  TAction,
+  TFeedback
+> {
+  /** Agent identifier (e.g. "cfo-agent"). */
+  agentId: string;
+  /** Agent semver string. */
+  agentVersion?: string;
+  /** Cycle interval in milliseconds. */
+  intervalMs: number;
+  /**
+   * Agent role description used in LLM prompts (system prompt context).
+   * Example: "You are the CFO agent responsible for financial oversight."
+   */
+  agentRole: string;
+  /**
+   * Extended thinking budget in tokens (Anthropic extended thinking).
+   * When set, phases should pass `thinkingBudget` to `deps.llm.complete()`
+   * via the `metadata` field or a custom wrapper.
+   *
+   * Recommended: 1024–8192 for reasoning tasks.
+   * Only effective when `deps.llm` is an AnthropicDirectAdapter with an
+   * extended-thinking-capable model (claude-3-7-sonnet or newer).
+   */
+  thinkingBudget?: number;
+  /** Observe phase: read data from Brain/APIs (readOnly). */
+  observe: (_: void, ctx: OODAContext) => Promise<TObs>;
+  /** Orient phase: LLM-powered analysis + Reflexion memory (readOnly). */
+  orient: (obs: TObs, ctx: OODAContext) => Promise<TOrient>;
+  /** Decide phase: LLM-powered decision making. */
+  decide: (orient: TOrient, ctx: OODAContext) => Promise<TDecision>;
+  /** Act phase: execute decisions via skills. */
+  act: (decision: TDecision, ctx: OODAContext) => Promise<TAction>;
+  /**
+   * Optional reflect phase: self-critique on the action (Reflexion pattern).
+   * Strongly recommended for reasoning agents to improve over time.
+   */
+  reflect?: (
+    input: TAction & { decision: TDecision },
+    ctx: OODAContext
+  ) => Promise<TFeedback>;
+  /** Feedback phase: log outcome, archive to Brain. */
+  feedback: (
+    input: TAction & { decision?: TDecision },
+    ctx: OODAContext
+  ) => Promise<TFeedback>;
+  /**
+   * HITL escalation level.
+   * - "L2": async review (default for reasoning agents).
+   * - "L3": synchronous HITL approval.
+   * When absent, no HITL gate is applied.
+   */
+  hitlEscalationLevel?: "L2" | "L3";
+  /** Optional session guards. Defaults to alwaysOn. */
+  sessionGuards?: SessionGuard[];
+  /** Optional risk guards. */
+  riskGuards?: RiskGuard[];
+  /** Optional outcome mapping for Economic Observer. */
+  outcomeMapping?: (feedback: TFeedback) => OutcomeRecord | null;
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+/**
+ * Create a Tier 2 (reasoning, LLM-powered, Reflexion-capable) OODA agent.
+ *
+ * Boilerplate reduction vs. raw `createAgentFromConfig`:
+ * - `agentRole` and `thinkingBudget` surfaced as first-class options
+ * - Optional `reflect` phase wired correctly between act and feedback
+ * - Phase `type` codes and `readOnly` flags set automatically
+ * - HITL wiring handled when `hitlEscalationLevel` is set
+ *
+ * The `agentRole` and `thinkingBudget` values are accessible in every phase
+ * via closure — pass them to `buildOrientPrompt` or `deps.llm.complete()` as
+ * needed in your phase implementations.
+ *
+ * @example
+ * ```ts
+ * const agent = await createReasoningAgent<Obs, Orient, Decision, Action, Feedback>(deps, {
+ *   agentId: "cfo-agent",
+ *   intervalMs: 3_600_000,
+ *   agentRole: "You are the CFO agent. Analyze financial data and provide recommendations.",
+ *   thinkingBudget: 4096,
+ *   observe: async () => ({ revenue: 10000, expenses: 8000 }),
+ *   orient: async (obs, ctx) => {
+ *     const { system, user } = buildOrientPrompt({
+ *       systemPrompt: ctx.config.agentRole ?? "",
+ *       userContext: JSON.stringify(obs),
+ *     });
+ *     const response = await ctx.deps.llm?.complete({ messages: [
+ *       { role: "system", content: system },
+ *       { role: "user", content: user },
+ *     ]});
+ *     return parseStructuredOutput(response?.content ?? "{}");
+ *   },
+ *   decide: async (orient) => ({ recommendation: orient.recommendation }),
+ *   act: async (decision) => ({ executed: true, decision }),
+ *   feedback: async (result) => ({ success: result.executed }),
+ * });
+ * await agent.start();
+ * ```
+ *
+ * @public
+ */
+export async function createReasoningAgent<
+  TObs,
+  TOrient,
+  TDecision,
+  TAction,
+  TFeedback
+>(
+  deps: AgentFactoryDeps,
+  opts: ReasoningAgentOptions<TObs, TOrient, TDecision, TAction, TFeedback>
+): Promise<OODAAgent> {
+  return createAgentFromConfig<
+    unknown,
+    TObs,
+    TOrient,
+    TDecision,
+    TAction,
+    TFeedback
+  >(deps, {
+    agentId: opts.agentId,
+    agentVersion: opts.agentVersion ?? "0.1.0",
+    intervalMs: opts.intervalMs,
+    hitlEscalationLevel: opts.hitlEscalationLevel,
+    sessionGuards: opts.sessionGuards,
+    riskGuards: opts.riskGuards,
+    outcomeMapping: opts.outcomeMapping,
+    // Expose agentRole + thinkingBudget via config so phases can access them
+    // via ctx.config (cast to ReasoningAgentConfig by the phase implementation)
+    defaults: {
+      agentRole: opts.agentRole,
+      thinkingBudget: opts.thinkingBudget,
+    },
+    phases: {
+      observe: {
+        type: "observation",
+        readOnly: true,
+        fn: opts.observe,
+      },
+      orient: {
+        type: "retrieval",
+        readOnly: true,
+        fn: opts.orient,
+      },
+      decide: {
+        type: "decision",
+        fn: opts.decide,
+      },
+      act: {
+        type: "execution",
+        hitlGate: opts.hitlEscalationLevel !== undefined,
+        fn: opts.act,
+      },
+      ...(opts.reflect !== undefined
+        ? {
+            reflect: {
+              type: "feedback" as const,
+              readOnly: true,
+              fn: opts.reflect,
+            },
+          }
+        : {}),
+      feedback: {
+        type: "feedback",
+        fn: opts.feedback as (
+          input: TAction,
+          ctx: OODAContext
+        ) => Promise<TFeedback>,
+      },
+    },
+  });
+}
+
+// ─── Config shape (accessible in phases via ctx.config) ──────────────────────
+
+/**
+ * ReasoningAgentConfig — the shape of `ctx.config` for reasoning agents.
+ * Cast `ctx.config` to this type in your phase implementations:
+ *
+ * ```ts
+ * orient: async (obs, ctx) => {
+ *   const cfg = ctx.config as ReasoningAgentConfig;
+ *   const { system, user } = buildOrientPrompt({
+ *     systemPrompt: cfg.agentRole,
+ *     userContext: JSON.stringify(obs),
+ *   });
+ *   // ...
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface ReasoningAgentConfig {
+  /** System prompt role description for LLM calls. */
+  readonly agentRole: string;
+  /** Extended thinking budget in tokens (optional). */
+  readonly thinkingBudget?: number;
+}

package/src/templates/simple-agent.ts

@@ -0,0 +1,173 @@
+/**
+ * SimpleAgent Template — Tier 1 (rule-based, no LLM debate).
+ *
+ * Promoted from forge/src/agents/shared/templates/simple-agent.ts (Vague 1.B.7).
+ *
+ * For agents that don't need LLM reasoning, Reflexion, or supervisor-worker:
+ *   - Validator Monitor, KPI Dashboard, deadLetterAgent, Support Tier 1,
+ *     Invoice & Facturation, Staking/Validator Monitor.
+ *
+ * Pattern: observe → orient (rules) → decide (threshold-based) → act → feedback.
+ *
+ * Differences from Forge template:
+ * - AgentDependencies removed — uses AgentFactoryDeps (SDK-native)
+ * - buildSkills / createForgeAgent replaced by createAgentFromConfig (SDK)
+ * - Forge-specific couplings (slackWebhookUrl, litellmUrl in skill wiring) removed
+ *
+ * @public @since 0.20.0
+ */
+
+import { createAgentFromConfig } from "../factory/agent-factory.js";
+import type { AgentFactoryDeps } from "../factory/agent-factory.js";
+import type { OODAAgent, OODAContext } from "../orchestration/ooda/types.js";
+import type {
+  SessionGuard,
+  RiskGuard,
+  OutcomeRecord,
+} from "../orchestration/ooda/types.js";
+
+// ─── Shared action type for rule-based agents ─────────────────────────────────
+
+export interface SimpleAction {
+  readonly type: string;
+  readonly payload: Record<string, unknown>;
+}
+
+export interface SimpleDecision {
+  readonly actions: SimpleAction[];
+  readonly rationale: string;
+}
+
+export interface SimpleExecutionResult {
+  readonly executed: Array<{
+    readonly type: string;
+    readonly success: boolean;
+    readonly details: string;
+  }>;
+}
+
+// ─── Options ──────────────────────────────────────────────────────────────────
+
+/**
+ * SimpleAgentOptions — typed configuration for Tier 1 agents.
+ *
+ * Type parameters:
+ * - `TContext`  — observation output type
+ * - `TOrient`   — orientation output type
+ * - `TFeedback` — feedback output type
+ *
+ * @public
+ */
+export interface SimpleAgentOptions<TContext, TOrient, TFeedback> {
+  /** Agent identifier (e.g. "validator-monitor"). */
+  agentId: string;
+  /** Agent semver string. */
+  agentVersion?: string;
+  /** Cycle interval in milliseconds. */
+  intervalMs: number;
+  /** Observe phase: reads data from Brain/APIs (readOnly). */
+  observe: (_: void, ctx: OODAContext) => Promise<TContext>;
+  /** Orient phase: rule-based analysis on observation (readOnly). */
+  orient: (obs: TContext, ctx: OODAContext) => Promise<TOrient>;
+  /**
+   * Decide phase: threshold-based decision on orient output.
+   * Returns a SimpleDecision with actions list and rationale.
+   */
+  decide: (orient: TOrient, ctx: OODAContext) => Promise<SimpleDecision>;
+  /**
+   * Act phase: executes actions declared by decide.
+   */
+  act: (
+    decision: SimpleDecision,
+    ctx: OODAContext
+  ) => Promise<SimpleExecutionResult>;
+  /**
+   * Feedback phase: log outcome, optionally archive to Brain.
+   */
+  feedback: (
+    result: SimpleExecutionResult,
+    ctx: OODAContext
+  ) => Promise<TFeedback>;
+  /** Optional session guards (e.g. market hours). Defaults to alwaysOn. */
+  sessionGuards?: SessionGuard[];
+  /** Optional risk guards (e.g. circuit breaker). */
+  riskGuards?: RiskGuard[];
+  /** Optional outcome mapping for Economic Observer. */
+  outcomeMapping?: (feedback: TFeedback) => OutcomeRecord | null;
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+/**
+ * Create a Tier 1 (simple, rule-based) OODA agent.
+ *
+ * Boilerplate reduction vs. raw `createAgentFromConfig`:
+ * - No `readOnly` flags to specify manually (observe + orient always readOnly)
+ * - No phase `type` codes to remember
+ * - Strongly-typed phase chain enforced by TypeScript
+ *
+ * @example
+ * ```ts
+ * const agent = await createSimpleAgent<Observation, Orientation, Feedback>(deps, {
+ *   agentId: "kpi-monitor",
+ *   intervalMs: 300_000,
+ *   observe: async () => ({ cpu: 0.42, memory: 0.8 }),
+ *   orient: async (obs) => ({ critical: obs.memory > 0.9 }),
+ *   decide: async (orient) => ({
+ *     actions: orient.critical ? [{ type: "alert", payload: {} }] : [],
+ *     rationale: orient.critical ? "Memory critical" : "All good",
+ *   }),
+ *   act: async (decision) => ({
+ *     executed: decision.actions.map((a) => ({ type: a.type, success: true, details: "" })),
+ *   }),
+ *   feedback: async (result) => ({ actionsExecuted: result.executed.length }),
+ * });
+ * await agent.start();
+ * ```
+ *
+ * @public
+ */
+export async function createSimpleAgent<TContext, TOrient, TFeedback>(
+  deps: AgentFactoryDeps,
+  opts: SimpleAgentOptions<TContext, TOrient, TFeedback>
+): Promise<OODAAgent> {
+  return createAgentFromConfig<
+    unknown,
+    TContext,
+    TOrient,
+    SimpleDecision,
+    SimpleExecutionResult,
+    TFeedback
+  >(deps, {
+    agentId: opts.agentId,
+    agentVersion: opts.agentVersion ?? "0.1.0",
+    intervalMs: opts.intervalMs,
+    sessionGuards: opts.sessionGuards,
+    riskGuards: opts.riskGuards,
+    outcomeMapping: opts.outcomeMapping,
+    phases: {
+      observe: {
+        type: "observation",
+        readOnly: true,
+        fn: opts.observe,
+      },
+      orient: {
+        type: "retrieval",
+        readOnly: true,
+        fn: opts.orient,
+      },
+      decide: {
+        type: "decision",
+        fn: opts.decide,
+      },
+      act: {
+        type: "execution",
+        fn: opts.act,
+      },
+      feedback: {
+        type: "feedback",
+        fn: opts.feedback,
+      },
+    },
+  });
+}

package/src/testing/brain-conformance.ts

@@ -0,0 +1,105 @@
+/**
+ * BrainPort conformance suite.
+ *
+ * Asserts a concrete BrainPort impl honours the contract:
+ *   - archiveKnowledge returns an entry-like object or null; never throws
+ *     on server validation failure (throws only for network/auth errors).
+ *   - queryKnowledge (when present) returns an array; empty array for no
+ *     matches, never null.
+ *   - Multiple archiveKnowledge calls with the same content are accepted;
+ *     the impl may de-dupe but must not reject on repeat.
+ */
+
+import type { BrainPort } from "../ports/brain.js";
+import type { ConformanceRunner } from "./runner.js";
+
+export interface BrainConformanceConfig {
+  describe: ConformanceRunner["describe"];
+  it: ConformanceRunner["it"];
+  expect: (actual: unknown) => {
+    toBeDefined(): void;
+    toBeNull(): void;
+    toBeTruthy(): void;
+    toBe(expected: unknown): void;
+    toEqual(expected: unknown): void;
+    toBeInstanceOf(cls: unknown): void;
+    toHaveProperty(key: string): void;
+    toBeGreaterThanOrEqual(n: number): void;
+    not: {
+      toBe(expected: unknown): void;
+      toBeNull(): void;
+      toThrow(): void;
+    };
+    // biome-ignore lint/suspicious/noExplicitAny: matcher shape
+    [key: string]: any;
+  };
+  /**
+   * Async factory returning a fresh BrainPort for each test case.
+   * Use this to isolate state between tests.
+   */
+  factory: () => Promise<BrainPort> | BrainPort;
+  /**
+   * Optional tag applied to all archived entries (so the host can clean
+   * up after the suite runs). Defaults to "conformance-test".
+   */
+  testTag?: string;
+}
+
+export function brainPortConformance(config: BrainConformanceConfig): void {
+  const { describe, it, expect, factory } = config;
+  const tag = config.testTag ?? "conformance-test";
+
+  describe("BrainPort conformance", () => {
+    it("archiveKnowledge returns an entry with an id on success", async () => {
+      const brain = await factory();
+      const result = await brain.archiveKnowledge({
+        content: "conformance — archive smoke",
+        category: "pattern",
+        tags: [tag],
+      });
+      if (result !== null) {
+        expect(result).toHaveProperty("id");
+        expect(typeof result.id).toBe("string");
+      }
+    });
+
+    it("archiveKnowledge returns null (not throws) on validation failure", async () => {
+      const brain = await factory();
+      // Empty content should either succeed or return null — never throw.
+      let threw = false;
+      try {
+        const result = await brain.archiveKnowledge({ content: "" });
+        // Acceptable outcomes: entry with id, or null.
+        if (result !== null) {
+          expect(result).toHaveProperty("id");
+        }
+      } catch {
+        threw = true;
+      }
+      expect(threw).toBe(false);
+    });
+
+    it("archiveKnowledge accepts repeated identical entries", async () => {
+      const brain = await factory();
+      const entry = {
+        content: `conformance-repeat-${Date.now()}`,
+        category: "pattern",
+        tags: [tag],
+      };
+      const r1 = await brain.archiveKnowledge(entry);
+      const r2 = await brain.archiveKnowledge(entry);
+      // Both calls must resolve without rejecting.
+      expect(r1 === null || typeof r1.id === "string").toBe(true);
+      expect(r2 === null || typeof r2.id === "string").toBe(true);
+    });
+
+    it("queryKnowledge (when present) returns an array", async () => {
+      const brain = await factory();
+      if (!brain.queryKnowledge) return; // optional port method
+      const results = await brain.queryKnowledge("conformance test query", {
+        limit: 5,
+      });
+      expect(Array.isArray(results)).toBe(true);
+    });
+  });
+}