@vauban-org/agent-sdk 0.16.0

package/docs/ports/event-bus.md

@@ -0,0 +1,131 @@
+# Port: EventBusPort
+
+**Module:** `@vauban-org/agent-sdk` · **Since:** extended in sprint-615 (ADR-ECO-017)
+
+## Purpose
+
+`EventBusPort` is the agent-to-agent pub/sub abstraction over CloudEvents 1.0 + Redis Streams (ADR-007). It provides:
+
+- At-least-once delivery with consumer-side dedup via CloudEvent `id` (UUIDv7)
+- MAXLEN ~10,000 per stream (backpressure via truncation)
+- Poison pill: 3 consecutive `XAUTOCLAIM` failures → auto-move to DLQ
+- Cross-product events via `DomainEvent` (ADR-ECO-017 HMAC-SHA256 authentication)
+
+## Interface definition
+
+```typescript
+import type {
+  EventBusPort,
+  CloudEvent,
+  DomainEvent,
+  EventSource,
+  Subscription,
+} from "@vauban-org/agent-sdk";
+
+type EventSource =
+  | "forge" | "vauban" | "vauban-finance" | "brain"
+  | "citadel" | "glacis" | "cc" | "tenant";
+
+interface CloudEvent {
+  id: string;               // UUIDv7 — doubles as idempotency key
+  specversion: "1.0";
+  source: string;
+  type: string;
+  time: string;             // ISO 8601
+  datacontenttype?: string;
+  data?: unknown;
+  traceparent?: string;
+  correlationid?: string;
+  partitionkey?: string;
+  dataschemaversion?: number;
+}
+
+interface DomainEvent<T = unknown> {
+  type: string;             // `<source>.<entity>.<action_past_tense>`
+  source: EventSource;      // enum — receivers reject unknown sources
+  correlationId: string;
+  causationId?: string;
+  idempotencyKey: string;   // UUIDv7 — dual role: anti-replay + Inbox dedup
+  timestamp: string;        // ISO 8601
+  schemaVersion: string;    // semver
+  payload: T;
+  signature: string;        // HMAC-SHA256, set by signEvent()
+}
+
+interface Subscription {
+  unsubscribe(): Promise<void>;
+}
+
+interface EventBusPort {
+  publish(event: CloudEvent, stream: string): Promise<void>;
+  publishWithIdempotency<T>(event: Omit<DomainEvent<T>, "signature">, key: string): Promise<void>;
+  subscribe(stream: string, consumerGroup: string, handler: (e: CloudEvent) => Promise<void>): Promise<() => void>;
+  subscribeDomain<T>(eventType: string, handler: (e: DomainEvent<T>) => Promise<void>, opts?: { groupId?: string; dlq?: string }): Subscription;
+  replayFrom(streamKey: string, fromId: string): AsyncIterable<DomainEvent>;
+  dlq(): { depth(): Promise<number>; replay(eventId: string): Promise<void> };
+  pendingCount(stream: string, consumerGroup: string): Promise<number>;
+}
+```
+
+## Cross-product events (ADR-ECO-017)
+
+All cross-product events **must** be signed and verified via SDK helpers. Direct `crypto.createHmac` outside the SDK is forbidden (CI lint rule `no-direct-hmac-outside-sdk`).
+
+```typescript
+import { signEvent, verifyEvent, InMemoryNonceStore } from "@vauban-org/agent-sdk";
+import type { DomainEvent } from "@vauban-org/agent-sdk";
+
+// Signing (producer side)
+const unsigned: Omit<DomainEvent, "signature"> = {
+  type: "cc.cost.recorded",
+  source: "cc",
+  correlationId: crypto.randomUUID(),
+  idempotencyKey: crypto.randomUUID(),
+  timestamp: new Date().toISOString(),
+  schemaVersion: "1.0.0",
+  payload: { agentId: "treasury", costUsd: 0.0014 },
+};
+
+const signed = signEvent(unsigned, process.env["EVENT_SIGNING_KEY_CC"]!);
+
+// Verification (consumer side)
+const nonceStore = new InMemoryNonceStore();
+await verifyEvent(signed, {
+  getKey: (source) => process.env[`EVENT_SIGNING_KEY_${source.toUpperCase()}`] ?? null,
+  nonceStore,
+  clockSkewMs: 300_000,
+});
+```
+
+Verification rejects with typed errors: `InvalidSignatureError`, `ClockSkewError`, `ReplayDetectedError`, `UnknownSourceError`.
+
+## Event naming convention
+
+Per ADR-ECO-017: `<source>.<entity>.<action_past_tense>` — source verb always past tense (events are facts).
+
+```
+cc.cost.recorded         ✅
+brain.knowledge.archived ✅
+forge.agent.started      ✅
+forge.start-agent        ❌ (imperative, wrong)
+```
+
+Sources must be one of the `EventSource` enum values. Unknown sources trigger `UnknownSourceError` on the consumer side.
+
+## Publishing with EconomyRouter integration
+
+```typescript
+import { EconomyRouter } from "@vauban-org/agent-sdk";
+
+// EconomyRouter publishes cc.cost.recorded automatically when eventBus is provided
+const router = new EconomyRouter({
+  tiers: [ /* ... */ ],
+  hourlyBudgetUsd: 1.0,
+  monthlyBudgetUsd: 10.0,
+  defaultTier: "cheap",
+  eventBus: myEventBusImplementation,
+});
+
+router.recordCycle("treasury-agent", 0.0014, { input: 500, output: 200 });
+// → publishes cc.cost.recorded to "cc.cost" stream
+```

package/docs/ports/hitl.md

@@ -0,0 +1,105 @@
+# Port: HITLPort
+
+**Module:** `@vauban-org/agent-sdk` · **Since:** 0.16.0 (plan v6 §1.7 + §3.4)
+
+## Purpose
+
+`HITLPort` is the stateful Human-In-The-Loop lifecycle contract. It manages the HITL state machine — from `pending` through `approved`/`rejected` to `executed`. State lives in the store (Postgres in production) **not** in the messaging channel. Channels are transports; state is the port's responsibility.
+
+## State machine
+
+```
+pending → approved → executed
+pending → rejected → executed
+pending → expired          (terminal — no further transitions)
+```
+
+Attempting an illegal transition (e.g. `expired → approved`) throws `InvalidStateTransitionError`.
+
+## Interface definition
+
+```typescript
+import type { HITLPort, HITLRequest, HITLState } from "@vauban-org/agent-sdk";
+import {
+  InvalidStateTransitionError,
+  HITLNotFoundError,
+  validateTransition,
+  runExpireJob,
+} from "@vauban-org/agent-sdk";
+
+type HITLState = "pending" | "approved" | "rejected" | "expired" | "executed";
+
+interface HITLRequest {
+  id: string;
+  agentSource: string;
+  question: string;
+  context: Record<string, unknown>;
+  options: string[];
+  deadline: string;          // ISO 8601
+  channel: "telegram" | "slack" | "discord";
+  tenantId?: string;
+}
+
+interface HITLPort {
+  request(req: HITLRequest): Promise<string>;          // returns approvalId
+  getState(id: string): Promise<HITLState>;
+  await(id: string, timeoutMs?: number): Promise<HITLState>;
+  resolve(id: string, decision: "approved" | "rejected", by: string): Promise<void>;
+  expire(id: string): Promise<void>;
+}
+```
+
+## Available adapters
+
+| Adapter | Import | Use case |
+|---------|--------|---------|
+| `MemoryHITLStateStore` | `@vauban-org/agent-sdk` | Tests, local dev |
+| `PostgresHITLStateStore` | `@vauban-org/agent-sdk` | Production |
+
+## Usage example
+
+```typescript
+import {
+  MemoryHITLStateStore,
+  runExpireJob,
+} from "@vauban-org/agent-sdk";
+import type { HITLPort, HITLRequest } from "@vauban-org/agent-sdk";
+
+const store: HITLPort = new MemoryHITLStateStore();
+
+// Start background expiry job (60s interval by default)
+const expireTimer = runExpireJob(store);
+
+// Agent requests approval
+const approvalId = await store.request({
+  id: crypto.randomUUID(),
+  agentSource: "treasury-agent",
+  question: "Approve swap of 10,000 USDC to ETH?",
+  context: { estimatedCostCents: 250, route: "uniswap-v3" },
+  options: ["approve", "reject"],
+  deadline: new Date(Date.now() + 5 * 60_000).toISOString(),
+  channel: "telegram",
+});
+
+// Human resolves via webhook/bot handler
+await store.resolve(approvalId, "approved", "operator@vauban.tech");
+
+// Agent polls or awaits resolution
+const finalState = await store.await(approvalId, 10_000);
+console.log(finalState); // "approved"
+
+// Cleanup
+clearInterval(expireTimer);
+```
+
+## HITL slack/telegram helpers
+
+The SDK also ships channel-specific HITL sending helpers:
+
+```typescript
+import { sendHITLApprovalRequestSlack } from "@vauban-org/agent-sdk";
+import { sendHITLApprovalRequestTelegram } from "@vauban-org/agent-sdk";
+import { createNodeSlackCallbackHandler } from "@vauban-org/agent-sdk";
+```
+
+See `@vauban-org/agent-sdk/hitl/slack` and `@vauban-org/agent-sdk/hitl/telegram` subpaths for the full helper API.

package/docs/ports/llm-provider.md

@@ -0,0 +1,125 @@
+# Port: LLMProviderPort
+
+**Module:** `@vauban-org/agent-sdk` · **Since:** 0.17.0 (plan v6 §3.2)
+
+## Purpose
+
+`LLMProviderPort` is the BYOM abstraction for language model calls. Every OODA agent that needs an LLM depends **only** on this port — never on a concrete provider SDK. Concrete adapters are injected at boot via `AgentFactoryDeps.deps.llm` (or `OODAAgentDeps.llm`).
+
+No model name is hardcoded in this interface or any file that re-exports it.
+
+## Interface definition
+
+```typescript
+import type {
+  LLMProviderPort,
+  ChatRequest,
+  ChatMessage,
+  ChatUsage,
+  ChatResponse,
+  StreamDelta,
+} from "@vauban-org/agent-sdk";
+
+interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+interface ChatRequest {
+  messages: ChatMessage[];
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  abortSignal?: AbortSignal;
+  metadata?: {
+    tenantId?: string;
+    agentId?: string;
+    correlationId?: string;
+  };
+}
+
+interface ChatUsage {
+  inputTokens: number;
+  outputTokens: number;
+  costUsd?: number;       // adapters that cannot compute cost omit this field
+}
+
+interface ChatResponse {
+  content: string;
+  usage: ChatUsage;
+  model: string;
+  finishReason: "stop" | "length" | "tool" | "error";
+}
+
+interface StreamDelta {
+  delta: string;
+  usage?: ChatUsage;      // only present in the final chunk
+}
+
+interface LLMProviderPort {
+  complete(req: ChatRequest): Promise<ChatResponse>;
+  stream?(req: ChatRequest): AsyncIterable<StreamDelta>;
+  estimateCost?(req: ChatRequest): { usd: number };
+}
+```
+
+**Contract:** `complete()` never rejects on model error — it returns `finishReason: "error"` instead. This prevents cascading failures in the OODA loop.
+
+## Available adapters
+
+| Adapter | Import | Backend |
+|---------|--------|---------|
+| `LiteLLMAdapter` | `@vauban-org/agent-sdk` | LiteLLM proxy (on-prem) |
+| `AnthropicDirectAdapter` | `@vauban-org/agent-sdk` | Anthropic API |
+| `CascadeAdapter` | `@vauban-org/agent-sdk` | Multi-provider fallback chain |
+
+See [byom.md](../byom.md) for setup examples.
+
+## Usage in a phase
+
+```typescript
+import type { OODAContext } from "@vauban-org/agent-sdk";
+
+const orientPhase = {
+  type: "retrieval" as const,
+  readOnly: true,
+  fn: async (obs: { data: string }, ctx: OODAContext) => {
+    const response = await ctx.deps.llm?.complete({
+      messages: [
+        { role: "system", content: "You are a financial analyst." },
+        { role: "user", content: `Analyze: ${obs.data}` },
+      ],
+      model: "qwen3-8b",
+      maxTokens: 512,
+    });
+    return { analysis: response?.content ?? "" };
+  },
+};
+```
+
+## Implementing a custom adapter
+
+```typescript
+import type { LLMProviderPort, ChatRequest, ChatResponse } from "@vauban-org/agent-sdk";
+
+class OpenRouterAdapter implements LLMProviderPort {
+  constructor(private readonly apiKey: string, private readonly defaultModel: string) {}
+
+  async complete(req: ChatRequest): Promise<ChatResponse> {
+    const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: req.model ?? this.defaultModel,
+        messages: req.messages,
+        max_tokens: req.maxTokens,
+      }),
+    });
+    // ... map response to ChatResponse
+    throw new Error("TODO: implement response mapping");
+  }
+}
+```

package/docs/ports/messaging.md

@@ -0,0 +1,94 @@
+# Port: MessagingChannelPort
+
+**Module:** `@vauban-org/agent-sdk` · **Since:** 0.16.0 (sprint-615:quick-2)
+
+## Purpose
+
+`MessagingChannelPort` is the generic abstraction for sending alerts and free-form messages via any channel (Telegram, Slack, Discord, console, or MCP). HITL approval flows are **excluded** from this port — they belong to `HITLPort` (plan v6 §3.5).
+
+Agents depend on this port for operational notifications; the concrete adapter is injected at boot via `AgentFactoryDeps.messaging`.
+
+## Interface definition
+
+```typescript
+import type { MessagingChannelPort, AlertLevel } from "@vauban-org/agent-sdk";
+import { InvalidTargetError } from "@vauban-org/agent-sdk";
+
+type AlertLevel = "info" | "warn" | "error" | "critical";
+
+interface MessagingChannelPort {
+  sendAlert(level: AlertLevel, title: string, body: string): Promise<void>;
+  sendMessage(target: string, text: string): Promise<void>;
+}
+
+class InvalidTargetError extends Error {
+  readonly target: string;
+  constructor(message: string, target: string);
+}
+```
+
+`sendMessage()` throws `InvalidTargetError` when `target` is empty or structurally invalid for the adapter.
+
+## Available adapters
+
+| Adapter | Import | Notes |
+|---------|--------|-------|
+| `ConsoleChannel` | `@vauban-org/agent-sdk` | Dev/test, prints to stdout |
+| `TelegramChannel` | `@vauban-org/agent-sdk` | Requires bot token + chat ID |
+| `SlackChannel` | `@vauban-org/agent-sdk` | Requires webhook URL or Bot token |
+| `DiscordChannel` | `@vauban-org/agent-sdk` | Requires webhook URL |
+| `MCPChannel` | `@vauban-org/agent-sdk` | For MCP-based environments |
+
+## Adapter examples
+
+### ConsoleChannel (dev/test)
+
+```typescript
+import { ConsoleChannel } from "@vauban-org/agent-sdk";
+import type { ConsoleChannelConfig } from "@vauban-org/agent-sdk";
+
+const messaging = new ConsoleChannel({ prefix: "[my-agent]" } satisfies ConsoleChannelConfig);
+await messaging.sendAlert("warn", "High latency", "p99 = 350ms");
+```
+
+### TelegramChannel
+
+```typescript
+import { TelegramChannel } from "@vauban-org/agent-sdk";
+import type { TelegramChannelConfig } from "@vauban-org/agent-sdk";
+
+const messaging = new TelegramChannel({
+  botToken: process.env["TELEGRAM_BOT_TOKEN"]!,
+  defaultChatId: process.env["TELEGRAM_CHAT_ID"]!,
+} satisfies TelegramChannelConfig);
+
+await messaging.sendAlert("critical", "Vault breach detected", "Immediate action required");
+await messaging.sendMessage("-100123456", "Custom message to a specific chat");
+```
+
+### SlackChannel
+
+```typescript
+import { SlackChannel } from "@vauban-org/agent-sdk";
+import type { SlackChannelConfig } from "@vauban-org/agent-sdk";
+
+const messaging = new SlackChannel({
+  webhookUrl: process.env["SLACK_WEBHOOK_URL"]!,
+} satisfies SlackChannelConfig);
+
+await messaging.sendAlert("error", "Pipeline failed", "Incident ID: inc-42");
+```
+
+## Usage in an agent
+
+```typescript
+import { createSimpleAgent, ConsoleChannel } from "@vauban-org/agent-sdk";
+import type { AgentFactoryDeps } from "@vauban-org/agent-sdk";
+
+const deps: Partial<AgentFactoryDeps> = {
+  messaging: new ConsoleChannel(),
+  // ... other deps
+};
+```
+
+When `deps.messaging` is set, `AgentFactory` automatically wires HITL notifications through it for agents with `hitlEscalationLevel` configured.

package/docs/templates.md

@@ -0,0 +1,165 @@
+# Tier Templates
+
+**Module:** `@vauban-org/agent-sdk` · **Since:** 0.20.0 (Vague 1.B.7, sprint-616)
+
+Three templates are promoted from Forge to the SDK. Each maps to a tier in the OODA agent taxonomy:
+
+| Tier | Template | Pattern |
+|------|----------|---------|
+| T1 — Rule-based | `createSimpleAgent` | observe → orient (rules) → decide (thresholds) → act → feedback |
+| T2 — Reasoning | `createReasoningAgent` | observe → orient (LLM + Reflexion) → decide (LLM) → act → feedback |
+| T3 — Complex | `createComplexAgent` | observe → orient (LLM + Debate) → decide (plan) → act → reflect → feedback |
+
+All three return an `OODAAgent` via `createAgentFromConfig` under the hood.
+
+---
+
+## `createSimpleAgent` — Tier 1
+
+For agents that don't need LLM reasoning: validators, KPI monitors, staking monitors, invoice processing.
+
+```typescript
+import {
+  createSimpleAgent,
+  ConsoleChannel,
+  noopLogger,
+} from "@vauban-org/agent-sdk";
+import type {
+  SimpleAgentOptions,
+  SimpleDecision,
+  SimpleExecutionResult,
+  AgentFactoryDeps,
+} from "@vauban-org/agent-sdk";
+
+type Observation = { memoryUsagePct: number };
+type Orientation = { critical: boolean };
+type Feedback = { alertsSent: number };
+
+const deps: Partial<AgentFactoryDeps> = {
+  executionMode: "live",
+  logger: noopLogger,
+  messaging: new ConsoleChannel(),
+  db: null as unknown as AgentFactoryDeps["db"],
+  skills: {},
+};
+
+const agent = await createSimpleAgent<Observation, Orientation, Feedback>(
+  deps as AgentFactoryDeps,
+  {
+    agentId: "memory-monitor",
+    intervalMs: 30_000,
+    observe: async () => ({ memoryUsagePct: process.memoryUsage().heapUsed / 1e9 }),
+    orient: async (obs) => ({ critical: obs.memoryUsagePct > 0.85 }),
+    decide: async (orient): Promise<SimpleDecision> => ({
+      actions: orient.critical ? [{ type: "gc", payload: {} }] : [],
+      rationale: orient.critical ? "Memory above 85%" : "Within bounds",
+    }),
+    act: async (decision): Promise<SimpleExecutionResult> => ({
+      executed: decision.actions.map((a) => ({ type: a.type, success: true, details: "" })),
+    }),
+    feedback: async (result): Promise<Feedback> => ({ alertsSent: result.executed.length }),
+  } satisfies SimpleAgentOptions<Observation, Orientation, Feedback>
+);
+
+await agent.start();
+```
+
+---
+
+## `createReasoningAgent` — Tier 2
+
+For agents that need LLM reasoning but not multi-agent debate: CFO IA, lead qualifier, churn predictor.
+
+```typescript
+import { createReasoningAgent } from "@vauban-org/agent-sdk";
+import type {
+  ReasoningAgentOptions,
+  AgentFactoryDeps,
+} from "@vauban-org/agent-sdk";
+
+type Obs = { revenueData: number[] };
+type Orient = { trend: string };
+type Decision = { recommendation: string };
+type Action = { sent: boolean };
+type Feedback = { ok: boolean };
+
+const agent = await createReasoningAgent<Obs, Orient, Decision, Action, Feedback>(
+  deps as AgentFactoryDeps,
+  {
+    agentId: "cfo-agent",
+    intervalMs: 3_600_000,
+    observe: async () => ({ revenueData: [100, 120, 115] }),
+    orient: async (obs, ctx) => {
+      const response = await ctx.deps.llm?.complete({
+        messages: [{ role: "user", content: `Analyze revenue: ${JSON.stringify(obs.revenueData)}` }],
+      });
+      return { trend: response?.content ?? "unknown" };
+    },
+    decide: async (orient, ctx) => {
+      const response = await ctx.deps.llm?.complete({
+        messages: [{ role: "user", content: `Recommend based on: ${orient.trend}` }],
+      });
+      return { recommendation: response?.content ?? "hold" };
+    },
+    act: async (decision) => {
+      console.log("Recommendation:", decision.recommendation);
+      return { sent: true };
+    },
+    feedback: async (result) => ({ ok: result.sent }),
+  } satisfies ReasoningAgentOptions<Obs, Orient, Decision, Action, Feedback>
+);
+```
+
+`ReasoningAgentConfig` also accepts `thinkingBudget` for Anthropic extended thinking support via `ctx.deps.llm`.
+
+---
+
+## `createComplexAgent` — Tier 3
+
+For orchestrators, treasury agents, DevOps agents, security auditors — multi-agent coordination with optional HITL gate.
+
+```typescript
+import { createComplexAgent } from "@vauban-org/agent-sdk";
+import type { ComplexAgentOptions, AgentFactoryDeps } from "@vauban-org/agent-sdk";
+
+type Obs = { pendingSwaps: Array<{ id: string; amountUsdc: number }> };
+type Orient = { riskScore: number; recommendation: string };
+type Decision = { steps: string[] };
+type Action = { executed: string[] };
+type Feedback = { success: boolean };
+
+const agent = await createComplexAgent<Obs, Orient, Decision, Action, Feedback>(
+  deps as AgentFactoryDeps,
+  {
+    agentId: "treasury-agent",
+    intervalMs: 900_000,
+    hitlEscalationLevel: "L2",       // HITL gate on act phase
+    observe: async () => ({ pendingSwaps: [] }),
+    orient: async (_obs, ctx) => {
+      const res = await ctx.deps.llm?.complete({
+        messages: [{ role: "user", content: "Assess treasury risk..." }],
+      });
+      return { riskScore: 0.3, recommendation: res?.content ?? "" };
+    },
+    decide: async (orient) => ({
+      steps: orient.riskScore > 0.7 ? ["pause", "alert"] : ["proceed"],
+    }),
+    act: async (decision) => ({ executed: decision.steps }),
+    feedback: async (result) => ({ success: result.executed.length > 0 }),
+  } satisfies ComplexAgentOptions<Obs, Orient, Decision, Action, Feedback>
+);
+```
+
+`ComplexAgentOptions` supports an optional `reflect` phase (self-critique with Reflexion memory) between `act` and `feedback`.
+
+---
+
+## Choosing a tier
+
+```
+No LLM needed?         → T1 SimpleAgent
+LLM + self-reasoning?  → T2 ReasoningAgent
+Multi-agent / HITL?    → T3 ComplexAgent
+```
+
+All tiers support: `sessionGuards`, `riskGuards`, `outcomeMapping`, and auto-registration via `registryDescriptor` when `deps.registry` is set.