@vauban-org/agent-sdk 0.16.0

package/docs/contributing.md

@@ -0,0 +1,139 @@
+# Contributing to @vauban-org/agent-sdk
+
+## Development setup
+
+```bash
+git clone https://github.com/vauban-org/command-center.git
+cd command-center
+pnpm install
+cd packages/agent-sdk
+pnpm build
+pnpm test
+```
+
+## Quality gates
+
+All PRs must pass:
+
+```bash
+pnpm lint     # Biome — zero warnings permitted
+pnpm build    # TypeScript strict — no `any`, no type errors
+pnpm test     # Vitest — full suite, no skipped tests
+```
+
+No `// TODO` without a sprint task ref. No commented-out code. No debug artifacts.
+
+---
+
+## SDK Consumer Matrix CI
+
+**Every PR modifying `packages/agent-sdk/**` must pass the 6-consumer matrix CI before merge (`sdk-consumer-matrix.yml` workflow).**
+
+This workflow:
+1. Builds the SDK from the PR branch
+2. Installs the built package into 6 consumer test harnesses (CC, Forge, Brain, Citadel, Vauban Finance, external SaaS stub)
+3. Runs the contract test suite for each consumer against the new build
+4. Fails the PR if any consumer breaks
+
+This prevents silent regression: a refactor that compiles fine but breaks a downstream import.
+
+To run the matrix locally (requires Docker):
+
+```bash
+pnpm run matrix:ci
+```
+
+Each consumer is an isolated pnpm workspace. Contract tests live in `packages/agent-sdk/src/testing/contracts/`.
+
+---
+
+## Contract tests
+
+The SDK ships contract tests for all ports. Any new port **must** include a contract test before merge.
+
+```bash
+# Run contract tests only
+pnpm test -- tests/contracts/
+```
+
+Contract test files:
+- `src/testing/contracts/brain-port.contract.ts` — `BrainPort` conformance
+- `src/testing/contracts/event-bus.contract.ts` — `EventBusPort` conformance
+- `src/testing/contracts/economic-observer.contract.ts` — `EconomyRouter` + `OutcomeTracker`
+
+To test your custom adapter against the port contract:
+
+```typescript
+import { brainPortContract } from "@vauban-org/agent-sdk/testing";
+
+describe("MyCustomBrainAdapter", () => {
+  brainPortContract(() => new MyCustomBrainAdapter());
+});
+```
+
+---
+
+## Semver discipline
+
+The SDK follows strict semver. Breaking changes require a major bump.
+
+| Change | Bump |
+|--------|------|
+| New export (type or value) | minor |
+| New optional field on existing type | minor |
+| Bug fix, performance improvement | patch |
+| Removing an export | **major** |
+| Changing a method signature | **major** |
+| Removing an optional field | **major** |
+
+**No breaking change without a migration guide** in `docs/migration/`. Update the guide file name to reflect the new version range.
+
+---
+
+## Adding a new port
+
+1. Create `src/ports/<name>.ts` — define the interface, doc every method
+2. Create at least one in-memory adapter in `src/adapters/<category>/<name>-memory.ts`
+3. Export from `src/ports/index.ts` and `src/index.ts`
+4. Write a contract test in `src/testing/contracts/<name>.contract.ts`
+5. Document in `docs/ports/<name>.md` (interface quote + ≥1 adapter example)
+6. Update `mkdocs.yml` nav
+
+---
+
+## Adding a new tier template
+
+1. Create `src/templates/<tier>-agent.ts`
+2. Export from `src/templates/index.ts` and `src/index.ts`
+3. Document in `docs/templates.md` with a full working example
+4. Write tests in `tests/templates/<tier>-agent.test.ts`
+
+---
+
+## Publishing
+
+The SDK is published to GitHub Container Registry (GHCR):
+
+```bash
+pnpm build && pnpm publish --registry https://npm.pkg.github.com
+```
+
+Automated on tag `sdk-v*` via `.github/workflows/sdk-publish.yml`. Requires `write:packages` scope.
+
+---
+
+## OODA agent security requirements
+
+Agents consuming the SDK must comply with:
+
+- Input sanitization via `sanitizeExternalInput()` at system boundaries
+- No `any` types — use `unknown` with type guards
+- Cross-product events signed via `signEvent()` (no raw `crypto.createHmac`)
+- HITL for all actions with `estimatedCostCents > 0` in live mode
+- No secrets in code — env vars only, never committed
+
+---
+
+## Brain archival after substantive changes
+
+After resolving an ADR-worthy decision or discovering a reusable pattern while working on the SDK, archive to Brain MCP with `category: "development"` or `category: "decision"`. One subject per entry (50–200 words).

package/docs/economy.md

@@ -0,0 +1,159 @@
+# EconomyRouter
+
+**Module:** `@vauban-org/agent-sdk` · **Since:** sprint-584 Sprint D (economy module)
+
+## Purpose
+
+`EconomyRouter` provides data-driven tier selection, spend tracking, and circuit-breaking for agent LLM costs. It maps a complexity score (0–1) to a provider tier, records each cycle's cost, and opens a circuit breaker when hourly or monthly budgets are exceeded.
+
+Budget: `$0/mo` is achievable when using Groq free tier + LiteLLM on-prem as fallback.
+
+---
+
+## Tier catalog
+
+```typescript
+import type { ProviderTier } from "@vauban-org/agent-sdk";
+
+type ProviderTier = {
+  name: "free" | "cheap" | "mid" | "premium";
+  costPerInputToken: number;   // USD per token
+  costPerOutputToken: number;  // USD per token
+  qualityScore: number;        // 0-1
+};
+```
+
+Complexity → tier mapping:
+
+| Complexity | Tier |
+|-----------|------|
+| 0.00–0.25 | free |
+| 0.25–0.50 | cheap |
+| 0.50–0.75 | mid |
+| 0.75–1.00 | premium |
+
+---
+
+## Basic setup
+
+```typescript
+import { EconomyRouter } from "@vauban-org/agent-sdk";
+import type { EconomyRouterOpts, ProviderTier } from "@vauban-org/agent-sdk";
+
+const FREE_TIER: ProviderTier = {
+  name: "free",
+  costPerInputToken: 0,
+  costPerOutputToken: 0,
+  qualityScore: 0.7,
+};
+
+const MID_TIER: ProviderTier = {
+  name: "mid",
+  costPerInputToken: 0.5 / 1_000_000,
+  costPerOutputToken: 1.5 / 1_000_000,
+  qualityScore: 0.88,
+};
+
+const router = new EconomyRouter({
+  tiers: [FREE_TIER, MID_TIER],
+  hourlyBudgetUsd: 0.10,
+  monthlyBudgetUsd: 3.00,
+  defaultTier: "free",
+  onCircuitBreak: (reason) => console.error("[EconomyRouter] Circuit open:", reason),
+} satisfies EconomyRouterOpts);
+```
+
+---
+
+## Selecting a tier
+
+```typescript
+const tier = router.selectTier(0.6);   // → mid tier
+const tier2 = router.selectTier(0.1);  // → free tier
+
+console.log(tier.name);                // "mid"
+```
+
+---
+
+## Recording cycle cost
+
+```typescript
+router.recordCycle("treasury-agent", 0.0014, { input: 500, output: 200 });
+```
+
+If `eventBus` is configured, this publishes a `cc.cost.recorded` CloudEvent to the `cc.cost` stream automatically.
+
+---
+
+## Budget guard before a cycle
+
+```typescript
+const estimatedCost = 0.05;
+const check = router.canProceed(estimatedCost);
+
+if (!check.ok) {
+  console.warn("Skipping cycle:", check.reason);
+  // check.reason examples:
+  // "circuit-breaker-open"
+  // "hourly budget would be exceeded: 0.1200 > 0.1000 USD"
+  // "monthly budget would be exceeded: ..."
+} else {
+  // proceed with the cycle
+}
+```
+
+Circuit breaker auto-resets after a 5-minute cooldown.
+
+---
+
+## Multi-tenant isolation
+
+```typescript
+const tenantRouter = router.forTenant("acme-corp");
+// Independent spend history and circuit breaker for this tenant
+// Shares the same tier catalog and hourlyBudgetUsd configuration
+```
+
+---
+
+## EventBus integration
+
+```typescript
+import { EconomyRouter } from "@vauban-org/agent-sdk";
+
+const router = new EconomyRouter({
+  // ... tiers and budgets
+  eventBus: myEventBusImplementation,  // publishes cc.cost.recorded
+});
+```
+
+The event payload: `{ agentId, costUsd, tokens: { input, output }, tenantId? }`.
+
+---
+
+## Full Economy module exports
+
+```typescript
+import {
+  EconomyRouter,
+  DefaultTierPolicy,
+  lookupTier,
+  OutcomeTracker,
+  FleetCircuitBreaker,
+} from "@vauban-org/agent-sdk";
+
+import type {
+  EconomyRouterOpts,
+  ProviderTier,
+  CostEntry,
+  ModelTier,
+  TierPolicy,
+  OutcomeHook,
+  CycleCost,
+  EconomyMode,
+  EconomyRouterConfig,
+  RouteDecision,
+  CircuitBreakerConfig,
+} from "@vauban-org/agent-sdk";
+```

package/docs/getting-started.md

@@ -0,0 +1,179 @@
+# Getting started with `@vauban-org/agent-sdk`
+
+**Version:** 0.1.0
+**Status:** stable public contract (see [`CONTRACT.md`](../CONTRACT.md))
+
+The Vauban Agent SDK is a framework for building autonomous LLM agents that
+run on durable queues, respect budgets, handle HITL approvals, and emit
+OpenTelemetry GenAI semantic convention spans.
+
+It is consumed by Command Center (reference host), but distributable:
+any Node 20+ app can `pnpm add @vauban-org/agent-sdk` and register its own
+agents.
+
+---
+
+## Install
+
+```bash
+pnpm add @vauban-org/agent-sdk
+```
+
+In pnpm workspaces:
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - "apps/agents/*"
+```
+
+Each agent package includes the SDK as a dep:
+
+```json
+{
+  "name": "@your-org/my-agent",
+  "version": "0.1.0",
+  "dependencies": {
+    "@vauban-org/agent-sdk": "^0.1.0"
+  },
+  "keywords": ["@vauban/agent-plugin"]
+}
+```
+
+The `@vauban/agent-plugin` keyword makes the package auto-discoverable by
+`AgentRegistry.discover()` at host boot time.
+
+---
+
+## Minimal echo agent
+
+```typescript
+// apps/agents/my-echo/src/index.ts
+import type { AgentDescriptor } from "@vauban-org/agent-sdk";
+import { createEchoHandler } from "./agent.js";
+
+const descriptor: AgentDescriptor = {
+  id: "my-echo",
+  version: "0.1.0",
+  loop: "minimal",          // or "sdk" for Claude Agent SDK wrapper
+  budget_monthly_usd: 1,
+  description: "Echoes its input back, for smoke testing.",
+  handler: createEchoHandler(),
+  // Optional for cron agents:
+  // schedule: "0 */6 * * *",
+  // featureFlag: "MY_ECHO_ENABLED",
+};
+export default descriptor;
+```
+
+```typescript
+// apps/agents/my-echo/src/agent.ts
+import type { AgentContext, AgentResult, AgentHandler } from "@vauban-org/agent-sdk";
+
+export function createEchoHandler(): AgentHandler {
+  return async (ctx: AgentContext, input: string): Promise<AgentResult> => {
+    return {
+      output: `Echo: ${input}`,
+      stopReason: "complete",
+      inputTokens: 0,
+      outputTokens: 0,
+    };
+  };
+}
+```
+
+---
+
+## Agent primitives
+
+The SDK exports 11 public concepts (see `CONTRACT.md` §API v0.1.0):
+
+| Export | Role |
+|--------|------|
+| `AgentLoop` | Minimal loop — Anthropic SDK direct + tool registry |
+| `SdkAgentLoop` | Wraps Claude Agent SDK with vauban-auth scope mapping |
+| `AgentRegistry` | Plugin registration + `discover()` |
+| `BudgetState` + `CoherenceDetector` | Budget tracking, stall/loop detection, compaction |
+| `ProviderRouter` | Anthropic → Groq failover, quota-aware |
+| `ApprovalChannel` | HITL interface + `InMemoryApprovalStore` reference impl |
+| `sanitizeExternalInput` | R3-2 guardrail — length cap + injection marker regex |
+| `mapScopesToSdkPermissions` | vauban-auth `cc:*` scopes → SDK bash/fileIO/web/mcp |
+| `createAgentRunTracker` | Persist cost/tokens/status to `agent_run` Postgres table |
+| `recordOutcome` | OTel GenAI semantic convention span |
+| `createBullMQRunner` | Durable execution with DLQ + timeouts per archetype |
+
+---
+
+## Host setup (reference: Command Center)
+
+```typescript
+// src/durable/startup.ts
+import { agentRegistry } from "@vauban-org/agent-sdk";
+
+// At boot:
+const descriptors = await agentRegistry.discover(monorepoRoot);
+
+for (const desc of descriptors) {
+  if (desc.featureFlag && process.env[desc.featureFlag] !== "true") {
+    continue; // gated off
+  }
+  if (desc.schedule) {
+    await queue.add(`${desc.id}-cron`, {}, { repeat: { pattern: desc.schedule } });
+  }
+}
+```
+
+That's it — the host never hardcodes agent IDs. Adding a new agent = dropping
+a package with the right keyword into the workspace.
+
+---
+
+## External consumer example — Brain Curator
+
+`brain-protocol` consumes the SDK to build a Brain-native curator agent
+that scans recent entries and suggests `derives_from` edges:
+
+```typescript
+// brain-protocol/apps/curator/src/index.ts
+import type { AgentDescriptor } from "@vauban-org/agent-sdk";
+import { createCuratorHandler } from "./agent.js";
+
+const descriptor: AgentDescriptor = {
+  id: "brain-curator",
+  version: "0.1.0",
+  loop: "minimal",
+  schedule: "0 3 * * *",  // daily 3am UTC
+  featureFlag: "BRAIN_CURATOR_ENABLED",
+  budget_monthly_usd: 2,
+  description: "Scans recent Brain entries, suggests derives_from edges.",
+  handler: createCuratorHandler(),
+};
+export default descriptor;
+```
+
+No coupling to Command Center — only the SDK.
+
+---
+
+## Versioning & stability
+
+The SDK follows semver. See `CONTRACT.md` for the full public API signature.
+Breaking changes require a major bump. Additions and internal refactors are
+minor/patch.
+
+## Publishing
+
+Internal GHCR:
+
+```bash
+cd packages/agent-sdk
+pnpm build
+pnpm publish --registry https://npm.pkg.github.com
+```
+
+The `publishConfig` in `package.json` pins the registry; the user running
+`publish` needs `write:packages` scope on a GitHub PAT via `.npmrc`
+`//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}`.
+
+A GHA workflow (`.github/workflows/sdk-publish.yml`) automates this on
+tag `sdk-v*`.

package/docs/index.md

@@ -0,0 +1,57 @@
+# @vauban-org/agent-sdk — Quickstart
+
+**Version:** 0.17.x (Vague 1.B) · **Node:** >=20 · **Package manager:** pnpm
+
+## Install
+
+```bash
+pnpm add @vauban-org/agent-sdk
+```
+
+## First OODA agent in under 10 minutes
+
+```typescript
+import { createSimpleAgent, LiteLLMAdapter, ConsoleChannel } from "@vauban-org/agent-sdk";
+import type { AgentFactoryDeps } from "@vauban-org/agent-sdk";
+import { noopLogger } from "@vauban-org/agent-sdk";
+
+const deps: AgentFactoryDeps = {
+  executionMode: "dry-run",
+  logger: noopLogger,
+  db: null as unknown as AgentFactoryDeps["db"],
+  skills: {},
+  brain: undefined,
+  messaging: new ConsoleChannel(),
+};
+
+const agent = await createSimpleAgent(deps, {
+  agentId: "kpi-monitor",
+  intervalMs: 60_000,
+  observe: async () => ({ latencyMs: 42 }),
+  orient: async (obs) => ({ slow: obs.latencyMs > 200 }),
+  decide: async (orient) => ({
+    actions: orient.slow ? [{ type: "alert", payload: { msg: "latency high" } }] : [],
+    rationale: orient.slow ? "Latency exceeded threshold" : "All good",
+  }),
+  act: async (decision) => ({
+    executed: decision.actions.map((a) => ({ type: a.type, success: true, details: "" })),
+  }),
+  feedback: async (result) => ({ count: result.executed.length }),
+});
+
+await agent.start();
+```
+
+That is all. The OODA loop (Observe → Orient → Decide → Act → Feedback) runs every `intervalMs` milliseconds.
+
+## Next steps
+
+| Topic | Doc |
+|-------|-----|
+| Choose your LLM provider | [byom.md](byom.md) |
+| Port contracts (LLM, Messaging, HITL, EventBus…) | [ports/](ports/llm-provider.md) |
+| Tier templates (Simple, Reasoning, Complex) | [templates.md](templates.md) |
+| Cost routing & circuit-breaker | [economy.md](economy.md) |
+| Platform sub-package | [platforms.md](platforms.md) |
+| Migration from 0.15 | [migration/0.15-to-0.17.md](migration/0.15-to-0.17.md) |
+| Contributing | [contributing.md](contributing.md) |