@vauban-org/agent-sdk

Vauban agent primitives extracted from Command Center. Provides the core loop, budget tracking, provider routing, HITL approval, permissions, durable execution, and telemetry building blocks.

Quickstart

import {
  AgentLoop,
  createBudgetState,
  createProviderRouter,
} from "@vauban-org/agent-sdk";

const router = createProviderRouter({
  groqApiKey: process.env.GROQ_API_KEY,
});

const loop = new AgentLoop({
  agentId: "my-agent",
  agentVersion: "0.1.0",
  systemPrompt: "You are a helpful assistant.",
  provider: router,
  tools: myToolRegistry,
  budget: createBudgetState({ maxSteps: 10 }),
});

const result = await loop.run("Summarise the latest market news.");
console.log(result.finalMessage);

Public API

See CONTRACT.md for all signatures and the breaking-change policy.

Export	Description
AgentLoop	Multi-provider loop (Anthropic + Groq cascade)
SdkAgentLoop	Anthropic-direct loop with permission enforcement
AgentRegistry	Plugin registration + descriptor validation
createBudgetState	Per-run budget counters
createCoherenceDetector	Loop/stall detection
createProviderRouter	Anthropic → Groq fallback router
InMemoryApprovalStore	In-process HITL approval store
sanitizeExternalInput	Prompt injection defence
keepSafeOnly	Filter + return clean items
recordOutcome	OTel span finalisation helper
createAgentRunTracker	DB-backed token/cost accounting
createBullMQRunner	BullMQ queue/worker/DLQ factory
AGENT_IDS	Stable UUIDs per agent archetype
mapScopesToSdkPermissions	JWT scope → SdkPermissions

Architecture

@vauban-org/agent-sdk
├── loop/          AgentLoop (minimal-loop) + SdkAgentLoop (sdk-loop)
├── budget/        AgentBudgetState, CoherenceDetector, compactToolLog
├── router/        ProviderRouter (Anthropic + Groq)
├── hitl/          ApprovalChannel interface + InMemoryApprovalStore
├── permissions/   SdkPermissions, mapScopesToSdkPermissions
├── safety/        sanitizeExternalInput, keepSafeOnly
├── tracking/      OTel gen-ai spans + AgentRunTracker
├── durable/       BullMQRunner (queues, workers, DLQ, flow)
└── registry/      AgentRegistry + AGENT_IDS

Trading-NQ Paper Validation (Required Before Live)

Before flipping TRADING_MODE=live:

1. Run 3 weeks of TRADING_MODE=paper cycles in production env
2. Verify net_roi_pct stable (median > 0 across 21 days)
3. Verify slippage_bps tolerable (P95 < 5 bps)
4. Founder + RSO sign-off (per governance/founder-authority.md)

Workspace dep (Command Center)

"@vauban-org/agent-sdk": "workspace:*"