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

package/src/telemetry/ids.ts

@@ -0,0 +1,60 @@
+import type { UniversalTelemetryEventType } from "./contract";
+
+export type TelemetryOperationKind =
+  | "turn"
+  | "generation"
+  | "tool"
+  | "approval"
+  | "interaction"
+  | "subagent"
+  | "compaction";
+
+function segment(value: string): string {
+  if (value.length === 0) throw new TypeError("Telemetry ID parts cannot be empty");
+  return `${value.length}:${value}`;
+}
+
+/** Length-prefixed parts make the deterministic identity unambiguous. */
+export function telemetryOperationId(
+  kind: TelemetryOperationKind,
+  ...identity: readonly string[]
+): string {
+  if (identity.length === 0) {
+    throw new TypeError("Telemetry operation identity cannot be empty");
+  }
+  return `ua:op:${kind}:${identity.map(segment).join("")}`;
+}
+
+/**
+ * Stable identity for a fact. `occurrenceId` is required by callers when the
+ * same operation may emit a type more than once (for example recovery/steer).
+ */
+export function telemetryEventId(
+  operationId: string,
+  type: UniversalTelemetryEventType,
+  occurrenceId?: string,
+): string {
+  if (operationId.length === 0) {
+    throw new TypeError("Telemetry operationId cannot be empty");
+  }
+  return `ua:event:${segment(operationId)}${segment(type)}${
+    occurrenceId === undefined ? "" : segment(occurrenceId)
+  }`;
+}
+
+export const telemetryOperations = {
+  turn: (sessionId: string, submissionId: string) =>
+    telemetryOperationId("turn", sessionId, submissionId),
+  generation: (submissionId: string, generationId: string) =>
+    telemetryOperationId("generation", submissionId, generationId),
+  tool: (submissionId: string, toolCallId: string) =>
+    telemetryOperationId("tool", submissionId, toolCallId),
+  approval: (submissionId: string, executionId: string) =>
+    telemetryOperationId("approval", submissionId, executionId),
+  interaction: (submissionId: string, interactionId: string) =>
+    telemetryOperationId("interaction", submissionId, interactionId),
+  subagent: (submissionId: string, subagentId: string) =>
+    telemetryOperationId("subagent", submissionId, subagentId),
+  compaction: (sessionId: string, compactionId: string) =>
+    telemetryOperationId("compaction", sessionId, compactionId),
+} as const;

package/src/telemetry/index.ts

@@ -0,0 +1,7 @@
+export * from "./contract";
+export * from "./coordinator";
+export * from "./delivery";
+export * from "./ids";
+export * from "./recorder";
+export * from "./runtime-telemetry";
+export * from "./sanitize";

package/src/telemetry/recorder.ts

@@ -0,0 +1,61 @@
+import type {
+  NewTelemetryOutboxEvent,
+  TelemetryOutboxInsertResult,
+} from "../db/telemetry-outbox.repo";
+import {
+  assertUniversalTelemetryEvent,
+  type TelemetryPrivacyMode,
+  type UniversalTelemetryEvent,
+} from "./contract";
+import {
+  sanitizeTelemetryEvent,
+} from "./sanitize";
+
+export type TelemetryRecordResult =
+  | { readonly status: "recorded" | "duplicate" }
+  | {
+    readonly status: "dropped";
+    readonly reason: "capacity" | "invalid" | "conflict";
+    readonly error?: string;
+  };
+
+export interface TelemetryOutboxWriter {
+  insert(event: NewTelemetryOutboxEvent): TelemetryOutboxInsertResult;
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Validate, sanitize and durably enqueue without changing Agent outcomes. */
+export class TelemetryRecorder {
+  constructor(
+    private readonly outbox: TelemetryOutboxWriter,
+    private readonly privacyMode: TelemetryPrivacyMode,
+  ) {}
+
+  record(event: UniversalTelemetryEvent): TelemetryRecordResult {
+    try {
+      assertUniversalTelemetryEvent(event);
+      const sanitized = sanitizeTelemetryEvent(event, this.privacyMode);
+      const result = this.outbox.insert({
+        eventId: sanitized.eventId,
+        body: JSON.stringify(sanitized),
+        createdAt: sanitized.occurredAt,
+      });
+      if (result === "full") {
+        return { status: "dropped", reason: "capacity" };
+      }
+      return { status: result === "inserted" ? "recorded" : "duplicate" };
+    } catch (error) {
+      const message = errorText(error);
+      return {
+        status: "dropped",
+        reason: message.startsWith("Conflicting telemetry event:")
+          ? "conflict"
+          : "invalid",
+        error: message,
+      };
+    }
+  }
+}

package/src/telemetry/runtime-telemetry.ts

@@ -0,0 +1,484 @@
+import type { TelemetryRecordResult, TelemetryRecorder } from "./recorder";
+import {
+  createUniversalTelemetryEvent,
+  type TelemetryPayloadByType,
+  type UniversalTelemetryEventType,
+  type UniversalTelemetryResource,
+} from "./contract";
+import { telemetryEventId, telemetryOperations } from "./ids";
+
+type EventOptions = Readonly<{
+  submissionId?: string;
+  toolCallId?: string;
+  parentOperationId?: string;
+  occurredAt?: number;
+  occurrenceId?: string;
+}>;
+
+/** Typed fact facade used by Runtime callsites. */
+export class RuntimeTelemetry {
+  constructor(
+    private readonly resource: UniversalTelemetryResource,
+    private readonly recorder: TelemetryRecorder,
+  ) {}
+
+  private record<T extends UniversalTelemetryEventType>(
+    type: T,
+    operationId: string,
+    payload: TelemetryPayloadByType[T],
+    options: EventOptions = {},
+  ): TelemetryRecordResult {
+    try {
+      return this.recorder.record(createUniversalTelemetryEvent({
+        type,
+        eventId: telemetryEventId(operationId, type, options.occurrenceId),
+        operationId,
+        ...(options.parentOperationId
+          ? { parentOperationId: options.parentOperationId }
+          : {}),
+        ...(options.submissionId
+          ? { submissionId: options.submissionId }
+          : {}),
+        ...(options.toolCallId ? { toolCallId: options.toolCallId } : {}),
+        occurredAt: options.occurredAt ?? Date.now(),
+        resource: this.resource,
+        payload,
+      }));
+    } catch (error) {
+      return {
+        status: "dropped",
+        reason: "invalid",
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  turnAdmitted(input: Readonly<{
+    submissionId: string;
+    requestId: string;
+    idempotencyKey?: string;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.turn(
+      this.resource.sessionId,
+      input.submissionId,
+    );
+    return this.record("turn.admitted", operationId, {
+      requestId: input.requestId,
+      ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+    }, input);
+  }
+
+  turnStarted(input: Readonly<{
+    submissionId: string;
+    assemblyRevision?: string;
+    input?: unknown;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.turn(
+      this.resource.sessionId,
+      input.submissionId,
+    );
+    return this.record("turn.started", operationId, {
+      ...(input.assemblyRevision
+        ? { assemblyRevision: input.assemblyRevision }
+        : {}),
+      ...(input.input === undefined ? {} : { input: input.input as never }),
+    }, input);
+  }
+
+  turnSteered(input: Readonly<{
+    submissionId: string;
+    steerId: string;
+    messageId?: string;
+    content?: unknown;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.turn(
+      this.resource.sessionId,
+      input.submissionId,
+    );
+    return this.record("turn.steered", operationId, {
+      steerId: input.steerId,
+      ...(input.messageId ? { messageId: input.messageId } : {}),
+      ...(input.content === undefined ? {} : { content: input.content as never }),
+    }, { ...input, occurrenceId: input.steerId });
+  }
+
+  turnRecovering(input: Readonly<{
+    submissionId: string;
+    reason: string;
+    attempt: number;
+    error?: string;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.turn(
+      this.resource.sessionId,
+      input.submissionId,
+    );
+    return this.record("turn.recovering", operationId, {
+      reason: input.reason,
+      attempt: input.attempt,
+      ...(input.error ? { error: input.error } : {}),
+    }, { ...input, occurrenceId: `${input.attempt}:${input.reason}` });
+  }
+
+  turnCancelled(input: Readonly<{
+    submissionId: string;
+    reason?: string;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.turn(
+      this.resource.sessionId,
+      input.submissionId,
+    );
+    return this.record("turn.cancelled", operationId, {
+      ...(input.reason ? { reason: input.reason } : {}),
+    }, input);
+  }
+
+  turnFinished(input: Readonly<{
+    submissionId: string;
+    outcome: "completed" | "failed" | "cancelled";
+    durationMs?: number;
+    output?: unknown;
+    error?: string;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.turn(
+      this.resource.sessionId,
+      input.submissionId,
+    );
+    return this.record("turn.finished", operationId, {
+      outcome: input.outcome,
+      ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+      ...(input.output === undefined ? {} : { output: input.output as never }),
+      ...(input.error ? { error: input.error } : {}),
+    }, input);
+  }
+
+  generationStarted(input: Readonly<{
+    submissionId: string;
+    generationId: string;
+    provider?: string;
+    model?: string;
+    input?: unknown;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.generation(
+      input.submissionId,
+      input.generationId,
+    );
+    return this.record("generation.started", operationId, {
+      generationId: input.generationId,
+      ...(input.provider ? { provider: input.provider } : {}),
+      ...(input.model ? { model: input.model } : {}),
+      ...(input.input === undefined ? {} : { input: input.input as never }),
+    }, {
+      ...input,
+      parentOperationId: telemetryOperations.turn(
+        this.resource.sessionId,
+        input.submissionId,
+      ),
+    });
+  }
+
+  generationFinished(input: Readonly<{
+    submissionId: string;
+    generationId: string;
+    outcome: "completed" | "failed" | "cancelled";
+    durationMs?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    cost?: number;
+    output?: unknown;
+    error?: string;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.generation(
+      input.submissionId,
+      input.generationId,
+    );
+    return this.record("generation.finished", operationId, {
+      generationId: input.generationId,
+      outcome: input.outcome,
+      ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+      ...(input.inputTokens === undefined ? {} : { inputTokens: input.inputTokens }),
+      ...(input.outputTokens === undefined ? {} : { outputTokens: input.outputTokens }),
+      ...(input.totalTokens === undefined ? {} : { totalTokens: input.totalTokens }),
+      ...(input.cost === undefined ? {} : { cost: input.cost }),
+      ...(input.output === undefined ? {} : { output: input.output as never }),
+      ...(input.error ? { error: input.error } : {}),
+    }, {
+      ...input,
+      parentOperationId: telemetryOperations.turn(
+        this.resource.sessionId,
+        input.submissionId,
+      ),
+    });
+  }
+
+  toolStarted(input: Readonly<{
+    submissionId: string;
+    toolCallId: string;
+    toolName: string;
+    input?: unknown;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.tool(
+      input.submissionId,
+      input.toolCallId,
+    );
+    return this.record("tool.started", operationId, {
+      toolName: input.toolName,
+      ...(input.input === undefined ? {} : { input: input.input as never }),
+    }, {
+      ...input,
+      parentOperationId: telemetryOperations.turn(
+        this.resource.sessionId,
+        input.submissionId,
+      ),
+    });
+  }
+
+  toolFinished(input: Readonly<{
+    submissionId: string;
+    toolCallId: string;
+    toolName: string;
+    outcome: "completed" | "failed" | "cancelled";
+    durationMs?: number;
+    outputBytes?: number;
+    spilled?: boolean;
+    output?: unknown;
+    error?: string;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.tool(
+      input.submissionId,
+      input.toolCallId,
+    );
+    return this.record("tool.finished", operationId, {
+      toolName: input.toolName,
+      outcome: input.outcome,
+      ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+      ...(input.outputBytes === undefined ? {} : { outputBytes: input.outputBytes }),
+      ...(input.spilled === undefined ? {} : { spilled: input.spilled }),
+      ...(input.output === undefined ? {} : { output: input.output as never }),
+      ...(input.error ? { error: input.error } : {}),
+    }, {
+      ...input,
+      parentOperationId: telemetryOperations.turn(
+        this.resource.sessionId,
+        input.submissionId,
+      ),
+    });
+  }
+
+  approvalRequested(input: Readonly<{
+    submissionId: string;
+    toolCallId: string;
+    executionId: string;
+    toolName: string;
+    summary?: string;
+    input?: unknown;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.approval(
+      input.submissionId,
+      input.executionId,
+    );
+    return this.record("approval.requested", operationId, {
+      executionId: input.executionId,
+      toolName: input.toolName,
+      ...(input.summary ? { summary: input.summary } : {}),
+      ...(input.input === undefined ? {} : { input: input.input as never }),
+    }, {
+      ...input,
+      parentOperationId: telemetryOperations.tool(
+        input.submissionId,
+        input.toolCallId,
+      ),
+    });
+  }
+
+  approvalDecided(input: Readonly<{
+    submissionId: string;
+    toolCallId: string;
+    executionId: string;
+    decision: "approved" | "rejected" | "cancelled";
+    reason?: string;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.approval(
+      input.submissionId,
+      input.executionId,
+    );
+    return this.record("approval.decided", operationId, {
+      executionId: input.executionId,
+      decision: input.decision,
+      ...(input.reason ? { reason: input.reason } : {}),
+    }, {
+      ...input,
+      parentOperationId: telemetryOperations.tool(
+        input.submissionId,
+        input.toolCallId,
+      ),
+    });
+  }
+
+  interactionRequested(input: Readonly<{
+    submissionId: string;
+    toolCallId: string;
+    interactionId: string;
+    toolName: string;
+    input?: unknown;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.interaction(
+      input.submissionId,
+      input.interactionId,
+    );
+    return this.record("interaction.requested", operationId, {
+      interactionId: input.interactionId,
+      toolName: input.toolName,
+      ...(input.input === undefined ? {} : { input: input.input as never }),
+    }, {
+      ...input,
+      parentOperationId: telemetryOperations.tool(
+        input.submissionId,
+        input.toolCallId,
+      ),
+    });
+  }
+
+  interactionResponded(input: Readonly<{
+    submissionId: string;
+    toolCallId: string;
+    interactionId: string;
+    response?: unknown;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.interaction(
+      input.submissionId,
+      input.interactionId,
+    );
+    return this.record("interaction.responded", operationId, {
+      interactionId: input.interactionId,
+      ...(input.response === undefined
+        ? {}
+        : { response: input.response as never }),
+    }, {
+      ...input,
+      parentOperationId: telemetryOperations.tool(
+        input.submissionId,
+        input.toolCallId,
+      ),
+    });
+  }
+
+  interactionCancelled(input: Readonly<{
+    submissionId: string;
+    toolCallId: string;
+    interactionId: string;
+    reason?: string;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.interaction(
+      input.submissionId,
+      input.interactionId,
+    );
+    return this.record("interaction.cancelled", operationId, {
+      interactionId: input.interactionId,
+      ...(input.reason ? { reason: input.reason } : {}),
+    }, {
+      ...input,
+      parentOperationId: telemetryOperations.tool(
+        input.submissionId,
+        input.toolCallId,
+      ),
+    });
+  }
+
+  subagentStarted(input: Readonly<{
+    submissionId: string;
+    toolCallId?: string;
+    subagentId: string;
+    agentType?: string;
+    prompt?: unknown;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.subagent(
+      input.submissionId,
+      input.subagentId,
+    );
+    return this.record("subagent.started", operationId, {
+      subagentId: input.subagentId,
+      ...(input.agentType ? { agentType: input.agentType } : {}),
+      ...(input.prompt === undefined ? {} : { prompt: input.prompt as never }),
+    }, {
+      ...input,
+      parentOperationId: input.toolCallId
+        ? telemetryOperations.tool(input.submissionId, input.toolCallId)
+        : telemetryOperations.turn(this.resource.sessionId, input.submissionId),
+    });
+  }
+
+  subagentFinished(input: Readonly<{
+    submissionId: string;
+    toolCallId?: string;
+    subagentId: string;
+    outcome: "completed" | "failed" | "cancelled";
+    durationMs?: number;
+    output?: unknown;
+    error?: string;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.subagent(
+      input.submissionId,
+      input.subagentId,
+    );
+    return this.record("subagent.finished", operationId, {
+      subagentId: input.subagentId,
+      outcome: input.outcome,
+      ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+      ...(input.output === undefined ? {} : { output: input.output as never }),
+      ...(input.error ? { error: input.error } : {}),
+    }, {
+      ...input,
+      parentOperationId: input.toolCallId
+        ? telemetryOperations.tool(input.submissionId, input.toolCallId)
+        : telemetryOperations.turn(this.resource.sessionId, input.submissionId),
+    });
+  }
+
+  contextCompacted(input: Readonly<{
+    submissionId: string;
+    compactionId: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    removedMessages?: number;
+    summary?: unknown;
+    occurredAt?: number;
+  }>): TelemetryRecordResult {
+    const operationId = telemetryOperations.compaction(
+      this.resource.sessionId,
+      input.compactionId,
+    );
+    return this.record("context.compacted", operationId, {
+      compactionId: input.compactionId,
+      ...(input.inputTokens === undefined ? {} : { inputTokens: input.inputTokens }),
+      ...(input.outputTokens === undefined ? {} : { outputTokens: input.outputTokens }),
+      ...(input.removedMessages === undefined
+        ? {}
+        : { removedMessages: input.removedMessages }),
+      ...(input.summary === undefined ? {} : { summary: input.summary as never }),
+    }, {
+      ...input,
+      parentOperationId: telemetryOperations.turn(
+        this.resource.sessionId,
+        input.submissionId,
+      ),
+    });
+  }
+}

package/src/telemetry/sanitize.ts

@@ -0,0 +1,97 @@
+import {
+  assertUniversalTelemetryEvent,
+  type TelemetryPrivacyMode,
+  type TelemetryValue,
+  type UniversalTelemetryEvent,
+  type UniversalTelemetryEventType,
+} from "./contract";
+
+export const TELEMETRY_SANITIZE_LIMITS = {
+  maxDepth: 16,
+  maxArrayItems: 200,
+  maxObjectEntries: 500,
+  metadataStringLength: 512,
+  contentStringLength: 20_000,
+} as const;
+
+export const TELEMETRY_REDACTED = "[REDACTED]";
+export const TELEMETRY_CONTENT_OMITTED = "[CONTENT OMITTED]";
+
+const SECRET_KEYS = /(?:authorization|cookie|credential|password|passwd|secret|api.?key|access.?token|refresh.?token|private.?key)/i;
+const CONTENT_KEYS = /^(?:args?|input|output|result|response|prompt|messages?|content|text|partialtext|partialparts|summary|reason|error)$/i;
+const SECRET_VALUE_PATTERNS = [
+  /\bbearer\s+[a-z0-9._~+/=-]+/i,
+  /\b(?:sk|pk)_(?:live|test)_[a-z0-9_-]{12,}\b/i,
+  /\bsk-[a-z0-9_-]{12,}\b/i,
+  /\beyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\b/,
+];
+
+function normalizedKey(key: string): string {
+  return key.replace(/[^a-z0-9]/gi, "");
+}
+
+function truncate(value: string, limit: number): string {
+  if (value.length <= limit) return value;
+  return `${value.slice(0, limit)}…[truncated ${value.length - limit} chars]`;
+}
+
+function sanitizeString(value: string, limit: number): string {
+  if (SECRET_VALUE_PATTERNS.some((pattern) => pattern.test(value))) {
+    return TELEMETRY_REDACTED;
+  }
+  return truncate(value, limit);
+}
+
+function sanitizeValue(
+  value: unknown,
+  mode: TelemetryPrivacyMode,
+  depth: number,
+  key?: string,
+): TelemetryValue | undefined {
+  const normalized = key === undefined ? "" : normalizedKey(key);
+  if (key !== undefined && SECRET_KEYS.test(normalized)) {
+    return TELEMETRY_REDACTED;
+  }
+  if (mode === "metadata" && key !== undefined && CONTENT_KEYS.test(normalized)) {
+    return TELEMETRY_CONTENT_OMITTED;
+  }
+  if (depth >= TELEMETRY_SANITIZE_LIMITS.maxDepth) {
+    return "[MAX DEPTH]";
+  }
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "string") {
+    const limit = mode === "content"
+      ? TELEMETRY_SANITIZE_LIMITS.contentStringLength
+      : TELEMETRY_SANITIZE_LIMITS.metadataStringLength;
+    return sanitizeString(value, limit);
+  }
+  if (Array.isArray(value)) {
+    return value
+      .slice(0, TELEMETRY_SANITIZE_LIMITS.maxArrayItems)
+      .map((item) => sanitizeValue(item, mode, depth + 1) ?? null);
+  }
+  if (typeof value === "object" && value !== null) {
+    const output: Record<string, TelemetryValue> = {};
+    for (const [entryKey, entryValue] of Object.entries(value).slice(
+      0,
+      TELEMETRY_SANITIZE_LIMITS.maxObjectEntries,
+    )) {
+      const sanitized = sanitizeValue(entryValue, mode, depth + 1, entryKey);
+      if (sanitized !== undefined) output[entryKey] = sanitized;
+    }
+    return output;
+  }
+  return undefined;
+}
+
+/** Sanitize before persistence; downstream consumers never see raw secrets. */
+export function sanitizeTelemetryEvent<T extends UniversalTelemetryEventType>(
+  event: UniversalTelemetryEvent<T>,
+  mode: TelemetryPrivacyMode,
+): UniversalTelemetryEvent<T> {
+  assertUniversalTelemetryEvent(event);
+  const sanitized = sanitizeValue(event, mode, 0);
+  assertUniversalTelemetryEvent(sanitized);
+  return sanitized as unknown as UniversalTelemetryEvent<T>;
+}