@vauban-org/agent-sdk 0.16.0

package/package.json

@@ -0,0 +1,160 @@
+{
+  "name": "@vauban-org/agent-sdk",
+  "version": "0.16.0",
+  "description": "Vauban agent primitives: loop, budget, routing, HITL, permissions, tracking, durable execution",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./proof": {
+      "types": "./dist/proof/index.d.ts",
+      "import": "./dist/proof/index.js",
+      "default": "./dist/proof/index.js"
+    },
+    "./outcomes": {
+      "types": "./dist/outcomes/index.d.ts",
+      "import": "./dist/outcomes/index.js",
+      "default": "./dist/outcomes/index.js"
+    },
+    "./testing/chaos": {
+      "types": "./dist/testing/chaos.d.ts",
+      "import": "./dist/testing/chaos.js",
+      "default": "./dist/testing/chaos.js"
+    },
+    "./patterns/circuit-breaker": {
+      "types": "./dist/patterns/circuit-breaker/index.d.ts",
+      "import": "./dist/patterns/circuit-breaker/index.js",
+      "default": "./dist/patterns/circuit-breaker/index.js"
+    },
+    "./patterns/quality-gate": {
+      "types": "./dist/patterns/quality-gate/index.d.ts",
+      "import": "./dist/patterns/quality-gate/index.js",
+      "default": "./dist/patterns/quality-gate/index.js"
+    },
+    "./patterns/escalation": {
+      "types": "./dist/patterns/escalation/index.d.ts",
+      "import": "./dist/patterns/escalation/index.js",
+      "default": "./dist/patterns/escalation/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js",
+      "default": "./dist/mcp/index.js"
+    },
+    "./metrics": {
+      "types": "./dist/metrics/create-agent-metrics.d.ts",
+      "import": "./dist/metrics/create-agent-metrics.js",
+      "default": "./dist/metrics/create-agent-metrics.js"
+    },
+    "./hitl/slack": {
+      "types": "./dist/hitl/slack.d.ts",
+      "import": "./dist/hitl/slack.js",
+      "default": "./dist/hitl/slack.js"
+    },
+    "./hitl/telegram": {
+      "types": "./dist/hitl/telegram.d.ts",
+      "import": "./dist/hitl/telegram.js",
+      "default": "./dist/hitl/telegram.js"
+    },
+    "./hitl/api": {
+      "types": "./dist/hitl/api.d.ts",
+      "import": "./dist/hitl/api.js",
+      "default": "./dist/hitl/api.js"
+    },
+    "./hitl/callback-handlers": {
+      "types": "./dist/hitl/callback-handlers.d.ts",
+      "import": "./dist/hitl/callback-handlers.js",
+      "default": "./dist/hitl/callback-handlers.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "CONTRACT.md",
+    "README.md",
+    "docs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vauban-org/command-center.git",
+    "directory": "packages/agent-sdk"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "access": "restricted"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+    "@opentelemetry/resources": "^2.6.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "@vauban-org/proof-core": "^0.1.0",
+    "bullmq": "^5.75.2",
+    "ioredis": "^5.10.1",
+    "json-canonicalize": "^2.0.0",
+    "pino": "^9.5.0",
+    "yaml": "^2.6.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@microsoft/api-documenter": "^7.30.5",
+    "@microsoft/api-extractor": "^7.58.7",
+    "@size-limit/preset-small-lib": "^11.0.0",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/typescript-checker": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "@types/node": "^22.0.0",
+    "fast-check": "^4.7.0",
+    "size-limit": "^11.0.0",
+    "tinybench": "^6.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "prom-client": "^15.0.0",
+    "starknet": "^6.24.1"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": false
+    },
+    "prom-client": {
+      "optional": true
+    },
+    "starknet": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "biome check src/ tests/",
+    "size": "size-limit",
+    "size:legacy": "node scripts/measure-size.mjs",
+    "bench": "node --import tsx/esm bench/run.ts",
+    "bench:sdk": "node --import tsx/esm benchmarks/sdk.bench.ts",
+    "bench:baseline": "node --import tsx/esm benchmarks/sdk.bench.ts --write-baseline",
+    "mutation": "stryker run",
+    "stryker": "stryker run --concurrency 2",
+    "api:extract": "api-extractor run --local --verbose",
+    "api:check": "api-extractor run",
+    "depcruise": "depcruise src"
+  }
+}

package/src/adapters/hitl/memory-state-store.ts

@@ -0,0 +1,96 @@
+/**
+ * MemoryHITLStateStore — in-process HITL state store.
+ *
+ * Suitable for tests, local dev, and single-instance deployments.
+ * Multi-instance prod deployments must use PostgresHITLStateStore.
+ *
+ * @public
+ */
+
+import {
+  HITLNotFoundError,
+  type HITLPort,
+  type HITLRequest,
+  type HITLState,
+  validateTransition,
+} from "../../ports/hitl.js";
+
+interface MemoryEntry {
+  request: HITLRequest;
+  state: HITLState;
+  decision?: string;
+  decidedBy?: string;
+  decidedAt?: Date;
+  executedAt?: Date;
+}
+
+const POLL_INTERVAL_MS = 100;
+
+export class MemoryHITLStateStore implements HITLPort {
+  readonly #store = new Map<string, MemoryEntry>();
+
+  async request(req: HITLRequest): Promise<string> {
+    this.#store.set(req.id, { request: req, state: "pending" });
+    return req.id;
+  }
+
+  async getState(id: string): Promise<HITLState> {
+    const entry = this.#store.get(id);
+    if (!entry) throw new HITLNotFoundError(id);
+    return entry.state;
+  }
+
+  async await(id: string, timeoutMs?: number): Promise<HITLState> {
+    const deadline = timeoutMs != null ? Date.now() + timeoutMs : Infinity;
+
+    for (;;) {
+      const state = await this.getState(id);
+      if (state !== "pending") return state;
+      if (Date.now() >= deadline) return state;
+
+      // Wait one poll tick (or remaining budget, whichever is shorter)
+      const remaining = deadline - Date.now();
+      const wait = Math.min(POLL_INTERVAL_MS, remaining > 0 ? remaining : 0);
+      await new Promise<void>((resolve) => setTimeout(resolve, wait));
+
+      // Re-check deadline after sleeping
+      if (Date.now() >= deadline) return await this.getState(id);
+    }
+  }
+
+  async resolve(
+    id: string,
+    decision: "approved" | "rejected",
+    by: string
+  ): Promise<void> {
+    const entry = this.#store.get(id);
+    if (!entry) throw new HITLNotFoundError(id);
+    validateTransition(entry.state, decision);
+    entry.state = decision;
+    entry.decision = decision;
+    entry.decidedBy = by;
+    entry.decidedAt = new Date();
+  }
+
+  async expire(id: string): Promise<void> {
+    const entry = this.#store.get(id);
+    if (!entry) throw new HITLNotFoundError(id);
+    validateTransition(entry.state, "expired");
+    entry.state = "expired";
+  }
+
+  /**
+   * Called by runExpireJob to expire all overdue pending requests.
+   * Not part of HITLPort — called via the _expireOverdue duck-type hook.
+   */
+  async _expireOverdue(): Promise<void> {
+    const now = new Date();
+    for (const [id, entry] of this.#store.entries()) {
+      if (entry.state === "pending" && new Date(entry.request.deadline) < now) {
+        entry.state = "expired";
+        // Best-effort: if validateTransition would throw, we already checked state=pending above
+        void id; // keep the binding in scope
+      }
+    }
+  }
+}

package/src/adapters/hitl/postgres-state-store.ts

@@ -0,0 +1,147 @@
+/**
+ * PostgresHITLStateStore — Postgres-backed HITL state store.
+ *
+ * Uses SELECT FOR UPDATE for atomic state transitions (no lost-update races).
+ * Requires the hitl_requests table from migration 039_hitl_requests.sql.
+ *
+ * Constructor: { db: DbPort } — compatible with pg.Pool / pg.Client.
+ *
+ * @public
+ */
+
+import type { DbPort } from "../../ports/db.js";
+import {
+  HITLNotFoundError,
+  type HITLPort,
+  type HITLRequest,
+  type HITLState,
+  validateTransition,
+} from "../../ports/hitl.js";
+
+interface HITLRow {
+  id: string;
+  state: HITLState;
+}
+
+export class PostgresHITLStateStore implements HITLPort {
+  readonly #db: DbPort;
+
+  constructor({ db }: { db: DbPort }) {
+    this.#db = db;
+  }
+
+  async request(req: HITLRequest): Promise<string> {
+    await this.#db.query(
+      `INSERT INTO hitl_requests
+         (id, agent_source, question, context, options, channel, state, deadline, tenant_id)
+       VALUES ($1, $2, $3, $4, $5, $6, 'pending', $7, $8)`,
+      [
+        req.id,
+        req.agentSource,
+        req.question,
+        JSON.stringify(req.context),
+        req.options,
+        req.channel,
+        req.deadline,
+        req.tenantId ?? null,
+      ]
+    );
+    return req.id;
+  }
+
+  async getState(id: string): Promise<HITLState> {
+    const result = await this.#db.query<HITLRow>(
+      `SELECT id, state FROM hitl_requests WHERE id = $1`,
+      [id]
+    );
+    const row = result.rows[0];
+    if (!row) throw new HITLNotFoundError(id);
+    return row.state;
+  }
+
+  async await(id: string, timeoutMs?: number): Promise<HITLState> {
+    const deadline = timeoutMs != null ? Date.now() + timeoutMs : Infinity;
+    const POLL_MS = 500;
+
+    for (;;) {
+      const state = await this.getState(id);
+      if (state !== "pending") return state;
+      if (Date.now() >= deadline) return state;
+
+      const remaining = deadline - Date.now();
+      const wait = Math.min(POLL_MS, remaining > 0 ? remaining : 0);
+      await new Promise<void>((resolve) => setTimeout(resolve, wait));
+
+      if (Date.now() >= deadline) return await this.getState(id);
+    }
+  }
+
+  async resolve(
+    id: string,
+    decision: "approved" | "rejected",
+    by: string
+  ): Promise<void> {
+    await this.#db.query("BEGIN", []);
+    try {
+      const result = await this.#db.query<HITLRow>(
+        `SELECT id, state FROM hitl_requests WHERE id = $1 FOR UPDATE`,
+        [id]
+      );
+      const row = result.rows[0];
+      if (!row) {
+        await this.#db.query("ROLLBACK", []);
+        throw new HITLNotFoundError(id);
+      }
+      validateTransition(row.state, decision);
+
+      await this.#db.query(
+        `UPDATE hitl_requests
+            SET state = $1, decision = $2, decided_by = $3, decided_at = NOW()
+          WHERE id = $4`,
+        [decision, decision, by, id]
+      );
+      await this.#db.query("COMMIT", []);
+    } catch (err) {
+      await this.#db.query("ROLLBACK", []).catch(() => undefined);
+      throw err;
+    }
+  }
+
+  async expire(id: string): Promise<void> {
+    await this.#db.query("BEGIN", []);
+    try {
+      const result = await this.#db.query<HITLRow>(
+        `SELECT id, state FROM hitl_requests WHERE id = $1 FOR UPDATE`,
+        [id]
+      );
+      const row = result.rows[0];
+      if (!row) {
+        await this.#db.query("ROLLBACK", []);
+        throw new HITLNotFoundError(id);
+      }
+      validateTransition(row.state, "expired");
+
+      await this.#db.query(
+        `UPDATE hitl_requests SET state = 'expired' WHERE id = $1`,
+        [id]
+      );
+      await this.#db.query("COMMIT", []);
+    } catch (err) {
+      await this.#db.query("ROLLBACK", []).catch(() => undefined);
+      throw err;
+    }
+  }
+
+  /**
+   * Expire all pending requests whose deadline has passed.
+   * Called by runExpireJob via the _expireOverdue duck-type hook.
+   */
+  async _expireOverdue(): Promise<void> {
+    await this.#db.query(
+      `UPDATE hitl_requests
+          SET state = 'expired'
+        WHERE state = 'pending' AND deadline < NOW()`,
+      []
+    );
+  }
+}

package/src/adapters/llm/anthropic-direct.ts

@@ -0,0 +1,212 @@
+/**
+ * AnthropicDirectAdapter — wraps @anthropic-ai/sdk for direct API access.
+ *
+ * BYOM: defaultModel is a constructor param default only.
+ * No model string is hardcoded at module scope.
+ *
+ * Maps Anthropic SDK response to ChatResponse canonical format.
+ */
+
+import Anthropic from "@anthropic-ai/sdk";
+import type {
+  ChatRequest,
+  ChatResponse,
+  ChatUsage,
+  LLMProviderPort,
+  StreamDelta,
+} from "../../ports/llm-provider.js";
+
+export interface AnthropicDirectAdapterConfig {
+  apiKey: string;
+  /** Default model to use when ChatRequest.model is not specified. */
+  defaultModel?: string;
+  /** For testing only — inject a pre-built client instead of creating one. */
+  _clientOverride?: Anthropic;
+}
+
+// Pricing approximation for cost estimation (input/output per token in USD)
+const INPUT_USD_PER_TOKEN = 3 / 1_000_000; // $3 / MTok
+const OUTPUT_USD_PER_TOKEN = 15 / 1_000_000; // $15 / MTok
+
+function estimateInputTokens(req: ChatRequest): number {
+  const chars = req.messages.reduce((sum, m) => sum + m.content.length, 0);
+  return Math.ceil(chars / 4);
+}
+
+function mapStopReason(
+  raw: string | null | undefined
+): ChatResponse["finishReason"] {
+  switch (raw) {
+    case "end_turn":
+      return "stop";
+    case "max_tokens":
+      return "length";
+    case "tool_use":
+      return "tool";
+    default:
+      return "error";
+  }
+}
+
+export class AnthropicDirectAdapter implements LLMProviderPort {
+  private readonly client: Anthropic;
+  private readonly defaultModel: string;
+
+  constructor(config: AnthropicDirectAdapterConfig) {
+    this.client =
+      config._clientOverride ?? new Anthropic({ apiKey: config.apiKey });
+    // BYOM: default only in adapter, never exposed in port
+    this.defaultModel = config.defaultModel ?? "claude-sonnet-4-6";
+  }
+
+  estimateCost(req: ChatRequest): { usd: number } {
+    const inputTokens = estimateInputTokens(req);
+    const maxOutputTokens = req.maxTokens ?? 512;
+    return {
+      usd:
+        inputTokens * INPUT_USD_PER_TOKEN +
+        maxOutputTokens * OUTPUT_USD_PER_TOKEN,
+    };
+  }
+
+  async complete(req: ChatRequest): Promise<ChatResponse> {
+    const model = req.model ?? this.defaultModel;
+
+    // Extract system message (Anthropic API separates system from messages)
+    const systemMessages = req.messages.filter((m) => m.role === "system");
+    const conversationMessages = req.messages.filter(
+      (m) => m.role !== "system"
+    );
+
+    const systemPrompt =
+      systemMessages.length > 0
+        ? systemMessages.map((m) => m.content).join("\n")
+        : undefined;
+
+    if (req.abortSignal?.aborted) {
+      return {
+        content: "",
+        usage: { inputTokens: 0, outputTokens: 0 },
+        model,
+        finishReason: "error",
+      };
+    }
+
+    try {
+      const params: Anthropic.Messages.MessageCreateParamsNonStreaming = {
+        model,
+        max_tokens: req.maxTokens ?? 1024,
+        messages: conversationMessages.map((m) => ({
+          role: m.role as "user" | "assistant",
+          content: m.content,
+        })),
+      };
+
+      if (systemPrompt !== undefined) {
+        params.system = systemPrompt;
+      }
+      if (req.temperature !== undefined) {
+        params.temperature = req.temperature;
+      }
+
+      const response = await this.client.messages.create(params);
+
+      const rawUsage = response.usage;
+      const usage: ChatUsage = {
+        inputTokens: rawUsage.input_tokens,
+        outputTokens: rawUsage.output_tokens,
+        costUsd:
+          rawUsage.input_tokens * INPUT_USD_PER_TOKEN +
+          rawUsage.output_tokens * OUTPUT_USD_PER_TOKEN,
+      };
+
+      const textBlock = response.content.find((b) => b.type === "text");
+      const content = textBlock?.type === "text" ? textBlock.text : "";
+
+      return {
+        content,
+        usage,
+        model: response.model,
+        finishReason: mapStopReason(response.stop_reason),
+      };
+    } catch (err) {
+      if (req.abortSignal?.aborted) {
+        return {
+          content: "",
+          usage: { inputTokens: 0, outputTokens: 0 },
+          model,
+          finishReason: "error",
+        };
+      }
+      // Map Anthropic errors — never rethrow, return error finishReason
+      return {
+        content: "",
+        usage: { inputTokens: 0, outputTokens: 0 },
+        model,
+        finishReason: "error",
+      };
+    }
+  }
+
+  async *stream(req: ChatRequest): AsyncIterable<StreamDelta> {
+    const model = req.model ?? this.defaultModel;
+
+    const systemMessages = req.messages.filter((m) => m.role === "system");
+    const conversationMessages = req.messages.filter(
+      (m) => m.role !== "system"
+    );
+    const systemPrompt =
+      systemMessages.length > 0
+        ? systemMessages.map((m) => m.content).join("\n")
+        : undefined;
+
+    if (req.abortSignal?.aborted) {
+      yield { delta: "", usage: { inputTokens: 0, outputTokens: 0 } };
+      return;
+    }
+
+    try {
+      const params: Parameters<typeof this.client.messages.stream>[0] = {
+        model,
+        max_tokens: req.maxTokens ?? 1024,
+        messages: conversationMessages.map((m) => ({
+          role: m.role as "user" | "assistant",
+          content: m.content,
+        })),
+      };
+
+      if (systemPrompt !== undefined) {
+        params.system = systemPrompt;
+      }
+      if (req.temperature !== undefined) {
+        params.temperature = req.temperature;
+      }
+
+      const stream = this.client.messages.stream(params);
+
+      for await (const event of stream) {
+        if (req.abortSignal?.aborted) break;
+
+        if (
+          event.type === "content_block_delta" &&
+          event.delta.type === "text_delta"
+        ) {
+          yield { delta: event.delta.text };
+        }
+
+        if (event.type === "message_delta" && event.usage) {
+          yield {
+            delta: "",
+            usage: {
+              inputTokens: 0,
+              outputTokens: event.usage.output_tokens,
+            },
+          };
+        }
+      }
+    } catch {
+      // Stream error — yield empty and return
+      yield { delta: "", usage: { inputTokens: 0, outputTokens: 0 } };
+    }
+  }
+}