@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/src/ports/observability.contract.test.ts

@@ -0,0 +1,315 @@
+/**
+ * ObservabilityPort contract tests — validate port interface compliance.
+ *
+ * Tests verify:
+ * - startSpan returns a valid Span with all methods
+ * - recordEvent accepts all 5 severity levels
+ * - recordMetric accepts gauge, counter, histogram types
+ * - flush() resolves successfully
+ * - NoopObservabilityPort satisfies the interface
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  NoopObservabilityPort,
+  type ObservabilityEvent,
+} from "./observability";
+
+describe("ObservabilityPort contract", () => {
+  describe("startSpan", () => {
+    it("returns a Span with all required methods", () => {
+      const port = new NoopObservabilityPort();
+      const span = port.startSpan("test.span", {
+        service: "test",
+        version: 1,
+      });
+
+      expect(span).toBeDefined();
+      expect(typeof span.setAttribute).toBe("function");
+      expect(typeof span.recordException).toBe("function");
+      expect(typeof span.setStatus).toBe("function");
+      expect(typeof span.end).toBe("function");
+    });
+
+    it("accepts span name and optional attributes", () => {
+      const port = new NoopObservabilityPort();
+      const span1 = port.startSpan("workflow.execute");
+      const span2 = port.startSpan("brain.query", {
+        query: "test",
+        category: "semantic",
+        limit: 10,
+      });
+
+      expect(span1).toBeDefined();
+      expect(span2).toBeDefined();
+      span1.end();
+      span2.end();
+    });
+
+    it("span.setAttribute accepts string, number, boolean, and arrays", () => {
+      const port = new NoopObservabilityPort();
+      const span = port.startSpan("test");
+
+      span.setAttribute("string_attr", "hello");
+      span.setAttribute("number_attr", 42);
+      span.setAttribute("bool_attr", true);
+      span.setAttribute("string_array_attr", ["a", "b", "c"]);
+      span.setAttribute("number_array_attr", [1, 2, 3]);
+
+      expect(true).toBe(true); // noop implementation succeeds silently
+      span.end();
+    });
+
+    it("span.recordException accepts Error or unknown", () => {
+      const port = new NoopObservabilityPort();
+      const span = port.startSpan("test");
+
+      span.recordException(new Error("test error"));
+      span.recordException({ message: "unknown error" });
+      span.recordException("string error");
+
+      expect(true).toBe(true);
+      span.end();
+    });
+
+    it("span.setStatus accepts code and optional message", () => {
+      const port = new NoopObservabilityPort();
+      const span = port.startSpan("test");
+
+      span.setStatus({ code: "OK" });
+      span.setStatus({ code: "ERROR", message: "something went wrong" });
+
+      expect(true).toBe(true);
+      span.end();
+    });
+
+    it("span.end completes the span", () => {
+      const port = new NoopObservabilityPort();
+      const span = port.startSpan("test");
+
+      expect(() => span.end()).not.toThrow();
+    });
+  });
+
+  describe("recordEvent", () => {
+    it("accepts events with all 5 severity levels", () => {
+      const port = new NoopObservabilityPort();
+      const severities = ["debug", "info", "warn", "error", "fatal"] as const;
+
+      for (const severity of severities) {
+        const event: ObservabilityEvent = {
+          name: `event.${severity}`,
+          severity,
+        };
+        expect(() => port.recordEvent(event)).not.toThrow();
+      }
+    });
+
+    it("accepts optional attributes, timestamp, traceId, spanId", () => {
+      const port = new NoopObservabilityPort();
+      const event: ObservabilityEvent = {
+        name: "test.event",
+        severity: "info",
+        attributes: {
+          user_id: "user-123",
+          action: "created",
+          resource_count: 5,
+        },
+        timestamp: Date.now(),
+        traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+        spanId: "00f067aa0ba902b7",
+      };
+
+      expect(() => port.recordEvent(event)).not.toThrow();
+    });
+
+    it("attributes can contain strings, numbers, booleans, and arrays", () => {
+      const port = new NoopObservabilityPort();
+      const event: ObservabilityEvent = {
+        name: "complex.event",
+        severity: "warn",
+        attributes: {
+          message: "test warning",
+          count: 42,
+          enabled: true,
+          tags: ["tag1", "tag2"],
+          scores: [9.5, 8.7, 9.2],
+        },
+      };
+
+      expect(() => port.recordEvent(event)).not.toThrow();
+    });
+  });
+
+  describe("recordMetric", () => {
+    it("accepts gauge type metrics", () => {
+      const port = new NoopObservabilityPort();
+      port.recordMetric({
+        name: "memory.usage",
+        type: "gauge",
+        value: 512,
+        labels: { instance: "worker-1" },
+      });
+
+      expect(true).toBe(true);
+    });
+
+    it("accepts counter type metrics", () => {
+      const port = new NoopObservabilityPort();
+      port.recordMetric({
+        name: "requests.total",
+        type: "counter",
+        value: 1,
+        labels: { endpoint: "/api/query" },
+      });
+
+      expect(true).toBe(true);
+    });
+
+    it("accepts histogram type metrics", () => {
+      const port = new NoopObservabilityPort();
+      port.recordMetric({
+        name: "request.duration",
+        type: "histogram",
+        value: 125,
+        labels: { method: "POST" },
+      });
+
+      expect(true).toBe(true);
+    });
+
+    it("optional timestamp defaults to Date.now()", () => {
+      const port = new NoopObservabilityPort();
+      const before = Date.now();
+      port.recordMetric({
+        name: "test.metric",
+        type: "gauge",
+        value: 100,
+      });
+      const after = Date.now();
+
+      expect(after).toBeGreaterThanOrEqual(before);
+    });
+
+    it("accepts metrics without labels", () => {
+      const port = new NoopObservabilityPort();
+      port.recordMetric({
+        name: "simple.metric",
+        type: "gauge",
+        value: 42,
+      });
+
+      expect(true).toBe(true);
+    });
+  });
+
+  describe("flush", () => {
+    it("resolves successfully", async () => {
+      const port = new NoopObservabilityPort();
+      const result = port.flush();
+
+      expect(result).toBeInstanceOf(Promise);
+      await expect(result).resolves.toBeUndefined();
+    });
+
+    it("can be called multiple times", async () => {
+      const port = new NoopObservabilityPort();
+
+      await expect(port.flush()).resolves.toBeUndefined();
+      await expect(port.flush()).resolves.toBeUndefined();
+      await expect(port.flush()).resolves.toBeUndefined();
+    });
+  });
+
+  describe("NoopObservabilityPort interface compliance", () => {
+    it("satisfies ObservabilityPort contract", () => {
+      const port = new NoopObservabilityPort();
+
+      // All methods required by ObservabilityPort are present
+      expect(typeof port.startSpan).toBe("function");
+      expect(typeof port.recordEvent).toBe("function");
+      expect(typeof port.recordMetric).toBe("function");
+      expect(typeof port.flush).toBe("function");
+    });
+
+    it("startSpan, recordEvent, recordMetric work together", () => {
+      const port = new NoopObservabilityPort();
+
+      const span = port.startSpan("integration.test", { phase: "setup" });
+      port.recordEvent({
+        name: "span.created",
+        severity: "info",
+      });
+      port.recordMetric({
+        name: "span.count",
+        type: "counter",
+        value: 1,
+      });
+      span.setAttribute("status", "active");
+      port.recordEvent({
+        name: "span.attribute.set",
+        severity: "debug",
+      });
+      span.setStatus({ code: "OK" });
+      span.end();
+
+      expect(true).toBe(true); // all calls succeed
+    });
+  });
+
+  describe("error paths", () => {
+    it("recordException handles various error types gracefully", () => {
+      const port = new NoopObservabilityPort();
+      const span = port.startSpan("error.test");
+
+      const testCases = [
+        new Error("standard error"),
+        new TypeError("type error"),
+        new RangeError("range error"),
+        { code: "CUSTOM_ERROR", message: "custom error object" },
+        "string error",
+        null,
+        undefined,
+      ];
+
+      for (const testCase of testCases) {
+        expect(() => span.recordException(testCase)).not.toThrow();
+      }
+
+      span.end();
+    });
+
+    it("setStatus accepts various code strings", () => {
+      const port = new NoopObservabilityPort();
+      const span = port.startSpan("status.test");
+
+      const codes = ["OK", "ERROR", "UNSET", "PENDING"];
+      for (const code of codes) {
+        expect(() => span.setStatus({ code })).not.toThrow();
+        expect(() =>
+          span.setStatus({ code, message: "optional message" })
+        ).not.toThrow();
+      }
+
+      span.end();
+    });
+  });
+
+  describe("attribute value types", () => {
+    it("setAttribute validates AttrValue union", () => {
+      const port = new NoopObservabilityPort();
+      const span = port.startSpan("types.test");
+
+      // All valid AttrValue types
+      span.setAttribute("string", "value");
+      span.setAttribute("number", 123);
+      span.setAttribute("float", 3.14);
+      span.setAttribute("bool", false);
+      span.setAttribute("array_strings", ["a", "b"]);
+      span.setAttribute("array_numbers", [1, 2, 3]);
+
+      expect(true).toBe(true);
+      span.end();
+    });
+  });
+});

package/src/ports/observability.ts

@@ -0,0 +1,150 @@
+/**
+ * ObservabilityPort — cross-cutting telemetry for Vauban Integration Spine.
+ *
+ * Implements S0 §6 (ObservabilityPort, port #14): OpenTelemetry-compatible spans,
+ * structured event logging, metrics, and graceful shutdown. Adapters emit to
+ * Prometheus, Sentry, audit logs, or custom backends.
+ *
+ * Design: structured types only — no hard dependency on @opentelemetry/api.
+ * Real OTel Spans satisfy the structural Span interface.
+ *
+ * Reference: S0 §6 type definition + createTracedBrainPort pattern in brain.ts
+ */
+
+// ─── Attribute value types ────────────────────────────────────────────────────
+
+export type AttrValue = string | number | boolean | (string | number)[];
+
+export interface SpanAttributes {
+  readonly [key: string]: AttrValue;
+}
+
+// ─── Span interface (structural — compatible with OTel Span) ─────────────────
+
+export interface Span {
+  /** Record a key-value attribute on this span. */
+  setAttribute(key: string, value: AttrValue): void;
+
+  /** Record an exception / error on this span. */
+  recordException(error: Error | unknown): void;
+
+  /**
+   * Set the final status of this span.
+   * @param code 'OK', 'ERROR', or other OTel SpanStatusCode equivalent
+   * @param message optional message (used when code is 'ERROR')
+   */
+  setStatus(opts: { code: string; message?: string }): void;
+
+  /** Mark the span as complete. */
+  end(): void;
+}
+
+// ─── Observability event types ────────────────────────────────────────────────
+
+export type EventSeverity = "debug" | "info" | "warn" | "error" | "fatal";
+
+export interface ObservabilityEvent {
+  readonly name: string;
+  readonly severity: EventSeverity;
+  readonly attributes?: Record<string, AttrValue>;
+  readonly timestamp?: number; // unix ms, default = Date.now()
+  readonly traceId?: string; // OTel W3C trace ID
+  readonly spanId?: string; // OTel span ID
+}
+
+// ─── Metric types ────────────────────────────────────────────────────────────
+
+export type MetricType = "gauge" | "counter" | "histogram";
+
+export interface MetricInput {
+  readonly name: string;
+  readonly type: MetricType;
+  readonly value: number;
+  readonly labels?: Record<string, string>;
+  readonly timestamp?: number; // unix ms, default = Date.now()
+}
+
+// ─── ObservabilityPort interface ─────────────────────────────────────────────
+
+export interface ObservabilityPort {
+  /**
+   * Start a new OTel-compatible span.
+   *
+   * @param name span name (e.g., "workflow.execute", "brain.query")
+   * @param attrs optional span attributes
+   * @returns Span handle for setAttribute, recordException, setStatus, end calls
+   */
+  startSpan(name: string, attrs?: SpanAttributes): Span;
+
+  /**
+   * Record a structured observability event (log, audit, compliance event).
+   *
+   * @param event event with name, severity, attributes, optional trace/span IDs
+   */
+  recordEvent(event: ObservabilityEvent): void;
+
+  /**
+   * Record a metric (gauge, counter, histogram).
+   *
+   * @param metric metric name, type, value, optional labels and timestamp
+   */
+  recordMetric(metric: MetricInput): void;
+
+  /**
+   * Graceful shutdown — flush all pending telemetry.
+   * Called at process exit or service shutdown.
+   */
+  flush(): Promise<void>;
+}
+
+// ─── Noop implementation (for tests, fallback, or offline mode) ──────────────
+
+/**
+ * NoopObservabilityPort — no-op implementation for tests or offline mode.
+ * All calls are discarded; span operations succeed silently.
+ */
+export class NoopObservabilityPort implements ObservabilityPort {
+  private readonly noopSpan: Span = {
+    setAttribute: () => {},
+    recordException: () => {},
+    setStatus: () => {},
+    end: () => {},
+  };
+
+  startSpan(_name: string, _attrs?: SpanAttributes): Span {
+    return this.noopSpan;
+  }
+
+  recordEvent(_event: ObservabilityEvent): void {
+    // no-op
+  }
+
+  recordMetric(_metric: MetricInput): void {
+    // no-op
+  }
+
+  async flush(): Promise<void> {
+    // no-op
+  }
+}
+
+// ─── Typed errors ────────────────────────────────────────────────────────────
+
+export class ObservabilityError extends Error {
+  constructor(message: string, public readonly cause?: unknown) {
+    super(message);
+    this.name = "ObservabilityError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class ObservabilityFlushTimeoutError extends Error {
+  constructor(
+    public readonly timeoutMs: number,
+    public readonly cause?: unknown
+  ) {
+    super(`Observability flush timed out after ${timeoutMs}ms`);
+    this.name = "ObservabilityFlushTimeoutError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/ports/outcome.ts

@@ -4,8 +4,17 @@
  * Host attributes a monetary value to each agent run via its
  * domain-specific rules (config/outcomes.yaml in CC). The agent simply
  * calls recordOutcomeAsync after its tracker.finish() — fire-and-forget.
+ *
+ * OTel instrumentation: import { createTracedOutcomePort } to wrap any
+ * OutcomePort implementation with OpenTelemetry spans. Gracefully degrades
+ * to noop spans when no OTel SDK is installed.
  */
 
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+
+const PORT_TRACER = trace.getTracer("vauban-agent-sdk.ports", "0.1.0");
+
 export interface AgentRunRef {
   /** agent_run.id (UUID) produced by AgentRunTracker. */
   id: string;
@@ -17,6 +26,25 @@ export interface AgentRunRef {
   outcome_id?: string | null;
 }
 
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+
+/**
+ * Thrown when the outcome store write fails (DB connection lost, serialization
+ * error, or queue full). Since recordOutcomeAsync is fire-and-forget, this
+ * error is surfaced only when the implementation chooses to throw synchronously
+ * (e.g., during validation or when the write queue is persistently full).
+ */
+export class OutcomeWriteError extends Error {
+  readonly runId: string;
+
+  constructor(message: string, runId: string, public readonly cause?: unknown) {
+    super(message);
+    this.name = "OutcomeWriteError";
+    this.runId = runId;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
 export interface OutcomePort {
   /**
    * Enqueue outcome attribution. Fire-and-forget: never throws,
@@ -24,3 +52,44 @@ export interface OutcomePort {
    */
   recordOutcomeAsync(run: AgentRunRef): void;
 }
+
+/**
+ * Wrap any OutcomePort implementation with OTel spans.
+ * The span captures the run id and agent_id as attributes.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
+ *
+ * Usage:
+ *   const raw: OutcomePort = buildPostgresOutcome(...);
+ *   const traced = createTracedOutcomePort(raw);
+ *   traced.recordOutcomeAsync({...}) // emits "outcome.recordOutcomeAsync" span
+ */
+export function createTracedOutcomePort(impl: OutcomePort): OutcomePort {
+  return {
+    recordOutcomeAsync(run: AgentRunRef): void {
+      PORT_TRACER.startActiveSpan(
+        "outcome.recordOutcomeAsync",
+        {
+          attributes: {
+            "outcome.run_id": run.id,
+            "outcome.agent_id": run.agent_id,
+            "vauban.port.name": "outcome",
+          },
+        },
+        (span: Span) => {
+          try {
+            impl.recordOutcomeAsync(run);
+            span.setStatus({ code: SpanStatusCode.OK });
+          } catch (err) {
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: err instanceof Error ? err.message : String(err),
+            });
+            span.recordException(err as Error);
+          } finally {
+            span.end();
+          }
+        }
+      );
+    },
+  };
+}