@telemetry-dev/eve 0.1.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@telemetry-dev/eve",
+  "version": "0.1.0",
+  "description": "Eve (Vercel agent framework) telemetry integration for telemetry.dev.",
+  "keywords": [
+    "agents",
+    "eve",
+    "genai",
+    "llm",
+    "observability",
+    "opentelemetry",
+    "telemetry",
+    "tracing"
+  ],
+  "homepage": "https://telemetry.dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telemetry-dev/telemetry.dev.git",
+    "directory": "packages/eve"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@telemetry-dev/sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/sdk-logs": "^0.218.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260328.1",
+    "ai": "7.0.0",
+    "eve": "0.19.0",
+    "typescript": "^6.0.2",
+    "vite-plus": "0.1.20",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.20",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "eve": ">=0.19.0 <1"
+  },
+  "scripts": {
+    "build": "pnpm exec vp pack",
+    "dev": "pnpm exec vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}

package/src/client.ts

@@ -0,0 +1,277 @@
+import type { Attributes } from "@opentelemetry/api";
+import {
+  startSpan,
+  type ClientOverrides,
+  type SpanHandle,
+  type TokenUsage,
+} from "@telemetry-dev/sdk";
+import type {
+  Client,
+  ClientSession,
+  HandleMessageStreamEvent,
+  SendTurnInput,
+  SendTurnPayload,
+  SessionState,
+} from "eve/client";
+import { isCurrentTurnBoundaryEvent, MessageResponse } from "eve/client";
+
+import { ensureInit, type TelemetryDevEveOptions } from "./config.ts";
+
+export interface WrapEveClientOptions extends TelemetryDevEveOptions {
+  /** gen_ai.agent.name on turn spans. */
+  agentName?: string;
+  /** Span name for each send() turn. Default "invoke_agent". */
+  spanName?: string;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== "object") return undefined;
+  return value as Record<string, unknown>;
+}
+
+function stringField(record: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = record?.[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function numberField(record: Record<string, unknown> | undefined, key: string): number | undefined {
+  const value = record?.[key];
+  return typeof value === "number" ? value : undefined;
+}
+
+function eventData(event: HandleMessageStreamEvent): Record<string, unknown> {
+  if (!("data" in event)) return {};
+  return asRecord(event.data) ?? {};
+}
+
+function eventAttributes(
+  attributes: Record<string, string | number | boolean | undefined>,
+): Attributes {
+  const out: Attributes = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+function addUsage(usage: TokenUsage, key: keyof TokenUsage, value: number | undefined): boolean {
+  if (value === undefined) return false;
+  usage[key] = (usage[key] ?? 0) + value;
+  return true;
+}
+
+function failureError(code: string | undefined, message: string | undefined): Error {
+  const error = new Error(message ?? code ?? "error");
+  if (code) error.name = code;
+  return error;
+}
+
+function inputForSpan<TOutput>(payload: SendTurnPayload<TOutput>): unknown {
+  return payload.message ?? payload.inputResponses;
+}
+
+function bindOrReturn<T extends object>(target: T, prop: string | symbol): unknown {
+  const value = Reflect.get(target, prop, target);
+  return typeof value === "function" ? value.bind(target) : value;
+}
+
+function addLifecycleEvent(span: SpanHandle, event: HandleMessageStreamEvent): void {
+  const data = eventData(event);
+  switch (event.type) {
+    case "subagent.called": {
+      const remote = asRecord(data.remote);
+      span.span.addEvent(
+        event.type,
+        eventAttributes({
+          "eve.subagent.name": stringField(data, "name"),
+          "gen_ai.tool.name": stringField(data, "toolName"),
+          "gen_ai.tool.call.id": stringField(data, "callId"),
+          "eve.child.session_id": stringField(data, "childSessionId"),
+          "eve.workflow.id": stringField(data, "workflowId"),
+          "eve.remote.url": stringField(remote, "url"),
+        }),
+      );
+      return;
+    }
+    case "input.requested": {
+      const requests = Array.isArray(data.requests) ? data.requests : undefined;
+      span.span.addEvent(
+        event.type,
+        eventAttributes({ "eve.input.request_count": requests?.length }),
+      );
+      return;
+    }
+    case "authorization.required":
+      span.span.addEvent(
+        event.type,
+        eventAttributes({ "eve.authorization.name": stringField(data, "name") }),
+      );
+      return;
+    default:
+      return;
+  }
+}
+
+async function* instrumentedStream<TOutput>(
+  response: MessageResponse<TOutput>,
+  span: SpanHandle,
+  start: number,
+  payload: SendTurnPayload<TOutput>,
+): AsyncGenerator<HandleMessageStreamEvent> {
+  const usage: TokenUsage = {};
+  let sawUsage = false;
+  let output: unknown;
+  let finishReason: string | undefined;
+  let timeToFirstChunkMs: number | undefined;
+  let error: unknown;
+  let sawTerminalEvent = false;
+
+  const finish = (): void => {
+    if (!sawTerminalEvent && error === undefined) {
+      if (payload.signal?.aborted) {
+        error = failureError("cancelled", "cancelled");
+        finishReason ??= "cancelled";
+      } else {
+        error = failureError("stream_incomplete", "stream ended before a terminal event");
+        finishReason ??= "error";
+      }
+    }
+    span.end({
+      usage: sawUsage ? usage : undefined,
+      finishReason,
+      output,
+      timeToFirstChunkMs,
+      error,
+    });
+  };
+
+  try {
+    for await (const event of response) {
+      const data = eventData(event);
+      if (isCurrentTurnBoundaryEvent(event)) sawTerminalEvent = true;
+      if (
+        timeToFirstChunkMs === undefined &&
+        (event.type === "message.appended" || event.type === "reasoning.appended")
+      ) {
+        timeToFirstChunkMs = performance.now() - start;
+      }
+
+      if (event.type === "step.completed") {
+        const eventUsage = asRecord(data.usage);
+        sawUsage =
+          addUsage(usage, "inputTokens", numberField(eventUsage, "inputTokens")) || sawUsage;
+        sawUsage =
+          addUsage(usage, "outputTokens", numberField(eventUsage, "outputTokens")) || sawUsage;
+        sawUsage =
+          addUsage(usage, "cacheReadInputTokens", numberField(eventUsage, "cacheReadTokens")) ||
+          sawUsage;
+        sawUsage =
+          addUsage(
+            usage,
+            "cacheCreationInputTokens",
+            numberField(eventUsage, "cacheWriteTokens"),
+          ) || sawUsage;
+        finishReason = stringField(data, "finishReason") ?? finishReason;
+      }
+
+      if (
+        event.type === "message.completed" &&
+        stringField(data, "finishReason") !== "tool-calls"
+      ) {
+        output = data.message;
+      }
+      if (event.type === "result.completed") {
+        output = data.result;
+      }
+      if (
+        event.type === "turn.failed" ||
+        event.type === "session.failed" ||
+        event.type === "step.failed"
+      ) {
+        if (error === undefined) {
+          const code = stringField(data, "code");
+          error = failureError(code, stringField(data, "message"));
+          if (code) span.span.setAttribute("error.code", code);
+        }
+        finishReason = "error";
+      }
+
+      addLifecycleEvent(span, event);
+      yield event;
+    }
+  } catch (caught) {
+    if (payload.signal?.aborted) {
+      error = failureError("cancelled", "cancelled");
+      finishReason ??= "cancelled";
+    } else {
+      error = caught;
+    }
+    throw caught;
+  } finally {
+    finish();
+  }
+}
+
+function wrapSession(session: ClientSession, options: WrapEveClientOptions): ClientSession {
+  return new Proxy(session, {
+    get(target, prop) {
+      if (prop === "send") {
+        const wrappedSend: ClientSession["send"] = async <TOutput = unknown>(
+          input: SendTurnInput<TOutput>,
+        ) => {
+          const payload: SendTurnPayload<TOutput> =
+            typeof input === "string" ? { message: input } : input;
+          const span = startSpan(options.spanName ?? "invoke_agent", {
+            type: "agent",
+            agentName: options.agentName,
+            input: inputForSpan(payload),
+          });
+          const start = performance.now();
+          let response: MessageResponse<TOutput>;
+          try {
+            response = await target.send(input);
+          } catch (error) {
+            if (payload.signal?.aborted) {
+              span.end({
+                error: failureError("cancelled", "cancelled"),
+                finishReason: "cancelled",
+              });
+            } else {
+              span.end({ error });
+            }
+            throw error;
+          }
+
+          span.span.setAttribute("gen_ai.conversation.id", response.sessionId);
+          // MessageResponse's constructor is @internal in eve; re-wrapping the stream has no
+          // public alternative. Revisit on eve upgrades.
+          return new MessageResponse<TOutput>({
+            continuationToken: response.continuationToken,
+            sessionId: response.sessionId,
+            createStream: () => instrumentedStream(response, span, start, payload),
+          });
+        };
+        return wrappedSend;
+      }
+      return bindOrReturn(target, prop);
+    },
+  });
+}
+
+export function wrapEveClient<C extends Client>(
+  client: C,
+  options: WrapEveClientOptions = {},
+  overrides?: ClientOverrides,
+): C {
+  const { agentName: _agentName, spanName: _spanName, ...sdkOptions } = options;
+  ensureInit(sdkOptions, overrides);
+
+  return new Proxy(client, {
+    get(target, prop) {
+      if (prop === "session") {
+        return (state?: SessionState | string) => wrapSession(target.session(state), options);
+      }
+      return bindOrReturn(target, prop);
+    },
+  }) as C;
+}

package/src/config.ts

@@ -0,0 +1,37 @@
+import { init, shutdown, type ClientOverrides, type TelemetryOptions } from "@telemetry-dev/sdk";
+
+/** Options accepted by every @telemetry-dev/eve entry point. */
+export type TelemetryDevEveOptions = Omit<TelemetryOptions, "registerGlobal">;
+
+export type { ClientOverrides };
+
+let initialized = false;
+
+/**
+ * Initializes the telemetry.dev SDK exactly once per process for this integration.
+ * registerGlobal:true lets eve's tracers (scopes "eve" and "gen_ai") resolve to
+ * the SDK provider. spanFilter defaults to exporting everything except eve's
+ * internal workflow-engine spans (scope "workflow"); pass spanFilter: () => true
+ * to export those too.
+ */
+export function ensureInit(
+  options: TelemetryDevEveOptions = {},
+  overrides?: ClientOverrides,
+): void {
+  if (initialized) return;
+  initialized = true;
+  init(
+    {
+      ...options,
+      registerGlobal: true,
+      spanFilter: options.spanFilter ?? ((span) => span.instrumentationScope.name !== "workflow"),
+    },
+    overrides,
+  );
+}
+
+/** Test seam for unit tests that need a fresh SDK singleton. */
+export async function resetForTesting(): Promise<void> {
+  initialized = false;
+  await shutdown();
+}

package/src/hook.ts

@@ -0,0 +1,313 @@
+import { log, type LogLevel } from "@telemetry-dev/sdk";
+import type { HandleMessageStreamEvent } from "eve/client";
+import type { HookContext, HookDefinition } from "eve/hooks";
+
+import { ensureInit, type ClientOverrides, type TelemetryDevEveOptions } from "./config.ts";
+
+type Attrs = Record<string, unknown>;
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== "object") return undefined;
+  return value as Record<string, unknown>;
+}
+
+function eventData(event: HandleMessageStreamEvent): Record<string, unknown> {
+  if (!("data" in event)) return {};
+  return asRecord(event.data) ?? {};
+}
+
+function stringField(record: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = record?.[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function numberField(record: Record<string, unknown> | undefined, key: string): number | undefined {
+  const value = record?.[key];
+  return typeof value === "number" ? value : undefined;
+}
+
+function jsonField(record: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = record?.[key];
+  if (value === undefined) return undefined;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function baseAttributes(event: HandleMessageStreamEvent, ctx: HookContext): Attrs {
+  const data = eventData(event);
+  return {
+    "gen_ai.conversation.id": ctx.session.id,
+    "gen_ai.agent.name": ctx.agent.name,
+    "eve.channel.kind": ctx.channel.kind,
+    "eve.turn.id": stringField(data, "turnId"),
+    "eve.step.index": numberField(data, "stepIndex"),
+    "eve.turn.sequence": numberField(data, "sequence"),
+  };
+}
+
+function toolAttrs(result: unknown): Attrs {
+  const record = asRecord(result);
+  const subagentName = stringField(record, "subagentName");
+  return {
+    "gen_ai.tool.name":
+      stringField(record, "toolName") ??
+      (subagentName ? `eve:subagent:${subagentName}` : undefined),
+    "gen_ai.tool.call.id": stringField(record, "callId"),
+    "eve.subagent.name": subagentName,
+  };
+}
+function reportError(onError: ((error: unknown) => void) | undefined, error: unknown): void {
+  try {
+    onError?.(error);
+  } catch {
+    // telemetry hooks must never fail an Eve turn.
+  }
+}
+
+function emit(
+  event: HandleMessageStreamEvent,
+  ctx: HookContext,
+  level: LogLevel,
+  message: string,
+  attributes: Attrs = {},
+  baseEvent: HandleMessageStreamEvent = event,
+): void {
+  const at = event.meta?.at;
+  log(message, {
+    level,
+    eventName: event.type,
+    timestamp: at ? new Date(at) : undefined,
+    attributes: { ...baseAttributes(baseEvent, ctx), ...attributes },
+  });
+}
+
+function stepCompletedMessage(data: Record<string, unknown>): string {
+  const finishReason = stringField(data, "finishReason") ?? "unknown";
+  const usage = asRecord(data.usage);
+  const inputTokens = numberField(usage, "inputTokens");
+  const outputTokens = numberField(usage, "outputTokens");
+  const suffix =
+    inputTokens !== undefined && outputTokens !== undefined
+      ? `: ${inputTokens} in / ${outputTokens} out tokens`
+      : "";
+  return `Step completed (${finishReason})${suffix}`;
+}
+
+function logEvent(event: HandleMessageStreamEvent, ctx: HookContext): void {
+  const data = eventData(event);
+
+  switch (event.type) {
+    case "session.started": {
+      const runtime = asRecord(data.runtime);
+      const invocation = asRecord(data.invocation);
+      emit(event, ctx, "info", "Session started", {
+        "eve.version": stringField(runtime, "eveVersion"),
+        "gen_ai.request.model": stringField(runtime, "modelId"),
+        "eve.agent.id": stringField(runtime, "agentId"),
+        "eve.parent.session_id": stringField(invocation, "parentSessionId"),
+        "eve.parent.call_id": stringField(invocation, "parentCallId"),
+        "eve.parent.turn_id": stringField(invocation, "parentTurnId"),
+        "eve.subagent.name": stringField(invocation, "name"),
+      });
+      return;
+    }
+    case "turn.started":
+      emit(event, ctx, "debug", "Turn started");
+      return;
+    case "message.received":
+      emit(event, ctx, "debug", "User message received");
+      return;
+    case "step.completed": {
+      const usage = asRecord(data.usage);
+      emit(event, ctx, "info", stepCompletedMessage(data), {
+        "gen_ai.usage.input_tokens": numberField(usage, "inputTokens"),
+        "gen_ai.usage.output_tokens": numberField(usage, "outputTokens"),
+        "eve.usage.cache_read_tokens": numberField(usage, "cacheReadTokens"),
+        "eve.usage.cache_write_tokens": numberField(usage, "cacheWriteTokens"),
+      });
+      return;
+    }
+    case "step.failed":
+      emit(event, ctx, "error", `Step failed: ${stringField(data, "message") ?? ""}`, {
+        "error.code": stringField(data, "code"),
+        "eve.error.details": jsonField(data, "details"),
+      });
+      return;
+    case "action.result": {
+      const status = stringField(data, "status");
+      if (status === "completed") return;
+      const error = asRecord(data.error);
+      emit(
+        event,
+        ctx,
+        status === "failed" ? "error" : "warn",
+        `Tool ${status ?? "failed"}: ${stringField(error, "message") ?? ""}`,
+        {
+          "error.code": stringField(error, "code"),
+          ...toolAttrs(data.result),
+        },
+      );
+      return;
+    }
+    case "input.requested": {
+      const requests = Array.isArray(data.requests) ? data.requests : undefined;
+      emit(event, ctx, "info", "Input requested (HITL)", {
+        "eve.input.request_count": requests?.length,
+      });
+      return;
+    }
+    case "authorization.required":
+      emit(event, ctx, "warn", `Authorization required: ${stringField(data, "name") ?? ""}`, {
+        "eve.authorization.name": stringField(data, "name"),
+      });
+      return;
+    case "authorization.completed": {
+      const outcome = stringField(data, "outcome");
+      emit(
+        event,
+        ctx,
+        outcome === "authorized" ? "info" : "warn",
+        `Authorization ${outcome ?? "completed"}: ${stringField(data, "name") ?? ""}`,
+        {
+          "eve.authorization.name": stringField(data, "name"),
+          "eve.authorization.outcome": outcome,
+          "eve.authorization.reason": stringField(data, "reason"),
+        },
+      );
+      return;
+    }
+    case "subagent.started":
+      emit(event, ctx, "info", "Subagent started", {
+        "eve.subagent.name": stringField(data, "subagentName"),
+        "gen_ai.tool.call.id": stringField(data, "callId"),
+      });
+      return;
+    case "subagent.event": {
+      const child = asRecord(data.event);
+      const childData = asRecord(child?.data);
+      const childType = stringField(child, "type");
+      const attrs = {
+        "eve.subagent.name": stringField(data, "subagentName"),
+        "gen_ai.tool.call.id": stringField(data, "callId"),
+      };
+      if (childType === "step.failed") {
+        emit(
+          event,
+          ctx,
+          "error",
+          `Subagent step failed: ${stringField(childData, "message") ?? ""}`,
+          {
+            ...attrs,
+            "error.code": stringField(childData, "code"),
+            "eve.error.details": jsonField(childData, "details"),
+          },
+          child as unknown as HandleMessageStreamEvent,
+        );
+        return;
+      }
+      if (childType === "turn.failed") {
+        emit(
+          event,
+          ctx,
+          "error",
+          `Subagent turn failed: ${stringField(childData, "message") ?? ""}`,
+          {
+            ...attrs,
+            "error.code": stringField(childData, "code"),
+            "eve.error.details": jsonField(childData, "details"),
+          },
+          child as unknown as HandleMessageStreamEvent,
+        );
+        return;
+      }
+      if (childType === "session.failed") {
+        emit(
+          event,
+          ctx,
+          "error",
+          `Subagent session failed: ${stringField(childData, "message") ?? ""}`,
+          {
+            ...attrs,
+            "error.code": stringField(childData, "code"),
+            "eve.error.details": jsonField(childData, "details"),
+          },
+          child as unknown as HandleMessageStreamEvent,
+        );
+      }
+      return;
+    }
+    case "subagent.called": {
+      const remote = asRecord(data.remote);
+      emit(event, ctx, "info", `Subagent called: ${stringField(data, "name") ?? ""}`, {
+        "eve.subagent.name": stringField(data, "name"),
+        "gen_ai.tool.name": stringField(data, "toolName"),
+        "gen_ai.tool.call.id": stringField(data, "callId"),
+        "eve.child.session_id": stringField(data, "childSessionId"),
+        "eve.workflow.id": stringField(data, "workflowId"),
+        "eve.remote.url": stringField(remote, "url"),
+      });
+      return;
+    }
+    case "subagent.completed":
+      emit(event, ctx, "info", "Subagent completed", {
+        "eve.subagent.name": stringField(data, "subagentName"),
+        "gen_ai.tool.call.id": stringField(data, "callId"),
+      });
+      return;
+    case "compaction.requested":
+      emit(event, ctx, "info", `Compaction requested (${stringField(data, "modelId") ?? ""})`, {
+        "gen_ai.request.model": stringField(data, "modelId"),
+        "gen_ai.usage.input_tokens": numberField(data, "usageInputTokens"),
+      });
+      return;
+    case "compaction.completed":
+      emit(event, ctx, "debug", "Compaction completed", {
+        "gen_ai.request.model": stringField(data, "modelId"),
+      });
+      return;
+    case "turn.completed":
+      emit(event, ctx, "info", "Turn completed");
+      return;
+    case "turn.failed":
+      emit(event, ctx, "error", `Turn failed: ${stringField(data, "message") ?? ""}`, {
+        "error.code": stringField(data, "code"),
+        "eve.error.details": jsonField(data, "details"),
+      });
+      return;
+    case "session.waiting":
+      emit(event, ctx, "debug", "Session waiting");
+      return;
+    case "session.completed":
+      emit(event, ctx, "info", "Session completed");
+      return;
+    case "session.failed":
+      emit(event, ctx, "error", `Session failed: ${stringField(data, "message") ?? ""}`, {
+        "error.code": stringField(data, "code"),
+        "eve.error.details": jsonField(data, "details"),
+      });
+      return;
+    default:
+      return;
+  }
+}
+
+export function telemetryDevHook(
+  options: TelemetryDevEveOptions = {},
+  overrides?: ClientOverrides,
+): HookDefinition {
+  return {
+    events: {
+      "*"(event, ctx) {
+        try {
+          ensureInit(options, overrides);
+          logEvent(event, ctx);
+        } catch (error) {
+          reportError(options.onError, error);
+        }
+      },
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { wrapEveClient, type WrapEveClientOptions } from "./client.ts";
+export type { TelemetryDevEveOptions } from "./config.ts";
+export { telemetryDevHook } from "./hook.ts";
+export {
+  telemetryDevInstrumentation,
+  type TelemetryDevInstrumentationOptions,
+} from "./instrumentation.ts";