@narumitw/pi-langfuse 0.50.6 → 0.51.1

package/src/runtime.ts

@@ -9,32 +9,62 @@ import {
 } from "@langfuse/tracing";
 import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import type { LangfuseConfig } from "./config.js";
+import { DEFAULT_BASE_URL, type LangfuseConfig } from "./config.js";
+import {
+  type CreateLangfuseRuntimeOptions,
+  createLangfuseRuntimeFromBackend,
+  getLangfuseRuntimeInternal,
+  type LangfuseRuntime,
+  type LangfuseRuntimeInternal,
+} from "./runtime-core.js";
 import type { Observation, ObservationAttributes, ObservationType, TraceBackend } from "./tracing.js";
 
-const RUNTIME_KEY = Symbol.for("@narumitw/pi-langfuse/runtime/v1");
+export type {
+  CreateLangfuseRuntimeOptions,
+  LangfuseRuntime,
+  LangfuseRuntimeConfig,
+} from "./runtime-core.js";
+
+const RUNTIME_KEY = Symbol.for("@narumitw/pi-langfuse/runtime/v2");
+const LEGACY_RUNTIME_KEY = Symbol.for("@narumitw/pi-langfuse/runtime/v1");
+
+interface ResolvedRuntimeConfig {
+  publicKey: string;
+  secretKey: string;
+  baseUrl: string;
+  environment?: string;
+  release?: string;
+}
 
 interface SharedRuntime {
   fingerprint: string;
-  backend: ProductionTraceBackend;
-  shutdown: boolean;
+  runtime: LangfuseRuntimeInternal;
+  shutdown: true;
 }
 
 type GlobalWithRuntime = typeof globalThis & {
   [RUNTIME_KEY]?: Promise<SharedRuntime>;
+  [LEGACY_RUNTIME_KEY]?: unknown;
 };
 
 export interface RuntimeFactories {
-  createProcessor(config: LangfuseConfig): SpanProcessor;
+  createProcessor(config: ResolvedRuntimeConfig): SpanProcessor;
   createProvider(processor: SpanProcessor): NodeTracerProvider;
   selectProvider(provider: NodeTracerProvider): void;
 }
 
 class ProductionObservation implements Observation {
-  constructor(readonly native: LangfuseObservation) {}
+  readonly traceId: string;
+
+  constructor(
+    readonly native: LangfuseObservation,
+    private readonly secrets: readonly string[],
+  ) {
+    this.traceId = native.traceId;
+  }
 
   update(attributes: ObservationAttributes): Observation {
-    const { sessionId, userId, ...observationAttributes } = attributes;
+    const { sessionId, userId, ...observationAttributes } = maskObservationAttributes(attributes, this.secrets);
     this.native.updateOtelSpanAttributes(observationAttributes as LangfuseObservationAttributes);
     applySessionId(this.native, sessionId);
     applyUserId(this.native, userId);
@@ -42,7 +72,10 @@ class ProductionObservation implements Observation {
   }
 
   updateTrace(attributes: ObservationAttributes): Observation {
-    const { input, output, metadata, name, sessionId, userId, tags, version } = attributes;
+    const { input, output, metadata, name, sessionId, userId, tags, version } = maskObservationAttributes(
+      attributes,
+      this.secrets,
+    );
     if (input !== undefined || output !== undefined) {
       this.native.setTraceIO({ input, output });
     }
@@ -58,7 +91,10 @@ class ProductionObservation implements Observation {
       this.native.otelSpan.setAttribute(LangfuseOtelSpanAttributes.VERSION, version);
     }
     for (const [key, value] of Object.entries(metadata ?? {})) {
-      this.native.otelSpan.setAttribute(`${LangfuseOtelSpanAttributes.TRACE_METADATA}.${key}`, String(value));
+      const serialized = serializeMetadataValue(value);
+      if (serialized !== undefined) {
+        this.native.otelSpan.setAttribute(`${LangfuseOtelSpanAttributes.TRACE_METADATA}.${key}`, serialized);
+      }
     }
     return this;
   }
@@ -73,22 +109,24 @@ class ProductionTraceBackend implements TraceBackend {
   constructor(
     private readonly provider: NodeTracerProvider,
     private readonly processor: SpanProcessor,
+    private readonly secrets: readonly string[],
   ) {}
 
   start(
     name: string,
     attributes: ObservationAttributes,
-    options: { asType: ObservationType; parent?: Observation },
+    options: { asType: ObservationType; parent?: Observation; startTime?: Date },
   ): Observation {
-    const { sessionId, userId, ...observationAttributes } = attributes;
+    const maskedName = maskSecretString(name, this.secrets);
+    const { sessionId, userId, ...observationAttributes } = maskObservationAttributes(attributes, this.secrets);
     const parent = options.parent;
     const native =
       parent instanceof ProductionObservation
-        ? startChild(parent.native, name, observationAttributes, options.asType)
-        : startRoot(name, observationAttributes, options.asType);
+        ? startChild(parent.native, maskedName, observationAttributes, options.asType, options.startTime)
+        : startRoot(maskedName, observationAttributes, options.asType, options.startTime);
     applySessionId(native, sessionId);
     applyUserId(native, userId);
-    return new ProductionObservation(native);
+    return new ProductionObservation(native, this.secrets);
   }
 
   async forceFlush(): Promise<void> {
@@ -100,37 +138,58 @@ class ProductionTraceBackend implements TraceBackend {
   }
 }
 
+export async function createLangfuseRuntime(options: CreateLangfuseRuntimeOptions = {}): Promise<LangfuseRuntime> {
+  return createSharedRuntime(resolveLangfuseRuntimeConfig(options), defaultFactories);
+}
+
 export async function createProductionBackend(
   config: LangfuseConfig,
   factoryOverrides: Partial<RuntimeFactories> = {},
 ): Promise<TraceBackend> {
+  const runtime = await createSharedRuntime(resolveLangfuseRuntimeConfig({ config, env: false }), {
+    ...defaultFactories,
+    ...factoryOverrides,
+  });
+  return getLangfuseRuntimeInternal(runtime).backend;
+}
+
+async function createSharedRuntime(
+  config: ResolvedRuntimeConfig,
+  factories: RuntimeFactories,
+): Promise<LangfuseRuntime> {
   const globalRuntime = globalThis as GlobalWithRuntime;
   const fingerprint = configFingerprint(config);
   const existing = globalRuntime[RUNTIME_KEY];
+  const legacyRuntime = globalRuntime[LEGACY_RUNTIME_KEY];
+  if (legacyRuntime !== undefined && legacyRuntime !== existing) {
+    throw new Error("An older Langfuse runtime is already loaded; restart the process before enabling this version.");
+  }
   if (existing) {
-    const runtime = await existing;
-    if (runtime.shutdown) {
-      throw new Error("Langfuse tracing was already shut down; restart Pi to enable it again.");
+    if (legacyRuntime === undefined) globalRuntime[LEGACY_RUNTIME_KEY] = existing;
+    const shared = await existing;
+    if (shared.runtime.closed) {
+      throw new Error("Langfuse tracing was already shut down; restart the process to enable it again.");
     }
-    if (runtime.fingerprint !== fingerprint) {
-      throw new Error("Langfuse configuration changed; restart Pi to apply the new credentials.");
+    if (shared.fingerprint !== fingerprint) {
+      throw new Error("Langfuse configuration changed; restart the process to apply the new credentials.");
     }
-    return runtime.backend;
+    return shared.runtime;
   }
 
-  const factories = { ...defaultFactories, ...factoryOverrides };
   const initializing = initializeRuntime(config, fingerprint, factories);
   globalRuntime[RUNTIME_KEY] = initializing;
+  globalRuntime[LEGACY_RUNTIME_KEY] = initializing;
   try {
-    return (await initializing).backend;
+    return (await initializing).runtime;
   } catch (error) {
-    delete globalRuntime[RUNTIME_KEY];
+    if (globalRuntime[RUNTIME_KEY] === initializing) delete globalRuntime[RUNTIME_KEY];
+    if (globalRuntime[LEGACY_RUNTIME_KEY] === initializing) delete globalRuntime[LEGACY_RUNTIME_KEY];
     throw error;
   }
 }
 
 async function initializeRuntime(
-  config: LangfuseConfig,
+  config: ResolvedRuntimeConfig,
   fingerprint: string,
   factories: RuntimeFactories,
 ): Promise<SharedRuntime> {
@@ -143,15 +202,12 @@ async function initializeRuntime(
     await (provider?.shutdown() ?? processor.shutdown()).catch(() => undefined);
     throw error;
   }
-  const backend = new ProductionTraceBackend(provider, processor);
-  const runtime: SharedRuntime = { fingerprint, backend, shutdown: false };
-  const originalShutdown = backend.shutdown.bind(backend);
-  backend.shutdown = async () => {
-    if (runtime.shutdown) return;
-    runtime.shutdown = true;
-    await originalShutdown();
-  };
-  return runtime;
+  const runtime = getLangfuseRuntimeInternal(
+    createLangfuseRuntimeFromBackend(
+      new ProductionTraceBackend(provider, processor, [config.publicKey, config.secretKey]),
+    ),
+  );
+  return { fingerprint, runtime, shutdown: true };
 }
 
 const defaultFactories: RuntimeFactories = {
@@ -174,6 +230,102 @@ const defaultFactories: RuntimeFactories = {
   selectProvider: setLangfuseTracerProvider,
 };
 
+export function resolveLangfuseRuntimeConfig(options: CreateLangfuseRuntimeOptions): ResolvedRuntimeConfig {
+  const env = options.env === false ? undefined : (options.env ?? process.env);
+  const publicKey = requiredSetting("publicKey", options.config?.publicKey, env?.LANGFUSE_PUBLIC_KEY);
+  const secretKey = requiredSetting("secretKey", options.config?.secretKey, env?.LANGFUSE_SECRET_KEY);
+  const explicitBaseUrl = options.config?.baseUrl;
+  if (explicitBaseUrl !== undefined && !normalizeString(explicitBaseUrl)) {
+    throw new Error("Langfuse baseUrl must be a non-empty string.");
+  }
+  const rawBaseUrl = selectedSetting(explicitBaseUrl, env?.LANGFUSE_BASE_URL) ?? DEFAULT_BASE_URL;
+  const baseUrl = normalizeBaseUrl(rawBaseUrl);
+  if (!baseUrl) {
+    throw new Error("Langfuse baseUrl must use HTTP or HTTPS without credentials, a query, or a fragment.");
+  }
+  const environment = optionalSetting("environment", options.config?.environment, env?.LANGFUSE_TRACING_ENVIRONMENT);
+  if (environment && (environment.length > 40 || !/^(?!langfuse)[a-z0-9_-]+$/u.test(environment))) {
+    throw new Error(
+      "Langfuse environment must be at most 40 lowercase letters, numbers, hyphens, or underscores and must not start with langfuse.",
+    );
+  }
+  const release = optionalSetting("release", options.config?.release, env?.LANGFUSE_RELEASE);
+  return { publicKey, secretKey, baseUrl, ...(environment ? { environment } : {}), ...(release ? { release } : {}) };
+}
+
+function requiredSetting(name: string, explicit: string | undefined, environment: string | undefined): string {
+  const value = selectedSetting(explicit, environment);
+  if (!value) throw new Error(`Langfuse ${name} is required.`);
+  return value;
+}
+
+function optionalSetting(
+  name: string,
+  explicit: string | undefined,
+  environment: string | undefined,
+): string | undefined {
+  const selected = explicit !== undefined ? explicit : environment;
+  if (selected === undefined) return undefined;
+  const value = normalizeString(selected);
+  if (!value) throw new Error(`Langfuse ${name} must be a non-empty string.`);
+  return value;
+}
+
+function selectedSetting(explicit: string | undefined, environment: string | undefined): string | undefined {
+  if (explicit !== undefined) return normalizeString(explicit);
+  return normalizeString(environment);
+}
+
+function normalizeBaseUrl(value: string): string | undefined {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+    if (url.username || url.password || url.search || url.hash) return undefined;
+    return url.toString().replace(/\/+$/, "");
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function serializeMetadataValue(value: unknown): string | undefined {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+function maskObservationAttributes(
+  attributes: ObservationAttributes,
+  secrets: readonly string[],
+): ObservationAttributes {
+  return {
+    ...attributes,
+    ...(attributes.metadata ? { metadata: maskSecrets(attributes.metadata, secrets) as Record<string, unknown> } : {}),
+    ...(attributes.name ? { name: maskSecretString(attributes.name, secrets) } : {}),
+    ...(attributes.sessionId ? { sessionId: maskSecretString(attributes.sessionId, secrets) } : {}),
+    ...(attributes.userId ? { userId: maskSecretString(attributes.userId, secrets) } : {}),
+    ...(attributes.tags ? { tags: attributes.tags.map((tag) => maskSecretString(tag, secrets)) } : {}),
+    ...(attributes.statusMessage ? { statusMessage: maskSecretString(attributes.statusMessage, secrets) } : {}),
+    ...(attributes.model ? { model: maskSecretString(attributes.model, secrets) } : {}),
+    ...(attributes.version ? { version: maskSecretString(attributes.version, secrets) } : {}),
+    ...(attributes.modelParameters
+      ? {
+          modelParameters: Object.fromEntries(
+            Object.entries(attributes.modelParameters).map(([key, value]) => [
+              maskSecretString(key, secrets),
+              typeof value === "string" ? maskSecretString(value, secrets) : value,
+            ]),
+          ),
+        }
+      : {}),
+  };
+}
+
+function maskSecretString(value: string, secrets: readonly string[]): string {
+  return maskSecrets(value, secrets) as string;
+}
+
 function applySessionId(observation: LangfuseObservation, sessionId: string | undefined): void {
   if (sessionId !== undefined) {
     observation.otelSpan.setAttribute(LangfuseOtelSpanAttributes.TRACE_SESSION_ID, sessionId);
@@ -186,19 +338,25 @@ function applyUserId(observation: LangfuseObservation, userId: string | undefine
   }
 }
 
-function startRoot(name: string, attributes: ObservationAttributes, type: ObservationType): LangfuseObservation {
+function startRoot(
+  name: string,
+  attributes: ObservationAttributes,
+  type: ObservationType,
+  startTime?: Date,
+): LangfuseObservation {
   if (type === "agent") {
-    return startObservation(name, attributes as LangfuseObservationAttributes, { asType: "agent" });
+    return startObservation(name, attributes as LangfuseObservationAttributes, { asType: "agent", startTime });
   }
   if (type === "generation") {
     return startObservation(name, attributes as LangfuseObservationAttributes, {
       asType: "generation",
+      startTime,
     });
   }
   if (type === "tool") {
-    return startObservation(name, attributes as LangfuseObservationAttributes, { asType: "tool" });
+    return startObservation(name, attributes as LangfuseObservationAttributes, { asType: "tool", startTime });
   }
-  return startObservation(name, attributes as LangfuseObservationAttributes, { asType: "span" });
+  return startObservation(name, attributes as LangfuseObservationAttributes, { asType: "span", startTime });
 }
 
 function startChild(
@@ -206,28 +364,50 @@ function startChild(
   name: string,
   attributes: ObservationAttributes,
   type: ObservationType,
+  startTime?: Date,
 ): LangfuseObservation {
-  if (type === "agent") {
-    return parent.startObservation(name, attributes as LangfuseObservationAttributes, {
-      asType: "agent",
+  if (startTime) {
+    const parentSpanContext = parent.otelSpan.spanContext();
+    if (type === "agent") {
+      return startObservation(name, attributes as LangfuseObservationAttributes, {
+        asType: "agent",
+        parentSpanContext,
+        startTime,
+      });
+    }
+    if (type === "generation") {
+      return startObservation(name, attributes as LangfuseObservationAttributes, {
+        asType: "generation",
+        parentSpanContext,
+        startTime,
+      });
+    }
+    if (type === "tool") {
+      return startObservation(name, attributes as LangfuseObservationAttributes, {
+        asType: "tool",
+        parentSpanContext,
+        startTime,
+      });
+    }
+    return startObservation(name, attributes as LangfuseObservationAttributes, {
+      asType: "span",
+      parentSpanContext,
+      startTime,
     });
   }
+  if (type === "agent") {
+    return parent.startObservation(name, attributes as LangfuseObservationAttributes, { asType: "agent" });
+  }
   if (type === "generation") {
-    return parent.startObservation(name, attributes as LangfuseObservationAttributes, {
-      asType: "generation",
-    });
+    return parent.startObservation(name, attributes as LangfuseObservationAttributes, { asType: "generation" });
   }
   if (type === "tool") {
-    return parent.startObservation(name, attributes as LangfuseObservationAttributes, {
-      asType: "tool",
-    });
+    return parent.startObservation(name, attributes as LangfuseObservationAttributes, { asType: "tool" });
   }
-  return parent.startObservation(name, attributes as LangfuseObservationAttributes, {
-    asType: "span",
-  });
+  return parent.startObservation(name, attributes as LangfuseObservationAttributes, { asType: "span" });
 }
 
-function configFingerprint(config: LangfuseConfig): string {
+function configFingerprint(config: ResolvedRuntimeConfig): string {
   return createHash("sha256")
     .update(
       `${config.publicKey}\0${config.secretKey}\0${config.baseUrl}\0${config.environment ?? ""}\0${config.release ?? ""}`,
@@ -256,7 +436,10 @@ function maskSecretValue(data: unknown, secrets: readonly string[], active: Weak
       return data.map((item) => maskSecretValue(item, secrets, active));
     }
     return Object.fromEntries(
-      Object.entries(data).map(([key, value]) => [key, maskSecretValue(value, secrets, active)]),
+      Object.entries(data).map(([key, value]) => [
+        maskSecretString(key, secrets),
+        maskSecretValue(value, secrets, active),
+      ]),
     );
   } finally {
     active.delete(data);

package/src/sanitizer.ts

@@ -19,9 +19,7 @@ function sanitize(value: unknown, active: WeakSet<object>, depth: number, budget
     return consume(value, budget);
   }
   if (typeof value === "string") {
-    const bounded = truncateString(value, Math.min(MAX_STRING_LENGTH, budget.remaining));
-    const redacted = bounded.replace(BASE64_DATA_URI, BASE64_DATA_URI_OMITTED);
-    return consume(redacted, budget);
+    return consume(sanitizeString(value, Math.min(MAX_STRING_LENGTH, budget.remaining)), budget);
   }
   if (typeof value === "bigint") return consume(value.toString(), budget);
   if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol") {
@@ -72,12 +70,13 @@ function sanitize(value: unknown, active: WeakSet<object>, depth: number, budget
           omitted = true;
           break;
         }
-        budget.remaining -= keyBytes + 4;
+        const sanitizedKey = sanitizeString(key, keyBudget);
+        budget.remaining -= byteLength(sanitizedKey) + 4;
         const property = readProperty(record, key);
         if (redactData && key === "data") {
-          output[key] = consume("[base64 omitted]", budget);
-        } else if (!property.ok) output[key] = consume("[unreadable property]", budget);
-        else output[key] = sanitize(property.value, active, depth + 1, budget);
+          output[sanitizedKey] = consume("[base64 omitted]", budget);
+        } else if (!property.ok) output[sanitizedKey] = consume("[unreadable property]", budget);
+        else output[sanitizedKey] = sanitize(property.value, active, depth + 1, budget);
         processed += 1;
       }
     } catch {
@@ -115,6 +114,10 @@ function consume<T>(value: T, budget: { remaining: number }): T | string {
   return value;
 }
 
+function sanitizeString(value: string, maxBytes: number): string {
+  return truncateString(value, maxBytes).replace(BASE64_DATA_URI, BASE64_DATA_URI_OMITTED);
+}
+
 function truncateString(value: string, maxBytes: number): string {
   const boundedPrefix = value.slice(0, maxBytes);
   if (boundedPrefix.length === value.length && byteLength(boundedPrefix) <= maxBytes) {

package/src/tracing.ts

@@ -45,6 +45,7 @@ export interface ObservationAttributes {
 }
 
 export interface Observation {
+  readonly traceId?: string;
   update(attributes: ObservationAttributes): Observation;
   updateTrace?(attributes: ObservationAttributes): Observation;
   end(endTime?: number): Observation;
@@ -56,18 +57,22 @@ export interface TraceBackend {
   start(
     name: string,
     attributes: ObservationAttributes,
-    options: { asType: ObservationType; parent?: Observation },
+    options: { asType: ObservationType; parent?: Observation; startTime?: Date },
   ): Observation;
   forceFlush(): Promise<void>;
   shutdown(): Promise<void>;
 }
 
-interface RecorderContext {
+export interface TraceRecorderOptions {
   sessionId: string;
   userId?: string;
   cwd: string;
   mode: string;
   captureContent: boolean;
+  traceName?: string;
+  tags?: readonly string[];
+  metadata?: Readonly<Record<string, unknown>>;
+  onTraceId?: (traceId: string) => void;
 }
 
 interface ModelDescriptor {
@@ -97,6 +102,7 @@ interface BeginAgentInput {
   model?: ModelDescriptor;
   git?: GitMetadata;
   snapshot?: ContextSnapshot;
+  requestId?: string;
 }
 
 interface AttemptInput {
@@ -104,6 +110,7 @@ interface AttemptInput {
 }
 
 interface GenerationInput {
+  startedAt?: number;
   payload?: unknown;
   payloadStage?: "before_provider_request";
   model?: ModelDescriptor;
@@ -233,13 +240,13 @@ export class TraceRecorder {
 
   constructor(
     private readonly backend: TraceBackend,
-    private readonly context: RecorderContext,
+    private readonly context: TraceRecorderOptions,
   ) {}
 
   private startObservation(
     name: string,
     attributes: ObservationAttributes,
-    options: { asType: ObservationType; parent?: Observation },
+    options: { asType: ObservationType; parent?: Observation; startTime?: Date },
   ): Observation {
     const { sessionId, userId } = this.context;
     return this.backend.start(name, { ...attributes, sessionId, ...(userId ? { userId } : {}) }, options);
@@ -268,6 +275,7 @@ export class TraceRecorder {
       ...(hasItems(input.images) ? { images: input.images } : {}),
     });
     const metadata: Record<string, unknown> = {
+      ...customTraceMetadata(this.context.metadata),
       "pi.cwd": this.context.cwd,
       ...(input.git?.branch ? { "pi.git.branch": input.git.branch } : {}),
       ...(input.git?.commit ? { "pi.git.commit": input.git.commit } : {}),
@@ -275,6 +283,7 @@ export class TraceRecorder {
       "pi.mode": this.context.mode,
       ...(input.model?.id ? { "pi.model": input.model.id } : {}),
       ...(input.model?.provider ? { "pi.provider": input.model.provider } : {}),
+      ...(input.requestId ? { "pi.request.id": input.requestId } : {}),
       "pi.session.id": this.context.sessionId,
       "pi.trace.schema_version": Number(TRACE_SCHEMA_VERSION),
       ...snapshotMetadata("start", input.snapshot),
@@ -284,14 +293,22 @@ export class TraceRecorder {
 
     this.root = this.startObservation("pi.agent", attributes, { asType: "agent" });
     this.root.updateTrace?.({
-      name: "pi.trace",
+      name: normalizeTraceName(this.context.traceName),
       sessionId: this.context.sessionId,
       ...(this.context.userId ? { userId: this.context.userId } : {}),
       version: TRACE_SCHEMA_VERSION,
       input: traceInput,
       metadata,
-      tags: ["pi", ...(gitTag ? [gitTag] : [])],
+      tags: traceTags(this.context.tags, gitTag),
     });
+    const traceId = this.root.traceId;
+    if (traceId && this.context.onTraceId) {
+      try {
+        void Promise.resolve(this.context.onTraceId(traceId)).catch(() => undefined);
+      } catch {
+        // Host callbacks must not corrupt observation lifecycle state.
+      }
+    }
   }
 
   beginAttempt(input: AttemptInput = {}): void {
@@ -389,7 +406,11 @@ export class TraceRecorder {
         ...(Object.keys(requestMetadata).length > 0 ? { metadata: requestMetadata } : {}),
         version: TRACE_SCHEMA_VERSION,
       },
-      { asType: "generation", parent: this.turn ?? this.attempt ?? this.root },
+      {
+        asType: "generation",
+        parent: this.turn ?? this.attempt ?? this.root,
+        ...(input.startedAt === undefined ? {} : { startTime: new Date(input.startedAt) }),
+      },
     );
     this.generation = {
       observation,
@@ -613,13 +634,8 @@ export class TraceRecorder {
     this.closeActiveTrace(statusMessage, snapshot, "interrupted");
   }
 
-  async flush(): Promise<void> {
-    await this.backend.forceFlush();
-  }
-
-  async shutdown(snapshot?: ContextSnapshot): Promise<void> {
-    this.closeActiveTrace("Pi shut down before the active trace settled.", snapshot, "interrupted");
-    await this.backend.shutdown();
+  dispose(statusMessage = "Pi session ended before the active trace settled.", snapshot?: ContextSnapshot): void {
+    this.closeActiveTrace(statusMessage, snapshot, "interrupted");
   }
 
   private closeActiveTrace(statusMessage?: string, snapshot?: ContextSnapshot, forcedOutcome?: Outcome): void {
@@ -755,6 +771,28 @@ export class TraceRecorder {
   }
 }
 
+function normalizeTraceName(value: string | undefined): string {
+  return typeof value === "string" && value.trim() ? value.trim() : "pi.trace";
+}
+
+function traceTags(customTags: readonly string[] | undefined, gitTag: string | undefined): string[] {
+  const tags = ["pi", ...(gitTag ? [gitTag] : []), ...(customTags ?? [])];
+  return [...new Set(tags.map(sanitizeTraceTag).filter((tag): tag is string => tag !== undefined))];
+}
+
+function sanitizeTraceTag(value: unknown): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const sanitized = sanitizeTraceValue(value.trim());
+  return typeof sanitized === "string" && sanitized.trim() ? sanitized.trim() : undefined;
+}
+
+function customTraceMetadata(metadata: Readonly<Record<string, unknown>> | undefined): Record<string, unknown> {
+  if (!metadata) return {};
+  const sanitized = sanitizeTraceValue(metadata);
+  if (!sanitized || typeof sanitized !== "object" || Array.isArray(sanitized)) return {};
+  return Object.fromEntries(Object.entries(sanitized).filter(([key]) => !key.startsWith("pi.")));
+}
+
 function generationHttpMetadata(state: GenerationState): Record<string, unknown> {
   const finalStatus = state.statuses.at(-1);
   return {