@vauban-org/agent-sdk 0.16.0

package/src/tracking/agent-run-tracker.ts

@@ -0,0 +1,228 @@
+/**
+ * AgentRunTracker — per-run token/cost accounting for agent loops.
+ *
+ * Lifecycle:
+ *   1. start(input)      → INSERT agent_run row with status='running', returns UUID.
+ *   2. recordStep(uuid)  → UPDATE increments input/output/tool_calls/cost_usd counters.
+ *   3. finish(uuid)      → UPDATE sets finished_at, status, stop_reason.
+ *
+ * Contract: agent_version is required at start().
+ * Cost is NUMERIC(10,6) USD (Postgres returns as string from pg driver — we
+ * normalise to string at the boundary).
+ *
+ * Persistence layer only — no side effects beyond DB. OTel spans are emitted
+ * by the caller (loop) with `gen_ai.usage.*` attributes.
+ */
+
+// ─── DbClient interface (inlined to avoid CC dep) ────────────────────────────
+
+/**
+ * Minimal injectable Postgres interface.
+ * Compatible with `pg.Pool`, `pg.Client`, and test mocks.
+ */
+export interface DbClient {
+  query<T extends object>(
+    sql: string,
+    params?: unknown[],
+  ): Promise<{ rows: T[]; rowCount?: number }>;
+}
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export interface AgentRunStartInput {
+  agentId: string;
+  agentVersion: string;
+  /** Caller-generated run id (matches the loop's runId / trace). */
+  runId: string;
+  model: string;
+  provider: string;
+  tenantId?: string;
+  /** OTel trace id for replay linkage. */
+  traceId?: string;
+}
+
+export interface AgentRunStepDelta {
+  inputTokens: number;
+  outputTokens: number;
+  toolCalls?: number;
+  /**
+   * USD delta for this step. Must be >= 0 (cumulative counter).
+   * Accepts number or string; normalised to fixed(6) in SQL binding.
+   */
+  costUsd: number;
+}
+
+export type AgentRunFinalStatus =
+  | "success"
+  | "failed"
+  | "timeout"
+  | "incoherent";
+
+export interface AgentRunFinish {
+  status: AgentRunFinalStatus;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+export interface AgentRunTracker {
+  /** Insert a new row in 'running' status; returns the UUID. */
+  start(input: AgentRunStartInput): Promise<string>;
+  /** Increment counters atomically. Idempotent per-call (caller dedupes). */
+  recordStep(uuid: string, delta: AgentRunStepDelta): Promise<void>;
+  /** Terminal transition — sets finished_at + status. */
+  finish(uuid: string, result: AgentRunFinish): Promise<void>;
+}
+
+// ─── Validation helpers ──────────────────────────────────────────────────────
+
+function assertNonEmpty(name: string, v: unknown): asserts v is string {
+  if (typeof v !== "string" || v.length === 0) {
+    throw new Error(`agent-run-tracker: ${name} must be a non-empty string`);
+  }
+}
+
+function assertNonNegativeInt(name: string, v: unknown): asserts v is number {
+  if (!Number.isFinite(v) || !Number.isInteger(v) || (v as number) < 0) {
+    throw new Error(
+      `agent-run-tracker: ${name} must be a non-negative integer`,
+    );
+  }
+}
+
+function assertNonNegativeCost(name: string, v: unknown): asserts v is number {
+  if (!Number.isFinite(v) || (v as number) < 0) {
+    throw new Error(
+      `agent-run-tracker: ${name} must be a non-negative finite number`,
+    );
+  }
+}
+
+function assertUuid(name: string, v: unknown): asserts v is string {
+  // Loose uuid check (36 chars with dashes) — DB has full constraint via type.
+  if (
+    typeof v !== "string" ||
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v)
+  ) {
+    throw new Error(`agent-run-tracker: ${name} must be a UUID`);
+  }
+}
+
+// ─── Implementation ──────────────────────────────────────────────────────────
+
+class AgentRunTrackerImpl implements AgentRunTracker {
+  constructor(private readonly db: DbClient) {}
+
+  async start(input: AgentRunStartInput): Promise<string> {
+    assertNonEmpty("agentId", input.agentId);
+    assertNonEmpty("agentVersion", input.agentVersion);
+    assertNonEmpty("runId", input.runId);
+    assertNonEmpty("model", input.model);
+    assertNonEmpty("provider", input.provider);
+
+    const result = await this.db.query<{ id: string }>(
+      `INSERT INTO agent_run
+         (agent_id, agent_version, run_id, model, provider,
+          tenant_id, trace_id, status, started_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, 'running', NOW())
+       RETURNING id`,
+      [
+        input.agentId,
+        input.agentVersion,
+        input.runId,
+        input.model,
+        input.provider,
+        input.tenantId ?? null,
+        input.traceId ?? null,
+      ],
+    );
+
+    const row = result.rows[0];
+    if (!row) {
+      throw new Error("agent-run-tracker: insert did not return an id");
+    }
+    return row.id;
+  }
+
+  async recordStep(uuid: string, delta: AgentRunStepDelta): Promise<void> {
+    assertUuid("uuid", uuid);
+    assertNonNegativeInt("inputTokens", delta.inputTokens);
+    assertNonNegativeInt("outputTokens", delta.outputTokens);
+    if (delta.toolCalls !== undefined) {
+      assertNonNegativeInt("toolCalls", delta.toolCalls);
+    }
+    assertNonNegativeCost("costUsd", delta.costUsd);
+
+    // Use numeric addition at the DB for atomicity; bind cost as fixed(6) string
+    // to avoid float64 imprecision accumulating over many steps.
+    const costStr = delta.costUsd.toFixed(6);
+
+    await this.db.query(
+      `UPDATE agent_run
+         SET input_tokens     = input_tokens     + $2,
+             output_tokens    = output_tokens    + $3,
+             tool_calls_count = tool_calls_count + $4,
+             cost_usd         = cost_usd         + $5::numeric
+       WHERE id = $1
+         AND status = 'running'`,
+      [
+        uuid,
+        delta.inputTokens,
+        delta.outputTokens,
+        delta.toolCalls ?? 0,
+        costStr,
+      ],
+    );
+  }
+
+  async finish(uuid: string, result: AgentRunFinish): Promise<void> {
+    assertUuid("uuid", uuid);
+    const validStatuses: AgentRunFinalStatus[] = [
+      "success",
+      "failed",
+      "timeout",
+      "incoherent",
+    ];
+    if (!validStatuses.includes(result.status)) {
+      throw new Error(
+        `agent-run-tracker: status must be one of ${validStatuses.join(", ")}`,
+      );
+    }
+    if (
+      result.stopReason !== undefined &&
+      typeof result.stopReason !== "string"
+    ) {
+      throw new Error(
+        "agent-run-tracker: stopReason must be a string when provided",
+      );
+    }
+    if (
+      result.errorMessage !== undefined &&
+      typeof result.errorMessage !== "string"
+    ) {
+      throw new Error(
+        "agent-run-tracker: errorMessage must be a string when provided",
+      );
+    }
+
+    await this.db.query(
+      `UPDATE agent_run
+         SET status        = $2,
+             stop_reason   = $3,
+             error_message = $4,
+             finished_at   = NOW()
+       WHERE id = $1
+         AND status = 'running'`,
+      [
+        uuid,
+        result.status,
+        result.stopReason ?? null,
+        result.errorMessage ?? null,
+      ],
+    );
+  }
+}
+
+/** Factory — inject a DbClient (pg.Pool or test mock). */
+export function createAgentRunTracker(db: DbClient): AgentRunTracker {
+  return new AgentRunTrackerImpl(db);
+}

package/src/tracking/gen-ai.ts

@@ -0,0 +1,153 @@
+/**
+ * tracking/gen-ai — OpenTelemetry GenAI semantic conventions wrapper.
+ *
+ * https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ *
+ * Scope: thin helpers that create spans with the standard `gen_ai.*`
+ * attribute set. Each helper returns the span so the caller can add
+ * provider-specific attributes and call `.end()` when done — mirrors the
+ * `@opentelemetry/api` ergonomics.
+ *
+ * Custom Vauban attributes (not in spec):
+ *   - gen_ai.agent.run_id     (our runId; used for replay linkage)
+ *   - gen_ai.agent.compacted  (event marker — emitted by AgentLoop)
+ */
+
+import { type Span, type Tracer, trace } from "@opentelemetry/api";
+
+const TRACER_VERSION = "0.10.0";
+
+export function getTracer(name = "vauban-agent-sdk"): Tracer {
+  return trace.getTracer(name, TRACER_VERSION);
+}
+
+// ─── LLM span ─────────────────────────────────────────────────────────────
+
+export function llmSpan(
+  tracer: Tracer,
+  request: {
+    provider: string;
+    model: string;
+    maxTokens?: number;
+    messageCount?: number;
+    temperature?: number;
+    topP?: number;
+    seed?: number;
+  },
+): Span {
+  const span = tracer.startSpan(`gen_ai.${request.provider}.chat`);
+  span.setAttribute("gen_ai.operation.name", "chat");
+  span.setAttribute("gen_ai.system", request.provider);
+  span.setAttribute("gen_ai.request.model", request.model);
+  if (request.maxTokens !== undefined) {
+    span.setAttribute("gen_ai.request.max_tokens", request.maxTokens);
+  }
+  if (request.messageCount !== undefined) {
+    span.setAttribute("gen_ai.request.message_count", request.messageCount);
+  }
+  if (request.temperature !== undefined) {
+    span.setAttribute("gen_ai.request.temperature", request.temperature);
+  }
+  if (request.topP !== undefined) {
+    span.setAttribute("gen_ai.request.top_p", request.topP);
+  }
+  if (request.seed !== undefined) {
+    span.setAttribute("gen_ai.request.seed", request.seed);
+  }
+  return span;
+}
+
+export function recordLlmUsage(
+  span: Span,
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    latencyMs: number;
+    finishReason?: string;
+    responseId?: string;
+  },
+): void {
+  span.setAttribute("gen_ai.usage.input_tokens", usage.inputTokens);
+  span.setAttribute("gen_ai.usage.output_tokens", usage.outputTokens);
+  span.setAttribute("gen_ai.latency_ms", usage.latencyMs);
+  if (usage.finishReason) {
+    span.setAttribute("gen_ai.response.finish_reasons", [usage.finishReason]);
+  }
+  if (usage.responseId) {
+    span.setAttribute("gen_ai.response.id", usage.responseId);
+  }
+}
+
+// ─── Tool span ────────────────────────────────────────────────────────────
+
+export function toolSpan(
+  tracer: Tracer,
+  toolName: string,
+  args: unknown,
+): Span {
+  const span = tracer.startSpan(`gen_ai.tool.${toolName}`);
+  span.setAttribute("gen_ai.operation.name", "tool");
+  span.setAttribute("gen_ai.tool.name", toolName);
+  try {
+    const serialized = JSON.stringify(args);
+    if (typeof serialized === "string") {
+      // Cap to avoid attribute bloat.
+      span.setAttribute("gen_ai.tool.args_preview", serialized.slice(0, 500));
+    }
+  } catch {
+    // Unserialisable args — skip the preview rather than fail the span.
+  }
+  return span;
+}
+
+export function recordToolResult(
+  span: Span,
+  result: {
+    success: boolean;
+    errorMessage?: string;
+    outputSizeBytes?: number;
+  },
+): void {
+  span.setAttribute("gen_ai.tool.success", result.success);
+  if (result.errorMessage) {
+    span.setAttribute("gen_ai.tool.error_message", result.errorMessage);
+  }
+  if (result.outputSizeBytes !== undefined) {
+    span.setAttribute("gen_ai.tool.output_size_bytes", result.outputSizeBytes);
+  }
+}
+
+// ─── Agent span ───────────────────────────────────────────────────────────
+
+export function agentSpan(
+  tracer: Tracer,
+  opts: { agentId: string; agentVersion: string; runId: string },
+): Span {
+  const span = tracer.startSpan(`gen_ai.agent.${opts.agentId}`);
+  span.setAttribute("gen_ai.operation.name", "agent");
+  span.setAttribute("gen_ai.agent.id", opts.agentId);
+  span.setAttribute("gen_ai.agent.version", opts.agentVersion);
+  span.setAttribute("gen_ai.agent.run_id", opts.runId);
+  return span;
+}
+
+/**
+ * recordOutcome — convenience helper to stamp the final outcome of an agent
+ * run onto an existing span. Call from the loop's finally block.
+ */
+export function recordOutcome(
+  span: Span,
+  outcome: {
+    stopReason: string;
+    inputTokens: number;
+    outputTokens: number;
+    stepCount?: number;
+  },
+): void {
+  span.setAttribute("gen_ai.agent.stop_reason", outcome.stopReason);
+  span.setAttribute("gen_ai.usage.input_tokens", outcome.inputTokens);
+  span.setAttribute("gen_ai.usage.output_tokens", outcome.outputTokens);
+  if (outcome.stepCount !== undefined) {
+    span.setAttribute("gen_ai.agent.step_count", outcome.stepCount);
+  }
+}

package/src/tracking/index.ts

@@ -0,0 +1,19 @@
+export { createAgentRunTracker } from "./agent-run-tracker.js";
+export type {
+  AgentRunTracker,
+  AgentRunStartInput,
+  AgentRunStepDelta,
+  AgentRunFinish,
+  AgentRunFinalStatus,
+  DbClient,
+} from "./agent-run-tracker.js";
+
+export {
+  getTracer,
+  llmSpan,
+  recordLlmUsage,
+  toolSpan,
+  recordToolResult,
+  agentSpan,
+  recordOutcome,
+} from "./gen-ai.js";

package/src/types/agent.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared agent types — promoted from Forge to SDK (Vague 1.B.1).
+ *
+ * These types are generic (no Forge-specific business logic) and safe to
+ * consume from any SDK consumer (CC, Forge, other agents).
+ *
+ * Forge-specific types (CitadelContactsPort outcome types, platform clients)
+ * remain in `forge/src/agents/shared/types.ts`.
+ *
+ * @public @since 0.17.0
+ */
+
+import type { BrainPort } from "../ports/brain.js";
+import type { LoggerPort } from "../ports/logger.js";
+import type { DbClient } from "../tracking/agent-run-tracker.js";
+import type { SkillRegistry } from "../orchestration/ooda/skills.js";
+import type { ExecutionMode } from "../orchestration/ooda/types.js";
+import type { EventBusPort } from "../ports/event-bus.js";
+
+// ─── Escalation Levels ────────────────────────────────────────────────────────
+
+/**
+ * EscalationLevel — four-tier escalation pyramid for agent actions.
+ *
+ * - `L0`: Fully autonomous, no human review.
+ * - `L1`: Autonomous with local audit log (L1_autonomous in CC SDK).
+ * - `L2`: Async review by a human before irreversible effects.
+ * - `L3`: Synchronous HITL (Human-In-The-Loop) approval required.
+ *
+ * Aligned with CC SDK EscalationPyramid terminology via `toSdkEscalationLevel()`.
+ */
+export type EscalationLevel = "L0" | "L1" | "L2" | "L3";
+
+// ─── Agent Action ─────────────────────────────────────────────────────────────
+
+/**
+ * AgentAction — declared in the OODA decide phase, consumed by EscalationPyramid.
+ *
+ * `estimatedCostCents` MUST be an integer (centimes). Never a float.
+ *
+ * @public
+ */
+export interface AgentAction {
+  /** Discriminant for the action type (e.g. "post_tweet", "record_outcome"). */
+  readonly type: string;
+  /** Escalation tier required before execution. */
+  readonly escalationLevel: EscalationLevel;
+  /** Whether this action can be undone after execution. */
+  readonly reversible: boolean;
+  /** Estimated cost in integer centimes (never float). Optional. */
+  readonly estimatedCostCents?: number;
+  /** Free-form action payload, validated by the consumer. */
+  readonly payload: Record<string, unknown>;
+}
+
+// ─── Agent Dependencies ───────────────────────────────────────────────────────
+
+/**
+ * AgentDependencies — generic dependency bundle injected at agent construction.
+ *
+ * Only generic, host-level dependencies are included here. Forge-specific
+ * dependencies (xClient, farcasterClient, rempartClient, citadelContacts,
+ * platform webhooks) remain in Forge's local type extension.
+ *
+ * Consumer agents may extend this interface for their own extras:
+ * ```ts
+ * interface MyAgentDeps extends AgentDependencies {
+ *   myClient: MyClient;
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface AgentDependencies {
+  /** Brain memory port (working + episodic + semantic + procedural tiers). */
+  readonly brain: BrainPort;
+  /** Database client for run tracking and persistence. */
+  readonly db: DbClient;
+  /** Structured logger (Pino-compatible). */
+  readonly logger: LoggerPort;
+  /** Redis client (untyped — consumers cast to their redis client type). */
+  readonly redis: unknown;
+  /** Skill registry for OODA phases. */
+  readonly skills: SkillRegistry;
+  /** Execution mode: "dry-run" (no side-effects) or "live". */
+  readonly executionMode: ExecutionMode;
+  /** LiteLLM base URL for BYOM model routing. Optional. */
+  readonly litellmUrl?: string;
+  /** Database URL for direct Postgres access. Optional. */
+  readonly databaseUrl?: string;
+  /** Event bus for cross-product HMAC-signed events (ADR-ECO-017). Optional. */
+  readonly eventBus?: EventBusPort;
+}

package/src/types/escalation-mapping.ts

@@ -0,0 +1,48 @@
+/**
+ * Escalation mapping helpers — Forge EscalationLevel → CC SDK pyramid levels.
+ *
+ * Promoted from Forge (Vague 1.B.1). Pure mapping, no external dependencies.
+ *
+ * @public @since 0.17.0
+ */
+
+import type { EscalationLevel } from "./agent.js";
+
+/**
+ * CC SDK EscalationPyramid level strings.
+ *
+ * - `L1_autonomous`: Fully autonomous execution (L0/L1 Forge).
+ * - `L2_async_review`: Async human review before irreversible effects (L2 Forge).
+ * - `L3_hitl_required`: Synchronous HITL approval required (L3 Forge).
+ */
+export type SdkEscalationLevel =
+  | "L1_autonomous"
+  | "L2_async_review"
+  | "L3_hitl_required";
+
+/**
+ * Map a Forge `EscalationLevel` to the CC SDK `EscalationPyramid` level.
+ *
+ * Both L0 and L1 map to `L1_autonomous` because Forge uses L0 for truly
+ * unchecked actions and L1 for audit-logged autonomous actions — both
+ * are autonomous from the CC SDK pyramid perspective.
+ *
+ * @example
+ * ```ts
+ * const sdkLevel = toSdkEscalationLevel("L2"); // "L2_async_review"
+ * ```
+ */
+export function toSdkEscalationLevel(
+  level: EscalationLevel
+): SdkEscalationLevel {
+  switch (level) {
+    case "L0":
+      return "L1_autonomous";
+    case "L1":
+      return "L1_autonomous";
+    case "L2":
+      return "L2_async_review";
+    case "L3":
+      return "L3_hitl_required";
+  }
+}