@springbrand/agent-runtime 0.2.0-alpha.15 → 0.2.0-alpha.17

package/src/telemetry/contract.ts

@@ -0,0 +1,389 @@
+/** JSON values accepted by the vendor-neutral telemetry contract. */
+export type TelemetryValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly TelemetryValue[]
+  | { readonly [key: string]: TelemetryValue };
+
+export type TelemetryAttributes = Readonly<Record<string, TelemetryValue>>;
+
+export type TelemetryPrivacyMode = "metadata" | "content";
+
+/** Identity attached to every event before it crosses the Runtime boundary. */
+export interface UniversalTelemetryResource {
+  readonly serviceName: string;
+  readonly serviceVersion?: string;
+  readonly environment?: string;
+  readonly agentName: string;
+  readonly agentId: string;
+  readonly sessionId: string;
+  readonly attributes?: TelemetryAttributes;
+}
+
+export const UNIVERSAL_TELEMETRY_EVENT_TYPES = [
+  "turn.admitted",
+  "turn.started",
+  "turn.steered",
+  "turn.recovering",
+  "turn.cancelled",
+  "turn.finished",
+  "generation.started",
+  "generation.finished",
+  "tool.started",
+  "tool.finished",
+  "approval.requested",
+  "approval.decided",
+  "interaction.requested",
+  "interaction.responded",
+  "interaction.cancelled",
+  "subagent.started",
+  "subagent.finished",
+  "context.compacted",
+] as const;
+
+export type UniversalTelemetryEventType =
+  typeof UNIVERSAL_TELEMETRY_EVENT_TYPES[number];
+
+interface PayloadBase {
+  readonly attributes?: TelemetryAttributes;
+}
+
+export interface TelemetryPayloadByType {
+  readonly "turn.admitted": PayloadBase & {
+    readonly requestId: string;
+    readonly idempotencyKey?: string;
+  };
+  readonly "turn.started": PayloadBase & {
+    readonly assemblyRevision?: string;
+    readonly input?: TelemetryValue;
+  };
+  readonly "turn.steered": PayloadBase & {
+    readonly steerId: string;
+    readonly messageId?: string;
+    readonly content?: TelemetryValue;
+  };
+  readonly "turn.recovering": PayloadBase & {
+    readonly reason: string;
+    readonly attempt: number;
+    readonly error?: string;
+  };
+  readonly "turn.cancelled": PayloadBase & {
+    readonly reason?: string;
+  };
+  readonly "turn.finished": PayloadBase & {
+    readonly outcome: "completed" | "failed" | "cancelled";
+    readonly durationMs?: number;
+    readonly output?: TelemetryValue;
+    readonly error?: string;
+  };
+  readonly "generation.started": PayloadBase & {
+    readonly generationId: string;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly input?: TelemetryValue;
+  };
+  readonly "generation.finished": PayloadBase & {
+    readonly generationId: string;
+    readonly outcome: "completed" | "failed" | "cancelled";
+    readonly durationMs?: number;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly totalTokens?: number;
+    readonly cost?: number;
+    readonly output?: TelemetryValue;
+    readonly error?: string;
+  };
+  readonly "tool.started": PayloadBase & {
+    readonly toolName: string;
+    readonly input?: TelemetryValue;
+  };
+  readonly "tool.finished": PayloadBase & {
+    readonly toolName: string;
+    readonly outcome: "completed" | "failed" | "cancelled";
+    readonly durationMs?: number;
+    readonly outputBytes?: number;
+    readonly spilled?: boolean;
+    readonly output?: TelemetryValue;
+    readonly error?: string;
+  };
+  readonly "approval.requested": PayloadBase & {
+    readonly executionId: string;
+    readonly toolName: string;
+    readonly summary?: string;
+    readonly input?: TelemetryValue;
+  };
+  readonly "approval.decided": PayloadBase & {
+    readonly executionId: string;
+    readonly decision: "approved" | "rejected" | "cancelled";
+    readonly reason?: string;
+  };
+  readonly "interaction.requested": PayloadBase & {
+    readonly interactionId: string;
+    readonly toolName: string;
+    readonly input?: TelemetryValue;
+  };
+  readonly "interaction.responded": PayloadBase & {
+    readonly interactionId: string;
+    readonly response?: TelemetryValue;
+  };
+  readonly "interaction.cancelled": PayloadBase & {
+    readonly interactionId: string;
+    readonly reason?: string;
+  };
+  readonly "subagent.started": PayloadBase & {
+    readonly subagentId: string;
+    readonly agentType?: string;
+    readonly prompt?: TelemetryValue;
+  };
+  readonly "subagent.finished": PayloadBase & {
+    readonly subagentId: string;
+    readonly outcome: "completed" | "failed" | "cancelled";
+    readonly durationMs?: number;
+    readonly output?: TelemetryValue;
+    readonly error?: string;
+  };
+  readonly "context.compacted": PayloadBase & {
+    readonly compactionId: string;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly removedMessages?: number;
+    readonly summary?: TelemetryValue;
+  };
+}
+
+export type UniversalTelemetryEvent<
+  T extends UniversalTelemetryEventType = UniversalTelemetryEventType,
+> = T extends UniversalTelemetryEventType ? {
+    readonly schemaVersion: 1;
+    readonly type: T;
+    readonly eventId: string;
+    readonly operationId: string;
+    readonly parentOperationId?: string;
+    readonly submissionId?: string;
+    readonly toolCallId?: string;
+    readonly occurredAt: number;
+    readonly resource: UniversalTelemetryResource;
+    readonly payload: TelemetryPayloadByType[T];
+  }
+  : never;
+
+export type NewUniversalTelemetryEvent<
+  T extends UniversalTelemetryEventType,
+> = Omit<UniversalTelemetryEvent<T>, "schemaVersion">;
+
+/** The only delivery boundary owned by Universal Agent. */
+export interface AgentTelemetryPort {
+  publish(events: readonly UniversalTelemetryEvent[]): Promise<void>;
+}
+
+/** Fully resolved telemetry choice carried by an assembled Runtime candidate. */
+export interface AgentTelemetryBinding {
+  readonly port: AgentTelemetryPort;
+  readonly resource: UniversalTelemetryResource;
+  readonly mode: TelemetryPrivacyMode;
+}
+
+const EVENT_TYPE_SET = new Set<string>(UNIVERSAL_TELEMETRY_EVENT_TYPES);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireNonEmptyString(
+  value: unknown,
+  field: string,
+): asserts value is string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`Telemetry ${field} must be a non-empty string`);
+  }
+}
+
+function requireFiniteNumber(value: unknown, field: string): void {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new TypeError(`Telemetry ${field} must be a finite number`);
+  }
+}
+
+function requireOneOf(
+  value: unknown,
+  allowed: readonly string[],
+  field: string,
+): void {
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    throw new TypeError(
+      `Telemetry ${field} must be one of: ${allowed.join(", ")}`,
+    );
+  }
+}
+
+function assertPayload(
+  type: UniversalTelemetryEventType,
+  payload: Record<string, unknown>,
+): void {
+  switch (type) {
+    case "turn.admitted":
+      requireNonEmptyString(payload.requestId, "payload.requestId");
+      break;
+    case "turn.steered":
+      requireNonEmptyString(payload.steerId, "payload.steerId");
+      break;
+    case "turn.recovering":
+      requireNonEmptyString(payload.reason, "payload.reason");
+      requireFiniteNumber(payload.attempt, "payload.attempt");
+      break;
+    case "turn.finished":
+    case "generation.finished":
+    case "tool.finished":
+    case "subagent.finished":
+      requireOneOf(
+        payload.outcome,
+        ["completed", "failed", "cancelled"],
+        "payload.outcome",
+      );
+      if (type === "generation.finished") {
+        requireNonEmptyString(payload.generationId, "payload.generationId");
+      } else if (type === "tool.finished") {
+        requireNonEmptyString(payload.toolName, "payload.toolName");
+      } else if (type === "subagent.finished") {
+        requireNonEmptyString(payload.subagentId, "payload.subagentId");
+      }
+      break;
+    case "generation.started":
+      requireNonEmptyString(payload.generationId, "payload.generationId");
+      break;
+    case "tool.started":
+      requireNonEmptyString(payload.toolName, "payload.toolName");
+      break;
+    case "approval.requested":
+      requireNonEmptyString(payload.executionId, "payload.executionId");
+      requireNonEmptyString(payload.toolName, "payload.toolName");
+      break;
+    case "approval.decided":
+      requireNonEmptyString(payload.executionId, "payload.executionId");
+      requireOneOf(
+        payload.decision,
+        ["approved", "rejected", "cancelled"],
+        "payload.decision",
+      );
+      break;
+    case "interaction.requested":
+      requireNonEmptyString(payload.interactionId, "payload.interactionId");
+      requireNonEmptyString(payload.toolName, "payload.toolName");
+      break;
+    case "interaction.responded":
+    case "interaction.cancelled":
+      requireNonEmptyString(payload.interactionId, "payload.interactionId");
+      break;
+    case "subagent.started":
+      requireNonEmptyString(payload.subagentId, "payload.subagentId");
+      break;
+    case "context.compacted":
+      requireNonEmptyString(payload.compactionId, "payload.compactionId");
+      break;
+    case "turn.started":
+    case "turn.cancelled":
+      break;
+  }
+  for (const field of [
+    "durationMs",
+    "inputTokens",
+    "outputTokens",
+    "totalTokens",
+    "cost",
+    "outputBytes",
+    "removedMessages",
+  ]) {
+    const value = payload[field];
+    if (value !== undefined) {
+      requireFiniteNumber(value, `payload.${field}`);
+      if ((value as number) < 0) {
+        throw new TypeError(`Telemetry payload.${field} cannot be negative`);
+      }
+    }
+  }
+}
+
+function assertTelemetryResource(
+  value: unknown,
+): asserts value is UniversalTelemetryResource {
+  if (!isRecord(value)) {
+    throw new TypeError("Telemetry resource must be an object");
+  }
+  for (const field of ["serviceName", "agentName", "agentId", "sessionId"] as const) {
+    requireNonEmptyString(value[field], `resource.${field}`);
+  }
+}
+
+/** Fail closed before malformed data is persisted or handed to a consumer. */
+export function assertUniversalTelemetryEvent(
+  value: unknown,
+): asserts value is UniversalTelemetryEvent {
+  if (!isRecord(value)) throw new TypeError("Telemetry event must be an object");
+  if (value.schemaVersion !== 1) {
+    throw new TypeError("Telemetry schemaVersion must be 1");
+  }
+  if (typeof value.type !== "string" || !EVENT_TYPE_SET.has(value.type)) {
+    throw new TypeError(`Unknown telemetry event type: ${String(value.type)}`);
+  }
+  requireNonEmptyString(value.eventId, "eventId");
+  requireNonEmptyString(value.operationId, "operationId");
+  if (value.parentOperationId !== undefined) {
+    requireNonEmptyString(value.parentOperationId, "parentOperationId");
+  }
+  if (value.submissionId !== undefined) {
+    requireNonEmptyString(value.submissionId, "submissionId");
+  }
+  if (value.toolCallId !== undefined) {
+    requireNonEmptyString(value.toolCallId, "toolCallId");
+  }
+  if (typeof value.occurredAt !== "number" || !Number.isFinite(value.occurredAt)) {
+    throw new TypeError("Telemetry occurredAt must be a finite number");
+  }
+  assertTelemetryResource(value.resource);
+  if (!isRecord(value.payload)) {
+    throw new TypeError("Telemetry payload must be an object");
+  }
+  assertPayload(value.type as UniversalTelemetryEventType, value.payload);
+}
+
+export function assertAgentTelemetryBinding(
+  value: unknown,
+): asserts value is AgentTelemetryBinding {
+  if (!isRecord(value)) throw new TypeError("Telemetry binding must be an object");
+  assertTelemetryResource(value.resource);
+  if (value.mode !== "metadata" && value.mode !== "content") {
+    throw new TypeError("Telemetry mode must be metadata or content");
+  }
+  if (!isRecord(value.port) || typeof value.port.publish !== "function") {
+    throw new TypeError("Telemetry port must implement publish(events)");
+  }
+}
+
+/** Validate and detach mutable resource input at the assembly boundary. */
+export function normalizeAgentTelemetryBinding(
+  binding: AgentTelemetryBinding,
+): AgentTelemetryBinding {
+  assertAgentTelemetryBinding(binding);
+  const attributes = binding.resource.attributes === undefined
+    ? undefined
+    : Object.freeze({ ...binding.resource.attributes });
+  const resource = Object.freeze({
+    ...binding.resource,
+    ...(attributes === undefined ? {} : { attributes }),
+  });
+  return Object.freeze({
+    port: binding.port,
+    resource,
+    mode: binding.mode,
+  });
+}
+
+export function createUniversalTelemetryEvent<
+  T extends UniversalTelemetryEventType,
+>(input: NewUniversalTelemetryEvent<T>): UniversalTelemetryEvent<T> {
+  const event = { ...input, schemaVersion: 1 } as UniversalTelemetryEvent<T>;
+  assertUniversalTelemetryEvent(event);
+  return event;
+}

package/src/telemetry/coordinator.ts

@@ -0,0 +1,143 @@
+import type { TelemetryDeliveryOutbox } from "./delivery";
+import { TELEMETRY_RETRY_DELAY_MS, TelemetryDelivery } from "./delivery";
+import type { TelemetryOutboxWriter } from "./recorder";
+import { TelemetryRecorder } from "./recorder";
+import { RuntimeTelemetry } from "./runtime-telemetry";
+import type { AgentTelemetryBinding } from "./contract";
+
+const TELEMETRY_COLD_BUFFER_LIMIT = 1_000;
+
+type RuntimeTelemetryMethod = {
+  [Name in keyof RuntimeTelemetry]: RuntimeTelemetry[Name] extends
+    (input: infer _Input) => unknown ? Name : never;
+}[keyof RuntimeTelemetry];
+
+type RuntimeTelemetryInput<Name extends RuntimeTelemetryMethod> =
+  RuntimeTelemetry[Name] extends (input: infer Input) => unknown ? Input : never;
+
+type RuntimeTelemetryOutbox = TelemetryDeliveryOutbox & TelemetryOutboxWriter;
+
+interface BufferedTelemetryFact {
+  readonly method: RuntimeTelemetryMethod;
+  readonly input: unknown;
+}
+
+export interface RuntimeTelemetryCoordinatorOptions {
+  readonly outbox: () => RuntimeTelemetryOutbox | undefined;
+  readonly waitUntil: (promise: Promise<void>) => void;
+  readonly scheduleRetry: (
+    delaySeconds: number,
+    idempotent: boolean,
+  ) => Promise<void>;
+  readonly onError?: (error: unknown) => void;
+}
+
+function detached<T>(input: T): T {
+  try {
+    return structuredClone(input);
+  } catch {
+    return input;
+  }
+}
+
+/**
+ * Owns Runtime telemetry activation, pre-activation buffering and delivery.
+ *
+ * Fact owners only call {@link capture}; consumer absence, retries and failures
+ * remain invisible to authoritative Runtime state transitions.
+ */
+export class RuntimeTelemetryCoordinator {
+  private runtime?: RuntimeTelemetry;
+  private delivery?: TelemetryDelivery;
+  private configured = false;
+  private draining?: Promise<void>;
+  private readonly coldBuffer: BufferedTelemetryFact[] = [];
+
+  constructor(
+    private readonly options: RuntimeTelemetryCoordinatorOptions,
+  ) {}
+
+  configure(binding?: AgentTelemetryBinding): void {
+    if (this.configured) return;
+    this.configured = true;
+    if (!binding) {
+      this.coldBuffer.length = 0;
+      return;
+    }
+    const outbox = this.options.outbox();
+    if (!outbox) {
+      this.coldBuffer.length = 0;
+      this.options.onError?.(new Error("Telemetry outbox is unavailable"));
+      return;
+    }
+    this.runtime = new RuntimeTelemetry(
+      binding.resource,
+      new TelemetryRecorder(outbox, binding.mode),
+    );
+    this.delivery = new TelemetryDelivery(outbox, binding.port);
+    for (const fact of this.coldBuffer.splice(0)) this.deliver(fact);
+    if (outbox.hasPending()) this.queueDrain();
+  }
+
+  capture<Name extends RuntimeTelemetryMethod>(
+    method: Name,
+    input: RuntimeTelemetryInput<Name>,
+  ): void {
+    if (this.runtime) {
+      this.deliver({ method, input });
+      this.queueDrain();
+      return;
+    }
+    if (!this.configured && this.coldBuffer.length < TELEMETRY_COLD_BUFFER_LIMIT) {
+      this.coldBuffer.push({ method, input: detached(input) });
+    }
+  }
+
+  recover(ensureReady: () => Promise<void>): void {
+    if (!this.options.outbox()?.hasPending()) return;
+    this.options.waitUntil(
+      ensureReady().then(() => this.drain()),
+    );
+  }
+
+  async drainScheduled(): Promise<void> {
+    await this.drain(false);
+  }
+
+  private deliver(fact: BufferedTelemetryFact): void {
+    if (!this.runtime) return;
+    try {
+      const invoke = this.runtime[fact.method] as unknown as (
+        input: unknown,
+      ) => unknown;
+      invoke.call(this.runtime, fact.input);
+    } catch (error) {
+      this.options.onError?.(error);
+    }
+  }
+
+  private queueDrain(): void {
+    if (!this.delivery || this.draining) return;
+    const pending = this.drain();
+    let tracked: Promise<void>;
+    tracked = pending.finally(() => {
+      if (this.draining === tracked) this.draining = undefined;
+    });
+    this.draining = tracked;
+    this.options.waitUntil(tracked);
+  }
+
+  private async drain(idempotentRetry = true): Promise<void> {
+    if (!this.delivery) return;
+    try {
+      const result = await this.delivery.drain();
+      if (!result.hasPending) return;
+      await this.options.scheduleRetry(
+        TELEMETRY_RETRY_DELAY_MS / 1_000,
+        idempotentRetry,
+      );
+    } catch (error) {
+      this.options.onError?.(error);
+    }
+  }
+}

package/src/telemetry/delivery.ts

@@ -0,0 +1,138 @@
+import type {
+  StoredTelemetryOutboxEvent,
+} from "../db/telemetry-outbox.repo";
+import {
+  TELEMETRY_OUTBOX_BATCH_SIZE,
+} from "../db/telemetry-outbox.repo";
+import {
+  assertUniversalTelemetryEvent,
+  type AgentTelemetryPort,
+  type UniversalTelemetryEvent,
+} from "./contract";
+
+export const TELEMETRY_BATCH_FAILURE_LIMIT = 5;
+export const TELEMETRY_DELIVERED_RETENTION_MS = 7 * 24 * 60 * 60 * 1_000;
+export const TELEMETRY_RETRY_DELAY_MS = 10_000;
+
+export interface TelemetryDeliveryOutbox {
+  listPending(limit?: number): StoredTelemetryOutboxEvent[];
+  markDelivered(eventIds: readonly string[], deliveredAt: number): void;
+  markFailed(eventIds: readonly string[], error: string): void;
+  quarantine(eventId: string, quarantinedAt: number, error: string): void;
+  deleteDeliveredBefore(cutoff: number): void;
+  hasPending(): boolean;
+}
+
+export interface TelemetryDeliveryResult {
+  readonly selected: number;
+  readonly delivered: number;
+  readonly quarantined: number;
+  readonly failed: number;
+  readonly hasPending: boolean;
+  readonly retryAfterMs: number | null;
+}
+
+function errorText(error: unknown): string {
+  const value = error instanceof Error ? error.message : String(error);
+  return value.length <= 1_000 ? value : `${value.slice(0, 1_000)}…`;
+}
+
+function parse(row: StoredTelemetryOutboxEvent): UniversalTelemetryEvent {
+  const event: unknown = JSON.parse(row.body);
+  assertUniversalTelemetryEvent(event);
+  if (event.eventId !== row.eventId) {
+    throw new Error(
+      `Telemetry outbox identity mismatch: ${row.eventId} != ${event.eventId}`,
+    );
+  }
+  return event;
+}
+
+/**
+ * Delivers one bounded batch. Ack happens only after publish resolves, so a
+ * crash between the remote write and local ack intentionally causes replay.
+ */
+export class TelemetryDelivery {
+  constructor(
+    private readonly outbox: TelemetryDeliveryOutbox,
+    private readonly port: AgentTelemetryPort,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  async drain(): Promise<TelemetryDeliveryResult> {
+    const now = this.now();
+    this.outbox.deleteDeliveredBefore(now - TELEMETRY_DELIVERED_RETENTION_MS);
+    const rows = this.outbox.listPending(TELEMETRY_OUTBOX_BATCH_SIZE);
+    let quarantined = 0;
+    const valid: Array<{
+      row: StoredTelemetryOutboxEvent;
+      event: UniversalTelemetryEvent;
+    }> = [];
+
+    for (const row of rows) {
+      try {
+        valid.push({ row, event: parse(row) });
+      } catch (error) {
+        this.outbox.quarantine(row.eventId, now, errorText(error));
+        quarantined += 1;
+      }
+    }
+
+    if (valid.length === 0) {
+      return this.result(rows.length, 0, quarantined, 0);
+    }
+
+    try {
+      await this.port.publish(valid.map(({ event }) => event));
+      this.outbox.markDelivered(valid.map(({ row }) => row.eventId), now);
+      return this.result(rows.length, valid.length, quarantined, 0);
+    } catch (error) {
+      const failure = errorText(error);
+      const ids = valid.map(({ row }) => row.eventId);
+      this.outbox.markFailed(ids, failure);
+      const shouldIsolate = valid.some(
+        ({ row }) => row.attemptCount + 1 >= TELEMETRY_BATCH_FAILURE_LIMIT,
+      );
+      if (!shouldIsolate) {
+        return this.result(rows.length, 0, quarantined, valid.length);
+      }
+    }
+
+    let delivered = 0;
+    let isolatedFailures = 0;
+    for (const { row, event } of valid) {
+      try {
+        await this.port.publish([event]);
+        this.outbox.markDelivered([row.eventId], now);
+        delivered += 1;
+      } catch (error) {
+        this.outbox.quarantine(row.eventId, now, errorText(error));
+        quarantined += 1;
+        isolatedFailures += 1;
+      }
+    }
+    return this.result(
+      rows.length,
+      delivered,
+      quarantined,
+      isolatedFailures,
+    );
+  }
+
+  private result(
+    selected: number,
+    delivered: number,
+    quarantined: number,
+    failed: number,
+  ): TelemetryDeliveryResult {
+    const hasPending = this.outbox.hasPending();
+    return {
+      selected,
+      delivered,
+      quarantined,
+      failed,
+      hasPending,
+      retryAfterMs: hasPending ? TELEMETRY_RETRY_DELAY_MS : null,
+    };
+  }
+}