@stigmer/runner 3.0.1

package/src/activities/execute-deep-agent/v3-event-recorder.ts

@@ -0,0 +1,111 @@
+/**
+ * V3 event recorder for capturing raw LangGraph v3 ProtocolEvents.
+ *
+ * Activated by the V3_EVENT_RECORD_DIR environment variable. When set,
+ * the v3 streaming loop records every raw protocol event and flushes
+ * them atomically to a JSON file after the stream completes.
+ *
+ * This is test/development infrastructure for the v3 streaming migration.
+ * The captured events serve as ground-truth for building the
+ * V3StatusBuilder and validating v3 event shape assumptions.
+ */
+
+import { writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+interface RecordedV3Event {
+  readonly seq: number;
+  readonly capturedAt: string;
+  readonly type: string;
+  readonly method: string;
+  readonly namespace: string[];
+  readonly timestamp: number;
+  readonly node: string | undefined;
+  readonly data: unknown;
+}
+
+export interface V3EventRecorder {
+  record(event: V3ProtocolEvent, seq: number): void;
+  flush(): Promise<void>;
+}
+
+export interface V3ProtocolEvent {
+  readonly type: string;
+  readonly seq: number;
+  readonly method: string;
+  readonly params: {
+    readonly namespace: string[];
+    readonly timestamp: number;
+    readonly node?: string;
+    readonly data: unknown;
+  };
+}
+
+/**
+ * Create a recorder if V3_EVENT_RECORD_DIR is set, otherwise return undefined.
+ * The caller does `recorder?.record(event, seq)` — zero overhead when off.
+ */
+export function createV3EventRecorder(
+  executionId: string,
+  recordDir: string | undefined,
+): V3EventRecorder | undefined {
+  if (!recordDir) return undefined;
+  return new FileV3EventRecorder(executionId, recordDir);
+}
+
+class FileV3EventRecorder implements V3EventRecorder {
+  private readonly events: RecordedV3Event[] = [];
+
+  constructor(
+    private readonly executionId: string,
+    private readonly outputDir: string,
+  ) {}
+
+  record(event: V3ProtocolEvent, seq: number): void {
+    this.events.push({
+      seq,
+      capturedAt: new Date().toISOString(),
+      type: event.type,
+      method: event.method,
+      namespace: event.params.namespace,
+      timestamp: event.params.timestamp,
+      node: event.params.node,
+      data: safeClone(event.params.data),
+    });
+  }
+
+  async flush(): Promise<void> {
+    if (this.events.length === 0) return;
+
+    await mkdir(this.outputDir, { recursive: true });
+
+    const filePath = join(
+      this.outputDir,
+      `${this.executionId}.v3-events.json`,
+    );
+
+    const payload = {
+      executionId: this.executionId,
+      recordedAt: new Date().toISOString(),
+      eventCount: this.events.length,
+      events: this.events,
+    };
+
+    await writeFile(filePath, JSON.stringify(payload, bigintReplacer, 2));
+  }
+}
+
+function safeClone(obj: unknown): unknown {
+  try {
+    return JSON.parse(JSON.stringify(obj, bigintReplacer));
+  } catch {
+    if (obj && typeof obj === "object") {
+      return { _serializationError: true, keys: Object.keys(obj) };
+    }
+    return { _serializationError: true };
+  }
+}
+
+function bigintReplacer(_key: string, value: unknown): unknown {
+  return typeof value === "bigint" ? value.toString() : value;
+}

package/src/activities/execute-deep-agent/v3-events.ts

@@ -0,0 +1,153 @@
+/**
+ * StigmerRunEvent — normalized v3 protocol event types.
+ *
+ * The V3ProtocolNormalizer converts raw LangGraph ProtocolEvents into
+ * these typed variants. V3StatusBuilder consumes them to build the
+ * AgentExecutionStatus proto.
+ *
+ * This is a runner-internal contract (not persisted, not exposed to
+ * clients). It isolates the StatusBuilder from LangGraph protocol
+ * instability (field naming, delta shapes, channel semantics).
+ *
+ * ID conventions:
+ *   - `runId`  — LLM invocation ID; shared across message events in one turn
+ *   - `callId` — provider tool call ID (e.g. `toolu_...`); keys ToolCall records
+ *   - `namespace` — formatted string from v3 namespace array; empty = parent agent
+ */
+
+// ── Base ──────────────────────────────────────────────────────────
+
+interface StigmerRunEventBase {
+  readonly kind: string;
+  readonly seq: number;
+  /** Formatted namespace string: empty = parent agent, joined with "|" for nested. */
+  readonly namespace: string;
+  readonly node?: string;
+}
+
+// ── Message Events (from `messages` channel) ──────────────────────
+
+export interface MessageStartEvent extends StigmerRunEventBase {
+  readonly kind: "message_start";
+  readonly runId: string;
+  readonly messageId?: string;
+}
+
+export interface TextDeltaEvent extends StigmerRunEventBase {
+  readonly kind: "text_delta";
+  readonly runId: string;
+  readonly text: string;
+}
+
+export interface ReasoningDeltaEvent extends StigmerRunEventBase {
+  readonly kind: "reasoning_delta";
+  readonly runId: string;
+  readonly text: string;
+}
+
+export interface ToolCallArgDeltaEvent extends StigmerRunEventBase {
+  readonly kind: "tool_call_arg_delta";
+  readonly callId: string;
+  readonly argsChunk: string;
+}
+
+export interface MessageFinishEvent extends StigmerRunEventBase {
+  readonly kind: "message_finish";
+  readonly runId: string;
+  readonly usage?: V3UsagePayload;
+  readonly reason?: string;
+}
+
+// ── Tool Events (from `tools` channel — authoritative) ───────────
+
+export interface ToolStartedEvent extends StigmerRunEventBase {
+  readonly kind: "tool_started";
+  readonly callId: string;
+  readonly name: string;
+  readonly input: Record<string, unknown>;
+}
+
+export interface ToolOutputDeltaEvent extends StigmerRunEventBase {
+  readonly kind: "tool_output_delta";
+  readonly callId: string;
+  readonly delta: string;
+}
+
+export interface ToolFinishedEvent extends StigmerRunEventBase {
+  readonly kind: "tool_finished";
+  readonly callId: string;
+  readonly output: unknown;
+}
+
+export interface ToolErrorEvent extends StigmerRunEventBase {
+  readonly kind: "tool_error";
+  readonly callId: string;
+  readonly message: string;
+}
+
+// ── Usage / Lifecycle / Provider ──────────────────────────────────
+
+export interface UsageEvent extends StigmerRunEventBase {
+  readonly kind: "usage";
+  readonly runId: string;
+  readonly usage: V3UsagePayload;
+}
+
+export interface LifecycleEvent extends StigmerRunEventBase {
+  readonly kind: "lifecycle";
+  readonly event: string;
+  readonly graphName?: string;
+}
+
+export interface ProviderEvent extends StigmerRunEventBase {
+  readonly kind: "provider";
+  readonly provider: string;
+  readonly model?: string;
+}
+
+// ── Usage Payload ─────────────────────────────────────────────────
+
+export interface V3UsagePayload {
+  readonly input_tokens?: number;
+  readonly output_tokens?: number;
+  readonly total_tokens?: number;
+  readonly input_token_details?: {
+    readonly cache_creation?: number;
+    readonly cache_read?: number;
+  };
+}
+
+// ── Union ─────────────────────────────────────────────────────────
+
+export type StigmerRunEvent =
+  | MessageStartEvent
+  | TextDeltaEvent
+  | ReasoningDeltaEvent
+  | ToolCallArgDeltaEvent
+  | MessageFinishEvent
+  | ToolStartedEvent
+  | ToolOutputDeltaEvent
+  | ToolFinishedEvent
+  | ToolErrorEvent
+  | UsageEvent
+  | LifecycleEvent
+  | ProviderEvent;
+
+// ── Namespace Formatting ──────────────────────────────────────────
+
+export function formatNamespace(ns: readonly string[]): string {
+  return ns.length === 0 ? "" : ns.join("|");
+}
+
+/**
+ * Returns the depth (number of segments) of a formatted namespace string.
+ * Empty string → 0, single segment → 1, "a|b" → 2, etc.
+ */
+export function namespaceDepth(namespace: string): number {
+  if (!namespace) return 0;
+  let count = 1;
+  for (let i = 0; i < namespace.length; i++) {
+    if (namespace[i] === "|") count++;
+  }
+  return count;
+}

package/src/activities/execute-deep-agent/v3-protocol-normalizer.ts

@@ -0,0 +1,264 @@
+/**
+ * V3ProtocolNormalizer — converts raw LangGraph v3 ProtocolEvents
+ * into the StigmerRunEvent discriminated union.
+ *
+ * Stateless: each event is self-describing per real recordings.
+ * Routes by `event.method`, then by `data.event` within channels.
+ *
+ * Defensive parsing: handles both snake_case and camelCase field names
+ * for tool IDs/names (protocol spec uses camelCase but recordings show
+ * snake_case). Uses `data.event` as canonical discriminator, with
+ * `data.type` as fallback (CP04 finding).
+ */
+
+import type { V3ProtocolEvent } from "./v3-event-recorder.js";
+import type { StigmerRunEvent, V3UsagePayload } from "./v3-events.js";
+import { formatNamespace } from "./v3-events.js";
+
+const loggedUnknowns = new Set<string>();
+
+export function normalize(event: V3ProtocolEvent): StigmerRunEvent[] {
+  const method = event.method;
+
+  switch (method) {
+    case "messages": return normalizeMessage(event);
+    case "tools": return normalizeTool(event);
+    case "lifecycle": return normalizeLifecycle(event);
+    default:
+      return [];
+  }
+}
+
+// ── Messages Channel ──────────────────────────────────────────────
+
+function normalizeMessage(event: V3ProtocolEvent): StigmerRunEvent[] {
+  const data = event.params.data as Record<string, unknown> | undefined;
+  if (!data) return [];
+
+  const eventType = readEventType(data);
+  const base = {
+    seq: event.seq,
+    namespace: formatNamespace(event.params.namespace),
+    node: event.params.node,
+  };
+  const runId = (data.run_id ?? "") as string;
+
+  switch (eventType) {
+    case "message-start":
+      return [{
+        kind: "message_start" as const,
+        ...base,
+        runId,
+        messageId: data.id as string | undefined,
+      }];
+
+    case "content-block-delta":
+      return normalizeContentBlockDelta(event, data, base, runId);
+
+    case "message-finish":
+      return [{
+        kind: "message_finish" as const,
+        ...base,
+        runId,
+        usage: normalizeUsagePayload(data.usage as Record<string, unknown> | undefined),
+        reason: data.reason as string | undefined,
+      }];
+
+    case "usage":
+      return [{
+        kind: "usage" as const,
+        ...base,
+        runId,
+        usage: normalizeUsagePayload(data.usage as Record<string, unknown> | undefined)!,
+      }];
+
+    case "provider":
+      return [{
+        kind: "provider" as const,
+        ...base,
+        provider: (data.provider ?? "") as string,
+        model: extractModel(data),
+      }];
+
+    case "content-block-start":
+    case "content-block-finish":
+      return [];
+
+    default:
+      logUnknown("messages", eventType);
+      return [];
+  }
+}
+
+function normalizeContentBlockDelta(
+  event: V3ProtocolEvent,
+  data: Record<string, unknown>,
+  base: { seq: number; namespace: string; node?: string },
+  runId: string,
+): StigmerRunEvent[] {
+  const delta = data.delta as Record<string, unknown> | undefined;
+  if (!delta) return [];
+
+  const deltaType = delta.type as string | undefined;
+
+  if (deltaType === "text-delta") {
+    const text = (delta.text ?? "") as string;
+    if (!text) return [];
+    return [{ kind: "text_delta" as const, ...base, runId, text }];
+  }
+
+  if (deltaType === "reasoning-delta") {
+    const text = (delta.reasoning ?? "") as string;
+    if (!text) return [];
+    return [{ kind: "reasoning_delta" as const, ...base, runId, text }];
+  }
+
+  if (deltaType === "block-delta") {
+    const fields = delta.fields as Record<string, unknown> | undefined;
+    if (!fields) return [];
+    if (fields.type === "tool_call_chunk") {
+      const callId = (fields.id ?? "") as string;
+      const argsChunk = (fields.args ?? "") as string;
+      if (!argsChunk && !callId) return [];
+      return [{
+        kind: "tool_call_arg_delta" as const,
+        ...base,
+        callId,
+        argsChunk,
+      }];
+    }
+  }
+
+  return [];
+}
+
+// ── Tools Channel ─────────────────────────────────────────────────
+
+function normalizeTool(event: V3ProtocolEvent): StigmerRunEvent[] {
+  const data = event.params.data as Record<string, unknown> | undefined;
+  if (!data) return [];
+
+  const eventType = readEventType(data);
+  const base = {
+    seq: event.seq,
+    namespace: formatNamespace(event.params.namespace),
+    node: event.params.node,
+  };
+
+  switch (eventType) {
+    case "tool-started": {
+      const callId = readToolCallId(data);
+      const name = readToolName(data);
+      const input = parseToolInput(data.input);
+      return [{
+        kind: "tool_started" as const,
+        ...base,
+        callId,
+        name,
+        input,
+      }];
+    }
+
+    case "tool-finished": {
+      const callId = readToolCallId(data);
+      return [{
+        kind: "tool_finished" as const,
+        ...base,
+        callId,
+        output: data.output,
+      }];
+    }
+
+    case "tool-error": {
+      const callId = readToolCallId(data);
+      const message = (data.message ?? data.error ?? "") as string;
+      return [{
+        kind: "tool_error" as const,
+        ...base,
+        callId,
+        message,
+      }];
+    }
+
+    case "tool-output-delta": {
+      const callId = readToolCallId(data);
+      const delta = (data.delta ?? "") as string;
+      return [{
+        kind: "tool_output_delta" as const,
+        ...base,
+        callId,
+        delta: String(delta),
+      }];
+    }
+
+    default:
+      logUnknown("tools", eventType);
+      return [];
+  }
+}
+
+// ── Lifecycle Channel ─────────────────────────────────────────────
+
+function normalizeLifecycle(event: V3ProtocolEvent): StigmerRunEvent[] {
+  const data = event.params.data as Record<string, unknown> | undefined;
+  if (!data) return [];
+
+  return [{
+    kind: "lifecycle" as const,
+    seq: event.seq,
+    namespace: formatNamespace(event.params.namespace),
+    node: event.params.node,
+    event: readEventType(data),
+    graphName: (data.graph_name ?? data.graphName) as string | undefined,
+  }];
+}
+
+// ── Defensive Field Parsers ───────────────────────────────────────
+
+function readEventType(data: Record<string, unknown>): string {
+  return ((data.event ?? data.type) as string) ?? "";
+}
+
+function readToolCallId(data: Record<string, unknown>): string {
+  return ((data.tool_call_id ?? data.toolCallId) as string) ?? "";
+}
+
+function readToolName(data: Record<string, unknown>): string {
+  return ((data.tool_name ?? data.toolName ?? data.name) as string) ?? "unknown_tool";
+}
+
+function parseToolInput(raw: unknown): Record<string, unknown> {
+  if (raw === undefined || raw === null) return {};
+  if (typeof raw === "object" && !Array.isArray(raw)) return raw as Record<string, unknown>;
+  if (typeof raw === "string") {
+    try { return JSON.parse(raw) as Record<string, unknown>; }
+    catch { return {}; }
+  }
+  return {};
+}
+
+function normalizeUsagePayload(raw: Record<string, unknown> | undefined): V3UsagePayload | undefined {
+  if (!raw) return undefined;
+  const details = raw.input_token_details as Record<string, unknown> | undefined;
+  return {
+    input_tokens: raw.input_tokens as number | undefined,
+    output_tokens: raw.output_tokens as number | undefined,
+    total_tokens: raw.total_tokens as number | undefined,
+    input_token_details: details ? {
+      cache_creation: details.cache_creation as number | undefined,
+      cache_read: details.cache_read as number | undefined,
+    } : undefined,
+  };
+}
+
+function extractModel(data: Record<string, unknown>): string | undefined {
+  const payload = data.payload as Record<string, unknown> | undefined;
+  return payload?.model as string | undefined;
+}
+
+function logUnknown(method: string, eventType: string): void {
+  const key = `${method}:${eventType}`;
+  if (loggedUnknowns.has(key)) return;
+  loggedUnknowns.add(key);
+  console.debug(`[V3Normalizer] Unknown event: method=${method} event=${eventType}`);
+}