@vauban-org/agent-sdk 0.16.0

package/src/outcomes/client.ts

@@ -0,0 +1,194 @@
+/**
+ * OutcomesClient — REST client for /api/outcomes/* endpoints.
+ *
+ * Endpoints are defined in sprint-522:quick-4 (command-center HTTP server).
+ * This client is the SDK-side contract: route authors must match these shapes.
+ *
+ * Auth: Bearer token injected via `getToken()` on every call.
+ * Error handling: 4xx responses throw OutcomesApiError.
+ * No Zod dependency — types are validated structurally at the call site.
+ */
+
+import type {
+  CfoView,
+  Outcome,
+  OutcomeSummary,
+  OutcomeType,
+  RoiPerAgent,
+} from "./types.js";
+
+// ─── Error ───────────────────────────────────────────────────────────────────
+
+export class OutcomesApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: string,
+    message?: string,
+  ) {
+    super(message ?? `OutcomesApiError: HTTP ${status}`);
+    this.name = "OutcomesApiError";
+  }
+}
+
+// ─── Filter + response types ─────────────────────────────────────────────────
+
+export interface OutcomesListFilter {
+  agentId?: string;
+  type?: OutcomeType;
+  /** ISO 8601 datetime — inclusive lower bound. */
+  from?: string;
+  /** ISO 8601 datetime — inclusive upper bound. */
+  to?: string;
+  limit?: number;
+  cursor?: string;
+}
+
+export interface OutcomesListResponse {
+  items: Outcome[];
+  /** Opaque cursor for the next page. Absent when no further pages exist. */
+  nextCursor?: string;
+}
+
+// ─── Client interface ─────────────────────────────────────────────────────────
+
+export interface OutcomesClient {
+  /**
+   * List outcomes with optional filtering and cursor-based pagination.
+   * GET /api/outcomes
+   */
+  list(filter?: OutcomesListFilter): Promise<OutcomesListResponse>;
+
+  /**
+   * Aggregated outcome summary for a time window.
+   * GET /api/outcomes/summary?from=...&to=...
+   */
+  summary(period: { from: string; to: string }): Promise<OutcomeSummary>;
+
+  /**
+   * CFO-ready burn-rate and initiative breakdown.
+   * GET /api/outcomes/cfo?from=...&to=...
+   */
+  cfo(period: { from: string; to: string }): Promise<CfoView>;
+
+  /**
+   * Per-agent ROI breakdown for a time window.
+   * GET /api/outcomes/roi?from=...&to=...
+   */
+  roi(
+    period: { from: string; to: string },
+    opts?: { sortBy?: "net_roi_pct" | "value_cents"; limit?: number },
+  ): Promise<RoiPerAgent[]>;
+}
+
+// ─── Implementation ──────────────────────────────────────────────────────────
+
+export interface OutcomesClientOptions {
+  baseUrl: string;
+  /** Called before every request to obtain a fresh Bearer token. */
+  getToken: () => Promise<string>;
+}
+
+class OutcomesClientImpl implements OutcomesClient {
+  private readonly baseUrl: string;
+  private readonly getToken: () => Promise<string>;
+
+  constructor(opts: OutcomesClientOptions) {
+    // Normalise base URL: strip trailing slash to simplify path concatenation.
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.getToken = opts.getToken;
+  }
+
+  // ── private helpers ──────────────────────────────────────────────────────
+
+  private async request<T>(
+    path: string,
+    params?: Record<string, string | number | undefined>,
+  ): Promise<T> {
+    const token = await this.getToken();
+
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params !== undefined) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+
+    const response = await fetch(url.toString(), {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new OutcomesApiError(
+        response.status,
+        body,
+        `OutcomesClient: ${response.status} ${response.statusText} — ${path}`,
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  // ── public methods ───────────────────────────────────────────────────────
+
+  async list(filter: OutcomesListFilter = {}): Promise<OutcomesListResponse> {
+    return this.request<OutcomesListResponse>("/api/outcomes", {
+      agent_id: filter.agentId,
+      type: filter.type,
+      from: filter.from,
+      to: filter.to,
+      limit: filter.limit,
+      cursor: filter.cursor,
+    });
+  }
+
+  async summary(period: {
+    from: string;
+    to: string;
+  }): Promise<OutcomeSummary> {
+    return this.request<OutcomeSummary>("/api/outcomes/summary", {
+      from: period.from,
+      to: period.to,
+    });
+  }
+
+  async cfo(period: { from: string; to: string }): Promise<CfoView> {
+    return this.request<CfoView>("/api/outcomes/cfo", {
+      from: period.from,
+      to: period.to,
+    });
+  }
+
+  async roi(
+    period: { from: string; to: string },
+    opts?: { sortBy?: "net_roi_pct" | "value_cents"; limit?: number },
+  ): Promise<RoiPerAgent[]> {
+    return this.request<RoiPerAgent[]>("/api/outcomes/roi", {
+      from: period.from,
+      to: period.to,
+      sort_by: opts?.sortBy,
+      limit: opts?.limit,
+    });
+  }
+}
+
+/**
+ * Factory — create an OutcomesClient pointed at a Command Center instance.
+ *
+ * @example
+ * const client = createOutcomesClient({
+ *   baseUrl: process.env.COMMAND_CENTER_URL,
+ *   getToken: () => auth.getAccessToken(),
+ * });
+ */
+export function createOutcomesClient(
+  opts: OutcomesClientOptions,
+): OutcomesClient {
+  return new OutcomesClientImpl(opts);
+}

package/src/outcomes/compute-roi.ts

@@ -0,0 +1,89 @@
+/**
+ * computeRoi — pure client-side ROI computation from a set of Outcome rows.
+ *
+ * No network calls. Safe to run in browser or server contexts.
+ * All monetary values are integer cents.
+ */
+
+import type { Outcome } from "./types.js";
+
+export interface ComputeRoiInput {
+  outcomes: Outcome[];
+  /**
+   * Optional external cost map.
+   * When provided, cost for each outcome is taken from this map (looked up by
+   * outcome id) rather than inferred from negative value_cents. Useful when
+   * cost is tracked separately from outcome value (e.g. infra spend is
+   * attributed via a different signal than the outcome row itself).
+   */
+  costsCentsByOutcomeId?: Map<string, number>;
+}
+
+export interface ComputeRoiResult {
+  totalValueCents: number;
+  totalCostCents: number;
+  /** totalValueCents / totalCostCents. Null when totalCostCents == 0. */
+  valueToCostRatio: number | null;
+  /** (totalValueCents - totalCostCents) / totalCostCents * 100. Null when totalCostCents == 0. */
+  netRoiPct: number | null;
+  outcomeCount: number;
+  pendingCount: number;
+}
+
+/**
+ * Compute ROI metrics from a set of Outcome rows.
+ *
+ * Cost inference:
+ * - If `costsCentsByOutcomeId` is provided: cost = map lookup (0 if absent).
+ * - Otherwise: cost = abs(value_cents) for rows where value_cents < 0.
+ *   Positive value_cents contribute to totalValueCents.
+ *
+ * Divide-by-zero is handled: ratios are null when totalCostCents == 0.
+ */
+export function computeRoi(input: ComputeRoiInput): ComputeRoiResult {
+  const { outcomes, costsCentsByOutcomeId } = input;
+
+  let totalValueCents = 0;
+  let totalCostCents = 0;
+  let pendingCount = 0;
+
+  for (const outcome of outcomes) {
+    if (outcome.is_pending_backfill) {
+      pendingCount++;
+    }
+
+    if (costsCentsByOutcomeId !== undefined) {
+      // External cost map mode: value and cost are tracked independently.
+      // value_cents may still be signed; positive rows contribute value.
+      if (outcome.value_cents > 0) {
+        totalValueCents += outcome.value_cents;
+      }
+      const externalCost = costsCentsByOutcomeId.get(outcome.id) ?? 0;
+      totalCostCents += externalCost;
+    } else {
+      // Inferred mode: sign of value_cents determines value vs cost.
+      if (outcome.value_cents >= 0) {
+        totalValueCents += outcome.value_cents;
+      } else {
+        totalCostCents += Math.abs(outcome.value_cents);
+      }
+    }
+  }
+
+  const valueToCostRatio =
+    totalCostCents === 0 ? null : totalValueCents / totalCostCents;
+
+  const netRoiPct =
+    totalCostCents === 0
+      ? null
+      : ((totalValueCents - totalCostCents) / totalCostCents) * 100;
+
+  return {
+    totalValueCents,
+    totalCostCents,
+    valueToCostRatio,
+    netRoiPct,
+    outcomeCount: outcomes.length,
+    pendingCount,
+  };
+}

package/src/outcomes/index.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./compute-roi.js";
+export * from "./client.js";

package/src/outcomes/meter.ts

@@ -0,0 +1,217 @@
+/**
+ * AgentMeter — intra-network agent outcome ledger.
+ *
+ * Sprint-563: B7 — append-only ledger + verifyChain + OutcomeGate.
+ * x402 inter-agent scope deferred to sprint-564 C1.
+ *
+ * recordRun(runId, agentId, outcome) → appends to ledger.
+ * getBalance(agentId, period) → MeterBalance (total runs, total value, net).
+ * verifyChain(agentId, since?) → valid + firstInvalidAt (R8 non-bloquant #3).
+ * OutcomeGate.validate(outcome, threshold) → chargeableCents.
+ */
+
+export interface MeterEntry {
+  agentId: string;
+  runId: string;
+  valueCents: number;
+  timestamp: number;
+  /** Hash of previous entry (chain integrity). */
+  prevHash: string;
+  /** Hash of this entry. */
+  hash: string;
+}
+
+export interface MeterBalance {
+  agentId: string;
+  totalRuns: number;
+  totalValueCents: number;
+  netValueCents: number;
+  firstRunAt: number;
+  lastRunAt: number;
+}
+
+export interface MeterVerifyResult {
+  valid: boolean;
+  firstInvalidAt?: number;
+  reason?: string;
+  totalEntries: number;
+}
+
+function hashEntry(entry: Omit<MeterEntry, "hash">): string {
+  const { hash: _, ...rest } = entry as MeterEntry;
+  return JSON.stringify(rest);
+}
+
+/**
+ * AgentMeter — append-only ledger for agent outcomes.
+ * Internal scope: intra-network only (no x402 cross-agent payments).
+ */
+export class AgentMeter {
+  private ledger: MeterEntry[] = [];
+
+  /** Record a run outcome. Appends to the ledger with chain hash. */
+  recordRun(runId: string, agentId: string, valueCents: number): MeterEntry {
+    const prevHash =
+      this.ledger.length > 0
+        ? this.ledger[this.ledger.length - 1]!.hash
+        : "genesis";
+
+    const rawEntry = {
+      agentId,
+      runId,
+      valueCents,
+      timestamp: Date.now(),
+      prevHash,
+    };
+
+    const entry: MeterEntry = {
+      ...rawEntry,
+      hash: hashEntry(rawEntry),
+    };
+
+    this.ledger.push(entry);
+    return entry;
+  }
+
+  /** Get balance for an agent within a time period. */
+  getBalance(agentId: string, since?: number): MeterBalance {
+    const runs = this.ledger.filter(
+      (e) => e.agentId === agentId && (since === undefined || e.timestamp >= since),
+    );
+
+    if (runs.length === 0) {
+      return {
+        agentId,
+        totalRuns: 0,
+        totalValueCents: 0,
+        netValueCents: 0,
+        firstRunAt: 0,
+        lastRunAt: 0,
+      };
+    }
+
+    const netValueCents = runs.reduce((s, e) => s + e.valueCents, 0);
+    const totalValueCents = runs.reduce((s, e) => s + Math.abs(e.valueCents), 0);
+    return {
+      agentId,
+      totalRuns: runs.length,
+      totalValueCents,
+      netValueCents,
+      firstRunAt: runs[0]!.timestamp,
+      lastRunAt: runs[runs.length - 1]!.timestamp,
+    };
+  }
+
+  /** Verify chain integrity. Returns first invalid entry index or null if all valid. */
+  verifyChain(agentId?: string, since?: number): MeterVerifyResult {
+    const entries = this.ledger.filter(
+      (e) =>
+        (agentId === undefined || e.agentId === agentId) &&
+        (since === undefined || e.timestamp >= since),
+    );
+
+    if (entries.length === 0) {
+      return { valid: true, totalEntries: 0 };
+    }
+
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i]!;
+      const expectedHash = hashEntry(entry);
+
+      // Check hash consistency
+      if (entry.hash !== expectedHash) {
+        const originalIndex = this.ledger.indexOf(entry);
+        return {
+          valid: false,
+          firstInvalidAt: originalIndex,
+          reason: `Hash mismatch at entry ${i}: expected ${expectedHash}, got ${entry.hash}`,
+          totalEntries: entries.length,
+        };
+      }
+
+      // Check chain continuity
+      if (i > 0) {
+        const prevEntry = entries[i - 1]!;
+        if (entry.prevHash !== prevEntry.hash) {
+          const originalIndex = this.ledger.indexOf(entry);
+          return {
+            valid: false,
+            firstInvalidAt: originalIndex,
+            reason: `Chain broken at entry ${i}: prevHash ${entry.prevHash} != ${prevEntry.hash}`,
+            totalEntries: entries.length,
+          };
+        }
+      }
+    }
+
+    return { valid: true, totalEntries: entries.length };
+  }
+
+  /** Export full ledger (for storage/persistence). */
+  export(): MeterEntry[] {
+    return [...this.ledger];
+  }
+
+  /** Import ledger entries (from storage). */
+  import(entries: MeterEntry[]): void {
+    this.ledger = [...entries];
+  }
+}
+
+// ─── OutcomeGate ─────────────────────────────────────────────────────────────
+
+export interface OutcomeGateResult {
+  allowed: boolean;
+  chargeableCents: number;
+  reason?: string;
+}
+
+export interface OutcomeGateOptions {
+  /** Maximum value per run (cents). Reject if outcome exceeds this. */
+  maxValueCents?: number;
+  /** Minimum value per run (cents). Reject if outcome is below this. */
+  minValueCents?: number;
+  /** Maximum cumulative spend in period (cents). */
+  maxCumulativeCents?: number;
+}
+
+/**
+ * OutcomeGate — validates agent outcomes against thresholds.
+ * Used to gate agent actions before execution.
+ */
+export function validateOutcome(
+  outcome: { valueCents: number },
+  currentBalance: MeterBalance,
+  opts: OutcomeGateOptions = {},
+): OutcomeGateResult {
+  const chargeableCents = Math.max(0, outcome.valueCents);
+
+  if (opts.minValueCents !== undefined && chargeableCents < opts.minValueCents) {
+    return {
+      allowed: false,
+      chargeableCents: 0,
+      reason: `Outcome value ${chargeableCents} below minimum ${opts.minValueCents}`,
+    };
+  }
+
+  if (opts.maxValueCents !== undefined && chargeableCents > opts.maxValueCents) {
+    return {
+      allowed: false,
+      chargeableCents: 0,
+      reason: `Outcome value ${chargeableCents} exceeds maximum ${opts.maxValueCents}`,
+    };
+  }
+
+  if (
+    opts.maxCumulativeCents !== undefined &&
+    currentBalance.totalValueCents + chargeableCents > opts.maxCumulativeCents
+  ) {
+    return {
+      allowed: false,
+      chargeableCents: 0,
+      reason: `Cumulative spend ${currentBalance.totalValueCents + chargeableCents} exceeds max ${opts.maxCumulativeCents}`,
+    };
+  }
+
+  return { allowed: true, chargeableCents };
+}

package/src/outcomes/trajectory.ts

@@ -0,0 +1,170 @@
+/**
+ * Trajectory export — RLHF/DPO training data from agent traces.
+ *
+ * Sprint-563: B3 — exportTrajectory(runId, db, opts).
+ *
+ * Formats:
+ *  - jsonl: one JSON object per line, auto-labeled (positive/negative/neutral)
+ *  - openai-dpo: OpenAI-compatible DPO format with chosen/rejected pairs
+ *
+ * Auto-labeling: outcome.value_cents > 0 → positive, < 0 → negative, null → neutral.
+ */
+
+import type { DbClient } from "../tracking/agent-run-tracker.js";
+
+export type TrajectoryFormat = "jsonl" | "openai-dpo";
+
+export interface TrajectoryOptions {
+  format: TrajectoryFormat;
+  /** Minimum tokens to include a step (skip empty LLM calls). */
+  minTokens?: number;
+  /** Maximum steps to export (default 1000). */
+  maxSteps?: number;
+}
+
+export interface TrajectoryStep {
+  runId: string;
+  stepIndex: number;
+  phase: string;
+  type: string;
+  input?: unknown;
+  output?: unknown;
+  model?: string;
+  provider?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  costUsd?: number;
+  durationMs?: number;
+  timestamp?: string;
+  /** Auto-label: positive | negative | neutral */
+  label: "positive" | "negative" | "neutral";
+}
+
+export interface TrajectoryExport {
+  steps: TrajectoryStep[];
+  totalCost: number;
+  totalTokens: number;
+  format: TrajectoryFormat;
+}
+
+/**
+ * Fetch trace steps from a run and export as training trajectory.
+ * Uses the db client to query run_step rows.
+ */
+export async function exportTrajectory(
+  runId: string,
+  db: DbClient,
+  opts: TrajectoryOptions = { format: "jsonl" },
+): Promise<TrajectoryExport> {
+  const maxSteps = opts.maxSteps ?? 1000;
+  const minTokens = opts.minTokens ?? 0;
+
+  // Query steps from DB
+  const rows = await db.query?.(
+    `SELECT step_index, phase, type, payload, model, provider,
+            input_tokens, output_tokens, cost_usd, duration_ms,
+            created_at, outcome_value_cents
+     FROM run_step
+     WHERE run_id = $1
+     ORDER BY step_index
+     LIMIT $2`,
+    [runId, String(maxSteps)],
+  );
+
+  const steps: TrajectoryStep[] = [];
+
+  if (rows?.rows) {
+    for (const row of rows.rows as Array<Record<string, unknown>>) {
+      const inputTokens = Number(row.input_tokens ?? 0);
+      const outputTokens = Number(row.output_tokens ?? 0);
+      if (inputTokens + outputTokens < minTokens) continue;
+
+      const valueCents = row.outcome_value_cents != null
+        ? Number(row.outcome_value_cents)
+        : null;
+
+      steps.push({
+        runId,
+        stepIndex: Number(row.step_index ?? 0),
+        phase: String(row.phase ?? "unknown"),
+        type: String(row.type ?? "unknown"),
+        input: tryParse(row.payload),
+        output: tryParse(row.output),
+        model: row.model ? String(row.model) : undefined,
+        provider: row.provider ? String(row.provider) : undefined,
+        inputTokens,
+        outputTokens,
+        costUsd: Number(row.cost_usd ?? 0),
+        durationMs: Number(row.duration_ms ?? 0),
+        timestamp: row.created_at ? String(row.created_at) : undefined,
+        label: valueCents === null ? "neutral"
+          : valueCents > 0 ? "positive"
+          : "negative",
+      });
+    }
+  }
+
+  const totalCost = steps.reduce((s, st) => s + (st.costUsd ?? 0), 0);
+  const totalTokens = steps.reduce(
+    (s, st) => s + (st.inputTokens ?? 0) + (st.outputTokens ?? 0),
+    0,
+  );
+
+  return { steps, totalCost, totalTokens, format: opts.format };
+}
+
+/**
+ * Serialize a trajectory export to the requested format.
+ */
+export function serializeTrajectory(exp: TrajectoryExport): string {
+  if (exp.format === "jsonl") {
+    return exp.steps.map((s) => JSON.stringify(s)).join("\n");
+  }
+
+  // openai-dpo: pair consecutive steps as chosen/rejected
+  const pairs: Array<{ chosen: TrajectoryStep; rejected: TrajectoryStep }> = [];
+  const positive = exp.steps.filter((s) => s.label === "positive");
+  const negative = exp.steps.filter((s) => s.label === "negative");
+
+  for (let i = 0; i < Math.min(positive.length, negative.length); i++) {
+    pairs.push({ chosen: positive[i]!, rejected: negative[i]! });
+  }
+
+  return pairs
+    .map((p) =>
+      JSON.stringify({
+        chosen: formatDpoMessage(p.chosen),
+        rejected: formatDpoMessage(p.rejected),
+      }),
+    )
+    .join("\n");
+}
+
+function formatDpoMessage(step: TrajectoryStep): unknown {
+  return {
+    messages: [
+      ...(step.input
+        ? [{ role: "user", content: typeof step.input === "string" ? step.input : JSON.stringify(step.input) }]
+        : []),
+      ...(step.output
+        ? [{ role: "assistant", content: typeof step.output === "string" ? step.output : JSON.stringify(step.output) }]
+        : []),
+    ],
+    metadata: {
+      model: step.model,
+      cost_usd: step.costUsd,
+      label: step.label,
+    },
+  };
+}
+
+function tryParse(v: unknown): unknown {
+  if (typeof v === "string") {
+    try {
+      return JSON.parse(v);
+    } catch {
+      return v;
+    }
+  }
+  return v;
+}