@vauban-org/agent-sdk 0.16.0

package/docs/migration/0.15-to-0.17.md

@@ -0,0 +1,227 @@
+# Migration Guide: 0.15 → 0.17
+
+**Released in:** sprint-616 (Vague 1.B promotions)
+
+---
+
+## Summary of breaking changes
+
+| Change | 0.15 | 0.17 |
+|--------|------|------|
+| `OODAAgentDeps.llm` | Not available | Optional (required in 1.0) |
+| `createOODAAgent` `deps` param | Not available | Optional, strict validation |
+| Messaging adapters | Internal to CC | Exported from SDK |
+| `AgentRegistryPort` | Not available | Exported, 2 adapters |
+| `HITLPort` state machine | Internal | Exported, 2 adapters |
+| Tier templates | Forge-internal | `createSimpleAgent`, `createReasoningAgent`, `createComplexAgent` |
+| `AgentFactory` | Forge-internal | `createAgentFromConfig` in SDK |
+| `SkillRegistryBuilder` | Forge-internal | `buildSkills`, `buildSkillRegistry` in SDK |
+| `EconomyRouter` | Sprint D | Fully exported |
+| Event auth (ADR-ECO-017) | Separate | `signEvent`, `verifyEvent`, `InMemoryNonceStore` |
+
+---
+
+## 1. Inject `deps.llm` (strict mode — will throw in 1.0)
+
+SDK 0.17 introduces `OODAAgentDeps` — the BYOM dependency injection contract for OODA agents. `deps` is optional in 0.17 but **required in 1.0**. Strict mode (default) already enforces `deps.llm` at boot.
+
+```typescript
+// Before (0.15 — no deps injection)
+createOODAAgent({
+  agentId: "my-agent",
+  executionMode: "live",
+  db,
+  logger,
+  phases: { ... },
+});
+
+// After (0.17 — inject deps)
+import { LiteLLMAdapter } from "@vauban-org/agent-sdk";
+
+createOODAAgent({
+  agentId: "my-agent",
+  executionMode: "live",
+  db,
+  logger,
+  deps: {
+    llm: new LiteLLMAdapter({ baseUrl: process.env["LITELLM_URL"]! }),
+  },
+  phases: { ... },
+});
+```
+
+### `SDK_STRICT_DEPS` env control
+
+| Value | Behavior |
+|-------|----------|
+| absent (default) | Strict — throws `MissingDependencyError` if `deps.llm` missing |
+| `"true"` | Strict — same as absent |
+| `"false"` | Legacy — logs `console.warn`, does NOT throw |
+
+To temporarily suppress errors during migration (not recommended for production):
+
+```bash
+SDK_STRICT_DEPS=false node dist/my-agent.js
+```
+
+---
+
+## 2. `ctx.deps` in phase functions
+
+Phases now receive `ctx.deps` with all injected ports:
+
+```typescript
+{
+  type: "decision",
+  fn: async (input, ctx) => {
+    // Direct LLM access from context — no hardcoded model
+    const response = await ctx.deps.llm?.complete({
+      messages: [{ role: "user", content: "Decide: ..." }],
+    });
+    return response?.content ?? "fallback";
+  },
+}
+```
+
+---
+
+## 3. New: OODAAgentDeps interface
+
+```typescript
+import type {
+  OODAAgentDeps,
+  LLMProviderPort,
+  EventBusPort,
+  HITLPort,
+  MessagingChannelPort,
+  BrainPort,
+  AgentRegistryPort,
+} from "@vauban-org/agent-sdk";
+
+// OODAAgentDeps (internal — used by createOODAAgent)
+interface OODAAgentDeps {
+  llm?: LLMProviderPort;
+  eventBus?: EventBusPort;
+  hitl?: HITLPort;
+  messaging?: MessagingChannelPort;
+  memory?: BrainPort;
+  registry?: AgentRegistryPort;
+}
+```
+
+---
+
+## 4. New: Tier templates (Vague 1.B.7)
+
+Replace manual `createOODAAgent` boilerplate with typed templates:
+
+```typescript
+// Before (0.15 — raw createOODAAgent)
+import { createOODAAgent } from "@vauban-org/agent-sdk";
+const agent = await createOODAAgent({ agentId, phases: { ... } });
+
+// After (0.17 — tier template)
+import { createSimpleAgent } from "@vauban-org/agent-sdk";
+const agent = await createSimpleAgent(deps, {
+  agentId: "kpi-monitor",
+  intervalMs: 60_000,
+  observe, orient, decide, act, feedback,
+});
+```
+
+See [templates.md](../templates.md) for all three tiers.
+
+---
+
+## 5. New: AgentFactory (Vague 1.B.2)
+
+Use `createAgentFromConfig` for full OODA wiring with auto-registration support:
+
+```typescript
+import { createAgentFromConfig } from "@vauban-org/agent-sdk";
+```
+
+---
+
+## 6. New: SkillRegistryBuilder (Vague 1.B.3)
+
+Replace ad-hoc `buildXxxSkills()` functions with the unified builder:
+
+```typescript
+// Before (0.15 — custom per-agent function)
+function buildRevenueSkills(deps) { ... }
+
+// After (0.17 — SDK builder)
+import { buildSkills } from "@vauban-org/agent-sdk";
+
+const { registry } = buildSkills({
+  agentId: "forge-revenue",
+  deps: { brain: deps.brain, logger: deps.logger },
+  domain: "revenue",
+  extras: [{ name: "http-fetch", skill: httpFetch }],
+});
+```
+
+---
+
+## 7. New messaging channel adapters
+
+```typescript
+import {
+  ConsoleChannel,
+  TelegramChannel, TelegramRateLimitError,
+  SlackChannel,
+  DiscordChannel,
+  MCPChannel,
+} from "@vauban-org/agent-sdk";
+```
+
+---
+
+## 8. New: Event authentication (ADR-ECO-017)
+
+```typescript
+import {
+  signEvent,
+  verifyEvent,
+  InMemoryNonceStore,
+  canonicalEventString,
+  InvalidSignatureError,
+  ClockSkewError,
+  ReplayDetectedError,
+  UnknownSourceError,
+} from "@vauban-org/agent-sdk";
+```
+
+---
+
+## 9. New error classes
+
+```typescript
+import {
+  MissingDependencyError,  // deps.llm absent in strict mode
+  DepsValidationError,     // deps object structurally invalid
+} from "@vauban-org/agent-sdk";
+```
+
+---
+
+## Migration checklist
+
+- [ ] Add `deps: { llm: new LiteLLMAdapter(...) }` to every `createOODAAgent()` call
+- [ ] Update phases that hardcode model calls to use `ctx.deps.llm` instead
+- [ ] Replace `buildXxxSkills()` functions with `buildSkills({ agentId, deps, domain, extras })`
+- [ ] Replace raw `createOODAAgent` boilerplate with tier templates where applicable
+- [ ] Remove `SDK_STRICT_DEPS=false` env overrides once migration is complete
+- [ ] Run `pnpm build && pnpm test` — all boot-validation tests must pass
+- [ ] Sign cross-product events with `signEvent()` from the SDK auth module
+
+---
+
+## Timeline
+
+| Version | Status |
+|---------|--------|
+| 0.15 | Stable — no `deps` injection |
+| 0.17 | Current — `deps` optional, strict mode enforced by default |
+| 1.0 | Planned — `deps.llm` required, no `SDK_STRICT_DEPS=false` escape hatch |

package/docs/papers/bon-mav-notes.md

@@ -0,0 +1,36 @@
+# BoN-MAV — Multi-Agent Verification (Lifshitz et al. 2025)
+
+**Source**: Lifshitz et al., "Multi-Agent Verification: Scaling Test-Time Compute with Multiple Verifiers", arXiv:2502.20379 (v2, 2025).
+
+## Algorithm (paper § 2.3)
+
+BoN-MAV is a three-step Best-of-N procedure with multiple **Aspect Verifiers (AVs)**:
+
+1. Sample `n` candidate outputs `o^(1), ..., o^(n)` from a generator LLM.
+2. For each candidate, collect **binary approvals** `BinaryScore_v(o^(i)) ∈ {0,1}` from each of `m` aspect verifiers `v ∈ M`. An aspect verifier is an off-the-shelf LLM prompted to check ONE specific aspect (correctness, units, format, edge cases, ...).
+3. Select `î = argmax_i AggScore(o^(i))` and return `o^(î)`.
+
+The aggregation function (§ 2.2, Eq. 1) is an unweighted average of the binary verifier votes:
+
+> `AggScore(o^(i)) = (1/|M|) · Σ_{v ∈ M} BinaryScore_v(o^(i))`
+
+This is functionally **majority vote with equal weights** — the paper notes more sophisticated aggregation is left to future work. Notation: `BoN-MAV@n` denotes `n` candidates, `|M|` denotes the verifier-count axis. The framework scales independently along both axes (`n`, `m`).
+
+## Aggregation strategies (this implementation)
+
+The Vauban implementation generalizes the paper's binary-vote average to four aggregation modes — the paper baseline (`majority-vote` with `voteThreshold=0.5`) is preserved bit-exact, while `mean`/`median`/`min` are extensions for verifiers that emit continuous `[0,1]` scores (our `Verifier` interface, `src/compute/verifier.ts`):
+
+- `mean` — paper-equivalent on continuous scores (default; matches Eq. 1 generalized).
+- `median` — robust to a single outlier verifier.
+- `min` — conservative / worst-case (useful for safety-critical aspects).
+- `majority-vote` — paper-faithful: each score `≥ voteThreshold` counts as `1`, aggregated as `votes/M`.
+
+## Empirical findings (paper § 3.1, Fig. 5, Table 1)
+
+Tested on MATH, MMLU-Pro, GPQA-diamond, HumanEval with `n=16`. BoN-MAV outperforms self-consistency and reward-model verification, with **up to ~10% gain on large LLMs and ~20% on small ones** as `m` grows. Demonstrates **weak-to-strong generalization**: weaker verifier ensembles can supervise stronger generators.
+
+The bench harness (sibling task in Sprint A) targets the ≥20% accuracy delta on the small-model regime, which is consistent with Fig. 5's small-LLM curve.
+
+## Cost accounting note
+
+Paper assumes verifier calls are "free" relative to generator calls in the compute budget. Our `cost.calls = N` mirrors this: only generator calls counted. Verifier-call cost is exposed implicitly via `mavMatrix.length × mavMatrix[0].length` in metadata for downstream telemetry.

package/docs/patterns.md

@@ -0,0 +1,138 @@
+# `@vauban-org/agent-sdk` — Orchestration Patterns (v0.9.0)
+
+3 patterns composables, indépendants. S'intègrent dans le cycle OODA sans
+modifier `OODAAgentImpl`.
+
+---
+
+## Pattern A — SessionCircuitBreaker
+
+```ts
+import { createSessionCircuitBreaker } from '@vauban-org/agent-sdk/patterns/circuit-breaker';
+```
+
+Track les métriques de session OODA et coupe l'exécution si un seuil est
+dépassé. S'intègre comme `RiskGuard` (`OODAAgentConfig.riskGuards`).
+
+**IMPORTANT** : les méthodes `record*` doivent être appelées manuellement
+depuis les phase functions — le SDK ne les alimente pas automatiquement.
+
+**Distinct de** `resilience/circuitBreaker` (qui wraps des fonctions async).
+
+### Thresholds (defaults)
+
+| Seuil | Default |
+|---|---|
+| `maxTokens` | 50 000 |
+| `maxConsecutiveErrors` | 5 — trips ON the Nth error (>= comparison) |
+| `maxActionCount` | 200 |
+| `maxElapsedMs` | 3 600 000 ms (1h) |
+| `maxCostUsd` | $10.00 |
+| `resetAfterMs` | 60 000 ms |
+
+### State machine
+
+`closed` → `open` (seuil dépassé) → `half-open` (après `resetAfterMs`) → `closed` (probe success)
+
+### Usage
+
+```ts
+const cb = createSessionCircuitBreaker({
+  name: 'trading-session',
+  thresholds: { maxConsecutiveErrors: 3, maxCostUsd: 5.0 },
+  onTrip: (snap) => ctx.notifySlack('#alerts', `CB tripped: ${snap.tripReason}`),
+});
+// Dans les phase functions :
+cb.recordTokens(500, 0.002);
+cb.recordAction();
+// cb.recordError() si la phase échoue
+// cb.recordSuccess() si la phase réussit
+// OODAAgentConfig :
+// riskGuards: [cb]
+```
+
+---
+
+## Pattern B — QualityGate
+
+```ts
+import { createQualityGate } from '@vauban-org/agent-sdk/patterns/quality-gate';
+```
+
+Évalue la qualité d'un output OODA via des evaluators pondérés (score 0..1).
+Route vers `auto`, `async_review`, ou `hitl_block` selon les seuils.
+NaN/Infinity retournés par un evaluator sont traités comme 0 (pas de propagation).
+
+### Routing (thresholds configurables)
+
+| Score | Routing | Default |
+|---|---|---|
+| >= `autoProceedThreshold` | `auto` | 0.8 |
+| >= `asyncReviewThreshold` | `async_review` | 0.5 |
+| < `asyncReviewThreshold` | `hitl_block` | — |
+
+### Usage (dans la phase `act`)
+
+```ts
+const gate = createQualityGate({
+  name: 'trade-signal-quality',
+  evaluators: [
+    { name: 'confidence', weight: 2, evaluate: async (s) => s.confidence },
+    { name: 'completeness', weight: 1, evaluate: async (s) => s.fields / s.total },
+  ],
+  onHitlBlock: (score, subject) => ctx.notifySlack('#alerts', `Quality gate blocked: ${score.overall.toFixed(2)}`),
+});
+const score = await gate.evaluate(decisionPayload);
+if (score.routing === 'hitl_block') return; // abort act phase
+```
+
+---
+
+## Pattern C — EscalationPyramid
+
+```ts
+import { createEscalationPyramid } from '@vauban-org/agent-sdk/patterns/escalation';
+```
+
+Déclare les niveaux d'autonomie par type d'action. Escalade automatiquement
+si la confiance est insuffisante. Types inconnus → L3 (fail-safe).
+
+**NOTE** : `confidence` doit être fourni par la phase DECIDE de l'agent.
+
+### Niveaux
+
+| Level | Comportement |
+|---|---|
+| `L1_autonomous` | Exécution directe |
+| `L2_async_review` | Exécution + review asynchrone |
+| `L3_hitl_required` | Bloque jusqu'à validation humaine |
+
+### Escalade par confiance (thresholds configurables)
+
+| Déclaré | Condition | Effectif |
+|---|---|---|
+| L1 | confidence < 0.85 | L2 |
+| L2 | confidence < 0.60 | L3 |
+| L3 | tout | L3 |
+| tout | dry-run | L1 |
+| inconnu | tout | L3 |
+
+### Usage
+
+```ts
+const pyramid = createEscalationPyramid({
+  name: 'trading-pyramid',
+  declarations: [
+    { actionType: 'read_portfolio',    level: 'L1_autonomous' },
+    { actionType: 'place_limit_order', level: 'L2_async_review' },
+    { actionType: 'place_market_order',level: 'L3_hitl_required' },
+  ],
+  onHitlRequired: (actionType, confidence, decision, ctx) =>
+    ctx.notifySlack('#trading-hitl', `${actionType} requires approval`),
+});
+const decision = await pyramid.canProceed('place_limit_order', 0.75, ctx);
+if (!decision.proceed) return;
+// Runtime override (sans redéploiement) :
+pyramid.override('place_limit_order', 'L3_hitl_required');
+pyramid.clearOverride('place_limit_order');
+```

package/docs/platforms.md

@@ -0,0 +1,137 @@
+# Platform Clients
+
+**Module:** `@vauban-org/agent-sdk` (clients sub-package) · **Since:** 0.8.2 (sprint-524:quick-9)
+
+## Purpose
+
+The SDK ships REST client helpers so agents can communicate with Command Center, Brain, and peer agents without re-implementing HTTP boilerplate. These clients are thin wrappers — no state, no circuit breaking (use `EconomyRouter` or `circuitBreaker` from the resilience module for that).
+
+---
+
+## Available clients
+
+```typescript
+import {
+  createAgentsClient,
+  createPipelinesClient,
+} from "@vauban-org/agent-sdk";
+import type {
+  AgentsClient,
+  AgentsClientOptions,
+  AgentExecuteInput,
+  AgentExecuteResult,
+  PipelinesClient,
+  PipelinesClientOptions,
+  PipelineRunInput,
+  PipelineRunResult,
+} from "@vauban-org/agent-sdk";
+```
+
+All imports come from `"@vauban-org/agent-sdk"` (no subpath required).
+
+---
+
+## PipelinesClient
+
+Trigger and poll Command Center pipelines.
+
+```typescript
+import { createPipelinesClient } from "@vauban-org/agent-sdk";
+import type { PipelinesClientOptions } from "@vauban-org/agent-sdk";
+
+const pipelines = createPipelinesClient({
+  baseUrl: process.env["CC_API_URL"]!,
+  getToken: async () => process.env["CC_SERVICE_TOKEN"]!,
+} satisfies PipelinesClientOptions);
+
+// Trigger a pipeline
+const run = await pipelines.run({ name: "vault-guardian", payload: { vaultId: "usdc-main" } });
+console.log(run.runId, run.statusUrl);
+
+// Poll status
+const status = await pipelines.status(run.pipelineId);
+console.log(status.status);  // string — e.g. "completed" | "running" | "failed"
+
+// List available pipelines
+const { pipelines: list } = await pipelines.list();
+console.log(list.map((p) => p.name));
+```
+
+---
+
+## AgentsClient
+
+Execute peer agents registered in Command Center.
+
+```typescript
+import { createAgentsClient } from "@vauban-org/agent-sdk";
+import type { AgentsClientOptions, AgentExecuteInput } from "@vauban-org/agent-sdk";
+
+const agents = createAgentsClient({
+  baseUrl: process.env["CC_API_URL"]!,
+  getToken: async () => process.env["CC_SERVICE_TOKEN"]!,
+} satisfies AgentsClientOptions);
+
+const result = await agents.execute({
+  agentId: "ARCHITECT",
+  taskType: "architecture-review",
+  description: "Review the new event bus design",
+  archiveToBrain: true,
+} satisfies AgentExecuteInput);
+
+console.log(result.runId, result.runUrl);
+
+// List the agent registry
+const { agents: registry } = await agents.listRegistry();
+```
+
+---
+
+## MessagingAdapters
+
+The SDK ships a lightweight command-parsing bridge for Telegram/Slack slash commands that dispatches to `AgentsClient` or `PipelinesClient`:
+
+```typescript
+import type {
+  TelegramTriggerContext,
+  SlackTriggerContext,
+  MessagingTriggerResult,
+} from "@vauban-org/agent-sdk";
+```
+
+See `src/clients/messaging-adapters.ts` for the full slash-command parse API (`/run`, `/pipeline`, `/status`).
+
+---
+
+## Resilience (co-use)
+
+Platform clients have no built-in retry or circuit breaking. Wrap them with SDK resilience primitives:
+
+```typescript
+import { circuitBreaker, idempotent } from "@vauban-org/agent-sdk";
+
+const protectedPipelines = circuitBreaker(pipelines.trigger.bind(pipelines), {
+  threshold: 3,
+  timeout: 30_000,
+});
+
+// With idempotency key to prevent duplicate pipeline triggers
+const safeTrigger = idempotent(protectedPipelines, {
+  cache: myIdempotencyCache,
+  keyFn: (pipelineId, payload) => `trigger:${pipelineId}:${JSON.stringify(payload)}`,
+});
+```
+
+---
+
+## Starknet / DataOps clients
+
+For Starknet-specific data queries, the SDK ships optional data access helpers:
+
+```typescript
+// These require `starknet` peerDep (optional)
+import { createVoyagerClient } from "@vauban-org/agent-sdk";
+import { createStarkscanClient } from "@vauban-org/agent-sdk";
+```
+
+These are read-only data clients. All write operations to Starknet go through the `starknet-mcp` server, never directly from agents.

package/docs/ports/agent-registry.md

@@ -0,0 +1,100 @@
+# Port: AgentRegistryPort
+
+**Module:** `@vauban-org/agent-sdk` · **Since:** 0.17.0 (sprint-615:quick-5)
+
+## Purpose
+
+`AgentRegistryPort` enables runtime discovery of agents by capability. The orchestrator and GTM arbiter use this port to find agents without hard-coding agent IDs. SaaS clients register their own agents via `register()`.
+
+## Interface definition
+
+```typescript
+import type {
+  AgentRegistryPort,
+  AgentDescriptor as AgentRegistryDescriptor,
+} from "@vauban-org/agent-sdk";
+
+interface AgentDescriptor {
+  /** Format: `<product>:<slug>` — e.g. `"forge:01-revenue"` */
+  id: string;
+  product: string;
+  capabilities: string[];
+  inputSchema: object;
+  trigger: "event" | "cron" | "hitl" | "webhook";
+  llmRequirements?: {
+    minContextWindow?: number;
+    toolUse?: boolean;
+  };
+  tenantId?: string;
+}
+
+interface AgentRegistryPort {
+  register(descriptor: AgentDescriptor): Promise<void>;
+  list(filter?: Partial<AgentDescriptor>): Promise<AgentDescriptor[]>;
+  resolve(capability: string, opts?: { tenantId?: string }): Promise<AgentDescriptor[]>;
+  unregister(id: string): Promise<void>;
+}
+```
+
+**Contract:**
+- `register()` is **upsert** — safe to call on every process start
+- `unregister()` is **idempotent** — does not throw if the id is absent
+- `resolve()` returns agents for the capability, scoped to `tenantId` when provided (plus global agents)
+
+## Available adapters
+
+| Adapter | Import | Use case |
+|---------|--------|---------|
+| `MemoryAgentRegistry` | `@vauban-org/agent-sdk` | Tests, single-process deployments |
+| `PostgresAgentRegistry` | `@vauban-org/agent-sdk` | Production, multi-tenant via RLS |
+
+## Usage examples
+
+### Register at boot (auto-register pattern)
+
+```typescript
+import { MemoryAgentRegistry } from "@vauban-org/agent-sdk";
+import type { AgentRegistryDescriptor } from "@vauban-org/agent-sdk";
+
+const registry = new MemoryAgentRegistry();
+
+await registry.register({
+  id: "forge:revenue-analyzer",
+  product: "forge",
+  capabilities: ["market-analysis", "revenue-forecast"],
+  inputSchema: { type: "object", properties: { period: { type: "string" } } },
+  trigger: "cron",
+});
+```
+
+### Discover agents by capability
+
+```typescript
+const analysts = await registry.resolve("market-analysis");
+console.log(analysts.map((a) => a.id));
+// ["forge:revenue-analyzer"]
+
+// Tenant-scoped discovery
+const tenantAgents = await registry.resolve("market-analysis", { tenantId: "acme" });
+```
+
+### Via AgentFactory (auto-registration)
+
+```typescript
+import { createAgentFromConfig } from "@vauban-org/agent-sdk";
+
+const agent = await createAgentFromConfig(deps, {
+  agentId: "revenue-analyzer",
+  agentVersion: "1.0.0",
+  intervalMs: 300_000,
+  registryDescriptor: {
+    product: "forge",
+    capabilities: ["market-analysis"],
+    inputSchema: {},
+    trigger: "cron",
+  },
+  phases: { /* ... */ },
+});
+```
+
+When `deps.registry` and `config.registryDescriptor` are both set, `createAgentFromConfig` automatically calls `registry.register()` at boot (non-fatal — failure logs a warning but does not block start).