pi-langfuse 1.5.6 → 1.5.8

package/README.md

@@ -104,6 +104,27 @@ export LANGFUSE_CAPTURE_CWD=false
 
 All captured payloads are redacted before upload. The extension masks common API keys, bearer tokens, passwords, cookies, private keys, Langfuse keys, GitHub/npm/AWS-style tokens, and local absolute paths.
 
+### Payload limits
+
+Before upload, payloads are shaped: strings are truncated and deeply nested or
+very wide structures are trimmed. These caps keep traces small and protect the
+Langfuse ingestion pipeline. Override any of them (no rebuild needed):
+
+```bash
+export PI_LANGFUSE_MAX_STRING_LENGTH=12000       # per-string chars (system prompt, inputs)
+export PI_LANGFUSE_MAX_TOOL_PAYLOAD_LENGTH=24000 # per tool input/output chars
+export PI_LANGFUSE_MAX_DEPTH=6                    # max nesting depth
+export PI_LANGFUSE_MAX_ARRAY_ITEMS=50            # max array elements kept
+export PI_LANGFUSE_MAX_OBJECT_KEYS=80            # max object keys kept
+export PI_LANGFUSE_MAX_PAYLOAD_NODES=2000        # max total nodes per payload
+```
+
+Set any limit to `0`, `off`, `none`, or `unlimited` to disable that cap
+entirely (captures the full value). Unset or invalid values fall back to the
+defaults shown above. To capture a very large system prompt or big tool
+payloads in full, raise or disable the relevant limit (e.g.
+`PI_LANGFUSE_MAX_STRING_LENGTH=off`).
+
 ### Method 3: Persistent `config.json`
 
 Create or update `~/.pi/agent/pi-langfuse/config.json`:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-langfuse",
-	"version": "1.5.6",
+	"version": "1.5.8",
 	"description": "Langfuse extension for Pi coding agent",
 	"repository": {
 		"type": "git",

package/src/config.ts

@@ -5,6 +5,7 @@ import { CONFIG_PATH, DEFAULT_LANGFUSE_HOST } from "./constants.js";
 import { state } from "./state.js";
 import { forceShutdownRuntime } from "./langfuse.js";
 import { createCapturePolicy, type EnvLike } from "./capture-policy.js";
+import { createPayloadLimits } from "./limits.js";
 
 export function loadConfigFromFile(path = CONFIG_PATH, env: EnvLike = process.env as EnvLike): Config | null {
   if (existsSync(path)) {
@@ -22,6 +23,7 @@ export function loadConfigFromFile(path = CONFIG_PATH, env: EnvLike = process.en
           secretKey: config.secretKey,
           host: config.host || DEFAULT_LANGFUSE_HOST,
           capturePolicy: createCapturePolicy(captureSource),
+          limits: createPayloadLimits(env),
         };
       }
     } catch (e) {
@@ -44,6 +46,7 @@ export function loadConfigFromEnv(env: EnvLike = process.env as EnvLike): Config
     secretKey,
     host: env.LANGFUSE_BASE_URL || env.LANGFUSE_HOST || DEFAULT_LANGFUSE_HOST,
     capturePolicy: createCapturePolicy(env),
+    limits: createPayloadLimits(env),
   };
 }
 

package/src/handlers/agent.ts

@@ -1,7 +1,7 @@
 import { state, resetRunState, computeEvaluationScores } from "../state.js";
 import { getRuntime, sendScore } from "../langfuse.js";
 import { ensureConfig } from "../config.js";
-import { shapePayload, truncate, extractFinalAssistant, extractAssistantOutput, getCapturePolicy } from "../utils.js";
+import { shapePayload, truncate, extractFinalAssistant, extractAssistantOutput, getCapturePolicy, getLimits } from "../utils.js";
 import { closeDanglingObservations } from "./tool.js";
 import { applyCapturePolicy } from "../capture-policy.js";
 import { collectSourceMetadata } from "../source-metadata.js";
@@ -79,7 +79,7 @@ export async function startAgentRun(event: Record<string, unknown>, ctx: any) {
           ...(state.currentProvider ? { provider: state.currentProvider } : {}),
           sessionId: state.currentSessionId || undefined,
         },
-        systemPrompt: systemPrompt ? truncate(String(systemPrompt), 20000) : undefined,
+        systemPrompt: systemPrompt ? truncate(String(systemPrompt), getLimits().maxString) : undefined,
       },
       getCapturePolicy(),
     );

package/src/handlers/tool.ts

@@ -10,8 +10,8 @@ import {
   truncate,
   estimatePayloadBytes,
   getCapturePolicy,
+  getLimits,
 } from "../utils.js";
-import { MAX_TOOL_PAYLOAD_LENGTH } from "../constants.js";
 import { applyCapturePolicy } from "../capture-policy.js";
 import { redactString } from "../redaction.js";
 
@@ -28,7 +28,7 @@ export async function startToolObservation(event: Record<string, unknown>) {
   try {
     const toolName = getToolName(event);
     const toolInput = getToolInput(event);
-    const shapedInput = shapePayload(toolInput, { maxString: MAX_TOOL_PAYLOAD_LENGTH });
+    const shapedInput = shapePayload(toolInput, { maxString: getLimits().maxToolPayload });
     const captured = applyCapturePolicy(
       {
         toolInput: shapedInput,
@@ -36,7 +36,7 @@ export async function startToolObservation(event: Record<string, unknown>) {
       },
       getCapturePolicy(),
     );
-    const inputBytes = estimatePayloadBytes(captured.toolInput, MAX_TOOL_PAYLOAD_LENGTH);
+    const inputBytes = estimatePayloadBytes(captured.toolInput, getLimits().maxToolPayload);
     const parent = state.agentState.activeTurn ?? state.agentState.root;
     const tool = await startChildObservation({
       parent,
@@ -79,7 +79,7 @@ export async function finishToolObservation(event: Record<string, unknown>) {
 
   const isError = Boolean(event.isError ?? event.error ?? event.status === "error");
   const output =
-    extractTextContent(event.content, MAX_TOOL_PAYLOAD_LENGTH) ??
+    extractTextContent(event.content, getLimits().maxToolPayload) ??
     event.output ??
     event.result ??
     event.error ??
@@ -87,7 +87,7 @@ export async function finishToolObservation(event: Record<string, unknown>) {
     event;
 
   try {
-    const shapedOutput = shapePayload(output, { maxString: MAX_TOOL_PAYLOAD_LENGTH });
+    const shapedOutput = shapePayload(output, { maxString: getLimits().maxToolPayload });
     const captured = applyCapturePolicy(
       {
         toolOutput: shapedOutput,
@@ -99,7 +99,7 @@ export async function finishToolObservation(event: Record<string, unknown>) {
       },
       getCapturePolicy(),
     );
-    const outputBytes = estimatePayloadBytes(captured.toolOutput, MAX_TOOL_PAYLOAD_LENGTH);
+    const outputBytes = estimatePayloadBytes(captured.toolOutput, getLimits().maxToolPayload);
     const durationMs = Math.max(0, Date.now() - activeTool.startedAt);
 
     activeTool.observation

package/src/langfuse.ts

@@ -1,4 +1,4 @@
-import type { LangfuseRuntime, LangfuseScoreClient } from "./types.js";
+import type { LangfuseRuntime, LangfuseScoreClient, PendingScore } from "./types.js";
 import { state } from "./state.js";
 import { randomUUID } from "node:crypto";
 
@@ -60,6 +60,11 @@ interface RestFallbackStore {
 const OTEL_VISIBILITY_TIMEOUT_MS = 1_500;
 const OTEL_VISIBILITY_POLL_INTERVAL_MS = 200;
 const DEFAULT_SHUTDOWN_STEP_TIMEOUT_MS = 2_000;
+const DEFAULT_LANGFUSE_REQUEST_TIMEOUT_SECONDS = 5;
+const DEFAULT_SCORE_FLUSH_AT = 10;
+const DEFAULT_SCORE_FLUSH_INTERVAL_MS = 1_000;
+const MAX_SCORE_QUEUE_SIZE = 100_000;
+const MAX_SCORE_BATCH_SIZE = 100;
 
 let shutdownStepTimeoutMs = DEFAULT_SHUTDOWN_STEP_TIMEOUT_MS;
 
@@ -67,8 +72,27 @@ function nowIso() {
   return new Date().toISOString();
 }
 
-function delay(ms: number) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function resolvePositiveEnvNumber(name: string, fallback: number, integer = false): number {
+  const parsed = Number(process.env[name]);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return integer ? Math.floor(parsed) : parsed;
+}
+
+function delay(ms: number, signal?: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+
+    const timeout = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timeout);
+      reject(signal.reason);
+    }, { once: true });
+  });
 }
 
 function debugLog(message: string) {
@@ -107,7 +131,14 @@ export function getLastRuntimeError(): { scope: string; message: string; timesta
   return lastRuntimeError;
 }
 
-async function withTimeout<T>(label: string, operation: Promise<T> | undefined): Promise<T | undefined> {
+async function withShutdownDeadline<T>(label: string, startOperation: () => Promise<T> | undefined, deadline: number): Promise<T | undefined> {
+  const remainingMs = deadline - Date.now();
+  if (remainingMs <= 0) {
+    debugLog(`📊 Langfuse: Skipped ${label}; shutdown deadline elapsed`);
+    return undefined;
+  }
+
+  const operation = startOperation();
   if (!operation) {
     return undefined;
   }
@@ -118,9 +149,9 @@ async function withTimeout<T>(label: string, operation: Promise<T> | undefined):
       operation,
       new Promise<undefined>((resolve) => {
         timeout = setTimeout(() => {
-          debugLog(`📊 Langfuse: ${label} timed out after ${shutdownStepTimeoutMs}ms`);
+          debugLog(`📊 Langfuse: ${label} timed out; shutdown deadline elapsed`);
           resolve(undefined);
-        }, shutdownStepTimeoutMs);
+        }, remainingMs);
       }),
     ]);
   } finally {
@@ -130,6 +161,142 @@ async function withTimeout<T>(label: string, operation: Promise<T> | undefined):
   }
 }
 
+function getRuntimeConfig(rt: LangfuseRuntime) {
+  return rt.runtimeConfig ?? state.config;
+}
+
+function ingestionHeaders(rt: LangfuseRuntime): Record<string, string> {
+  const config = getRuntimeConfig(rt);
+  if (!config) {
+    throw new Error("Langfuse runtime config is unavailable");
+  }
+
+  const auth = Buffer.from(`${config.publicKey}:${config.secretKey}`).toString("base64");
+  return {
+    Authorization: `Basic ${auth}`,
+    "Content-Type": "application/json",
+  };
+}
+
+async function ingestBatch(rt: LangfuseRuntime, batch: unknown[], signal: AbortSignal): Promise<unknown[]> {
+  const config = getRuntimeConfig(rt);
+  if (!config) {
+    throw new Error("Langfuse runtime config is unavailable");
+  }
+
+  const response = await fetch(`${config.host.replace(/\/$/, "")}/api/public/ingestion`, {
+    method: "POST",
+    headers: ingestionHeaders(rt),
+    body: JSON.stringify({ batch }),
+    signal,
+  });
+  if (!response.ok) {
+    throw new Error(`Langfuse ingestion failed with HTTP ${response.status}`);
+  }
+
+  const text = await response.text();
+  if (!text) {
+    return [];
+  }
+
+  const responseBody = JSON.parse(text) as { errors?: unknown[] };
+  return Array.isArray(responseBody.errors) ? responseBody.errors : [];
+}
+
+async function flushPendingScores(rt: LangfuseRuntime, signal: AbortSignal): Promise<void> {
+  const pendingScores = rt.pendingScores;
+  if (!pendingScores || pendingScores.length === 0) {
+    return;
+  }
+
+  while (pendingScores.length > 0) {
+    const scores = pendingScores.slice(0, MAX_SCORE_BATCH_SIZE);
+    try {
+      const errors = await ingestBatch(
+        rt,
+        scores.map((score) => ({
+          type: "score-create",
+          id: randomUUID(),
+          timestamp: nowIso(),
+          body: score,
+        })),
+        signal,
+      );
+      pendingScores.splice(0, scores.length);
+      if (errors.length > 0) {
+        rememberRuntimeError("score ingestion", new Error(JSON.stringify(errors)));
+        console.warn("📊 Langfuse: Score ingestion reported errors", errors);
+      }
+    } catch (error) {
+      if ((error as { name?: string }).name !== "AbortError") {
+        rememberRuntimeError("score ingestion", error);
+        console.warn("📊 Langfuse: Failed to flush scores", error);
+      }
+      return;
+    }
+  }
+}
+
+function clearScoreFlushTimer(rt: LangfuseRuntime) {
+  if (rt.scoreFlushTimer) {
+    clearTimeout(rt.scoreFlushTimer);
+    rt.scoreFlushTimer = undefined;
+  }
+}
+
+function scheduleScoreFlush(rt: LangfuseRuntime) {
+  if (
+    rt.scoreFlushStopped
+    || rt.scoreFlushTimer
+    || rt.scoreFlushPromise
+    || !rt.pendingScores?.length
+  ) {
+    return;
+  }
+
+  rt.scoreFlushTimer = setTimeout(() => {
+    rt.scoreFlushTimer = undefined;
+    void startScoreFlush(rt);
+  }, rt.scoreFlushIntervalMs ?? DEFAULT_SCORE_FLUSH_INTERVAL_MS);
+  rt.scoreFlushTimer.unref?.();
+}
+
+function startScoreFlush(rt: LangfuseRuntime): Promise<void> {
+  if (rt.scoreFlushPromise) {
+    return rt.scoreFlushPromise;
+  }
+
+  clearScoreFlushTimer(rt);
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort(new DOMException("Langfuse score request timed out", "AbortError")),
+    rt.scoreRequestTimeoutMs ?? DEFAULT_LANGFUSE_REQUEST_TIMEOUT_SECONDS * 1_000,
+  );
+  timeout.unref?.();
+  rt.scoreFlushController = controller;
+
+  const promise = flushPendingScores(rt, controller.signal).finally(() => {
+    clearTimeout(timeout);
+    if (rt.scoreFlushPromise === promise) {
+      rt.scoreFlushPromise = undefined;
+    }
+    if (rt.scoreFlushController === controller) {
+      rt.scoreFlushController = undefined;
+    }
+    scheduleScoreFlush(rt);
+  });
+  rt.scoreFlushPromise = promise;
+  return promise;
+}
+
+function stopScoreFlush(rt: LangfuseRuntime) {
+  rt.scoreFlushStopped = true;
+  clearScoreFlushTimer(rt);
+  rt.scoreFlushController?.abort(
+    new DOMException("Langfuse score flushing stopped", "AbortError"),
+  );
+}
+
 function toIso(value: unknown): string | undefined {
   if (!value) {
     return undefined;
@@ -258,27 +425,40 @@ function wrapObservation(
   };
 }
 
-async function traceExists(rt: LangfuseRuntime, traceId: string): Promise<boolean> {
+async function traceExists(rt: LangfuseRuntime, traceId: string, signal: AbortSignal): Promise<boolean> {
+  const config = getRuntimeConfig(rt);
+  if (!config) {
+    return false;
+  }
+
   try {
-    const traceApi = rt.scoreClient.api?.trace;
-    if (!traceApi?.get) {
+    const response = await fetch(
+      `${config.host.replace(/\/$/, "")}/api/public/traces/${encodeURIComponent(traceId)}`,
+      {
+        headers: ingestionHeaders(rt),
+        signal,
+      },
+    );
+    if (response.status === 404) {
       return false;
     }
-    const trace = await withTimeout("Trace visibility check", traceApi.get(traceId));
-    if (!trace) {
-      return false;
+    if (!response.ok) {
+      throw new Error(`Langfuse trace visibility check failed with HTTP ${response.status}`);
     }
     return true;
-  } catch {
+  } catch (error) {
+    if (signal.aborted) {
+      throw error;
+    }
     return false;
   }
 }
 
-async function waitForTraceVisibility(rt: LangfuseRuntime, traceId: string): Promise<boolean> {
+async function waitForTraceVisibility(rt: LangfuseRuntime, traceId: string, signal: AbortSignal): Promise<boolean> {
   const deadline = Date.now() + OTEL_VISIBILITY_TIMEOUT_MS;
 
   while (true) {
-    if (await traceExists(rt, traceId)) {
+    if (await traceExists(rt, traceId, signal)) {
       return true;
     }
 
@@ -287,7 +467,7 @@ async function waitForTraceVisibility(rt: LangfuseRuntime, traceId: string): Pro
       return false;
     }
 
-    await delay(Math.min(OTEL_VISIBILITY_POLL_INTERVAL_MS, remainingMs));
+    await delay(Math.min(OTEL_VISIBILITY_POLL_INTERVAL_MS, remainingMs), signal);
   }
 }
 
@@ -295,14 +475,14 @@ function eventTimestamp(record: { endTime?: string; startTime?: string; timestam
   return record.endTime ?? record.startTime ?? record.timestamp ?? nowIso();
 }
 
-async function fallbackToRestIngestion(rt: LangfuseRuntime) {
+async function fallbackToRestIngestion(rt: LangfuseRuntime, signal: AbortSignal) {
   const store = rt.restFallback as RestFallbackStore | undefined;
   if (!store?.trace || store.attempted) {
     return;
   }
   store.attempted = true;
 
-  if (await waitForTraceVisibility(rt, store.trace.id)) {
+  if (await waitForTraceVisibility(rt, store.trace.id, signal)) {
     return;
   }
 
@@ -355,31 +535,7 @@ async function fallbackToRestIngestion(rt: LangfuseRuntime) {
     });
   }
 
-  const ingestionApi = rt.scoreClient.api?.ingestion;
-  if (!ingestionApi?.batch) {
-    debugLog("📊 Langfuse: REST fallback ingestion is unavailable");
-    return;
-  }
-
-  const response = await withTimeout(
-    "REST fallback ingestion",
-    ingestionApi.batch({
-      batch,
-      metadata: {
-        source: "pi-langfuse",
-        fallback: "rest-ingestion",
-        reason: "otel-trace-not-visible-after-flush",
-      },
-    }),
-  );
-
-  if (!response) {
-    return;
-  }
-
-  const responseBody = response as { errors?: unknown[] } | undefined;
-  const responseErrors = responseBody?.errors;
-  const errors = Array.isArray(responseErrors) ? responseErrors : [];
+  const errors = await ingestBatch(rt, batch, signal);
   if (errors.length > 0) {
     rememberRuntimeError("REST fallback ingestion", new Error(JSON.stringify(errors)));
     console.warn("📊 Langfuse: REST fallback ingestion reported errors", errors);
@@ -426,6 +582,11 @@ export async function getRuntime(): Promise<LangfuseRuntime> {
 
     try {
       ensureOtelContextManager(context, AsyncHooksContextManager);
+      const scoreFlushAt = resolvePositiveEnvNumber("LANGFUSE_FLUSH_AT", DEFAULT_SCORE_FLUSH_AT, true);
+      const scoreFlushIntervalMs =
+        resolvePositiveEnvNumber("LANGFUSE_FLUSH_INTERVAL", DEFAULT_SCORE_FLUSH_INTERVAL_MS / 1_000) * 1_000;
+      const scoreRequestTimeoutMs =
+        resolvePositiveEnvNumber("LANGFUSE_TIMEOUT", DEFAULT_LANGFUSE_REQUEST_TIMEOUT_SECONDS) * 1_000;
       const spanProcessor = new LangfuseSpanProcessor({
         publicKey: state.config.publicKey,
         secretKey: state.config.secretKey,
@@ -449,6 +610,16 @@ export async function getRuntime(): Promise<LangfuseRuntime> {
         tracerProvider,
         clearTracerProvider: () => tracing.setLangfuseTracerProvider(null),
         restFallback,
+        pendingScores: [],
+        scoreFlushAt,
+        scoreFlushIntervalMs,
+        scoreRequestTimeoutMs,
+        scoreFlushStopped: false,
+        runtimeConfig: {
+          publicKey: state.config.publicKey,
+          secretKey: state.config.secretKey,
+          host: state.config.host,
+        },
       };
       lastRuntimeError = null;
     } catch (e) {
@@ -468,17 +639,36 @@ function doShutdownRuntime(): Promise<void> {
 
     const rt = runtime;
     runtime = null;
+    const deadline = Date.now() + shutdownStepTimeoutMs;
+    const controller = new AbortController();
+    const abortTimeout = setTimeout(() => controller.abort(), shutdownStepTimeoutMs);
+    stopScoreFlush(rt);
 
     try {
-      await withTimeout("OTel force flush", rt.tracerProvider?.forceFlush?.());
-      await fallbackToRestIngestion(rt);
-      await withTimeout("Langfuse score flush", rt.scoreClient.flush?.());
-      await withTimeout("Langfuse client shutdown", rt.scoreClient.shutdown?.());
-      await withTimeout("OTel tracer shutdown", rt.tracerProvider?.shutdown?.());
+      await withShutdownDeadline(
+        "Active score flush",
+        () => rt.scoreFlushPromise,
+        deadline,
+      );
+      await withShutdownDeadline("OTel force flush", () => rt.tracerProvider?.forceFlush?.(), deadline);
+      await withShutdownDeadline(
+        "REST fallback ingestion",
+        () => fallbackToRestIngestion(rt, controller.signal),
+        deadline,
+      );
+      await flushPendingScores(rt, controller.signal);
+      await withShutdownDeadline("Langfuse score flush", () => rt.scoreClient.flush?.(), deadline);
+      await withShutdownDeadline("Langfuse client shutdown", () => rt.scoreClient.shutdown?.(), deadline);
+      await withShutdownDeadline("OTel tracer shutdown", () => rt.tracerProvider?.shutdown?.(), deadline);
     } catch (e) {
       rememberRuntimeError("runtime shutdown", e);
       console.warn("📊 Langfuse: Failed to flush/shutdown cleanly", e);
     } finally {
+      clearTimeout(abortTimeout);
+      clearScoreFlushTimer(rt);
+      rt.scoreFlushController?.abort();
+      rt.scoreFlushController = undefined;
+      rt.scoreFlushPromise = undefined;
       if (!runtime) {
         rt.clearTracerProvider?.();
       }
@@ -516,7 +706,13 @@ export async function forceShutdownRuntime(): Promise<void> {
 }
 
 export function __setRuntimeForTest(rt: LangfuseRuntime | null, timeoutMs = DEFAULT_SHUTDOWN_STEP_TIMEOUT_MS): void {
+  if (runtime && runtime !== rt) {
+    stopScoreFlush(runtime);
+  }
   runtime = rt;
+  if (rt) {
+    rt.scoreFlushStopped = false;
+  }
   shutdownStepTimeoutMs = timeoutMs;
   activeSessions.clear();
 }
@@ -524,14 +720,35 @@ export function __setRuntimeForTest(rt: LangfuseRuntime | null, timeoutMs = DEFA
 export async function sendScore(name: string, value: number, options: { traceId?: string; observationId?: string } = {}) {
   try {
     const rt = await getRuntime();
-    rt.scoreClient.score?.create({
+    const score: PendingScore = {
       name,
       value,
       dataType: name === "session_had_errors" || name === "tool_is_error" ? "BOOLEAN" : "NUMERIC",
       traceId: options.traceId,
       observationId: options.observationId,
       sessionId: options.traceId ? undefined : state.currentSessionId || undefined,
-    });
+      ...(process.env.LANGFUSE_TRACING_ENVIRONMENT
+        ? { environment: process.env.LANGFUSE_TRACING_ENVIRONMENT }
+        : {}),
+    };
+    if (!rt.pendingScores) {
+      return;
+    }
+    if (rt.pendingScores.length >= MAX_SCORE_QUEUE_SIZE) {
+      const error = new Error(
+        `Langfuse score queue is full (${MAX_SCORE_QUEUE_SIZE}); dropping score`,
+      );
+      rememberRuntimeError("score queue", error);
+      console.warn(`📊 Langfuse: ${error.message}`);
+      return;
+    }
+
+    rt.pendingScores.push(score);
+    if (rt.pendingScores.length >= (rt.scoreFlushAt ?? DEFAULT_SCORE_FLUSH_AT)) {
+      void startScoreFlush(rt);
+    } else {
+      scheduleScoreFlush(rt);
+    }
   } catch (e) {
     rememberRuntimeError(`score ${name}`, e);
     console.warn(`📊 Langfuse: Failed to send score ${name}`, e);

package/src/limits.ts

@@ -0,0 +1,97 @@
+import {
+  MAX_ARRAY_ITEMS,
+  MAX_DEPTH,
+  MAX_OBJECT_KEYS,
+  MAX_PAYLOAD_NODES,
+  MAX_STRING_LENGTH,
+  MAX_TOOL_PAYLOAD_LENGTH,
+} from "./constants.js";
+import type { EnvLike } from "./capture-policy.js";
+import { state } from "./state.js";
+
+/**
+ * Payload-shaping limits. Every field is a positive integer, or
+ * `Number.POSITIVE_INFINITY` to disable that limit entirely (capture everything).
+ * Resolved once from the environment and stored on the loaded config; consumers
+ * read the resolved values via `getLimits()` rather than the raw constants.
+ */
+export interface PayloadLimits {
+  /** Max characters kept per captured string (generation/agent inputs, outputs, system prompt). */
+  readonly maxString: number;
+  /** Max characters kept for tool inputs/outputs (their payloads run larger than chat strings). */
+  readonly maxToolPayload: number;
+  /** Max nesting depth walked when shaping a structured payload. */
+  readonly maxDepth: number;
+  /** Max array elements kept per array. */
+  readonly maxArrayItems: number;
+  /** Max own-keys kept per object. */
+  readonly maxObjectKeys: number;
+  /** Max total nodes visited across a whole payload before bailing with `[payload too large]`. */
+  readonly maxNodes: number;
+}
+
+export const DEFAULT_LIMITS: PayloadLimits = {
+  maxString: MAX_STRING_LENGTH,
+  maxToolPayload: MAX_TOOL_PAYLOAD_LENGTH,
+  maxDepth: MAX_DEPTH,
+  maxArrayItems: MAX_ARRAY_ITEMS,
+  maxObjectKeys: MAX_OBJECT_KEYS,
+  maxNodes: MAX_PAYLOAD_NODES,
+};
+
+/** Words that mean "no limit" when supplied as an env value. */
+const UNLIMITED_WORDS = new Set(["off", "none", "false", "no", "unlimited", "inf", "infinity"]);
+
+/**
+ * Parse one limit env value.
+ * - unset / blank / unparseable  -> `fallback` (the built-in default)
+ * - "off"/"none"/"unlimited"/... or a value <= 0 -> `Infinity` (limit removed)
+ * - a positive number -> that integer
+ */
+export function parseLimit(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) {
+    return fallback;
+  }
+  const trimmed = raw.trim().toLowerCase();
+  if (trimmed === "") {
+    return fallback;
+  }
+  if (UNLIMITED_WORDS.has(trimmed)) {
+    return Number.POSITIVE_INFINITY;
+  }
+  const parsed = Number(trimmed);
+  if (!Number.isFinite(parsed)) {
+    return fallback;
+  }
+  if (parsed <= 0) {
+    return Number.POSITIVE_INFINITY;
+  }
+  return Math.floor(parsed);
+}
+
+/**
+ * Resolve payload limits from the environment. Each `PI_LANGFUSE_MAX_*` var overrides
+ * the corresponding default; set any to `0`/`off`/`unlimited` to remove that limit.
+ * Namespaced `PI_LANGFUSE_*` (not `LANGFUSE_*`) to avoid clashing with Langfuse
+ * server env vars such as `LANGFUSE_MAX_EVENT_SIZE_BYTES`.
+ */
+export function createPayloadLimits(env: EnvLike = process.env as EnvLike): PayloadLimits {
+  return {
+    maxString: parseLimit(env.PI_LANGFUSE_MAX_STRING_LENGTH, DEFAULT_LIMITS.maxString),
+    maxToolPayload: parseLimit(env.PI_LANGFUSE_MAX_TOOL_PAYLOAD_LENGTH, DEFAULT_LIMITS.maxToolPayload),
+    maxDepth: parseLimit(env.PI_LANGFUSE_MAX_DEPTH, DEFAULT_LIMITS.maxDepth),
+    maxArrayItems: parseLimit(env.PI_LANGFUSE_MAX_ARRAY_ITEMS, DEFAULT_LIMITS.maxArrayItems),
+    maxObjectKeys: parseLimit(env.PI_LANGFUSE_MAX_OBJECT_KEYS, DEFAULT_LIMITS.maxObjectKeys),
+    maxNodes: parseLimit(env.PI_LANGFUSE_MAX_PAYLOAD_NODES, DEFAULT_LIMITS.maxNodes),
+  };
+}
+
+/**
+ * Resolved limits for the current session: the config-loaded values when a
+ * config is active, otherwise a fresh resolve from the environment. Every
+ * capture/redaction path reads limits through this so a single env change
+ * (or config) governs truncation everywhere.
+ */
+export function getLimits(): PayloadLimits {
+  return state.config?.limits ?? createPayloadLimits();
+}

package/src/redaction.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { getLimits } from "./limits.js";
 
 export const REDACTED = "[REDACTED_SECRET]";
 
@@ -9,12 +10,15 @@ export interface RedactOptions {
   maxStringLength: number;
 }
 
-const DEFAULT_OPTIONS: RedactOptions = {
-  maxDepth: 6,
-  maxArrayItems: 50,
-  maxObjectKeys: 80,
-  maxStringLength: 12_000,
-};
+function defaultOptions(): RedactOptions {
+  const limits = getLimits();
+  return {
+    maxDepth: limits.maxDepth,
+    maxArrayItems: limits.maxArrayItems,
+    maxObjectKeys: limits.maxObjectKeys,
+    maxStringLength: limits.maxString,
+  };
+}
 
 const SECRET_ASSIGNMENT_RE =
   /\b([A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|PASS|API[_-]?KEY|PRIVATE[_-]?KEY|AUTH|COOKIE)[A-Z0-9_]*)\s*=\s*([^\s"'`]+)/gi;
@@ -36,7 +40,7 @@ function truncate(value: string, maxStringLength: number): string {
 }
 
 export function redactString(value: string, options: Partial<RedactOptions> = {}): string {
-  const merged = { ...DEFAULT_OPTIONS, ...options };
+  const merged = { ...defaultOptions(), ...options };
   const truncated = truncate(value, merged.maxStringLength);
   return truncated
     .replace(PRIVATE_KEY_RE, REDACTED)
@@ -110,6 +114,6 @@ function visit(value: unknown, options: RedactOptions, depth: number, seen: Weak
 }
 
 export function redactValue(value: unknown, options: Partial<RedactOptions> = {}): unknown {
-  const merged: RedactOptions = { ...DEFAULT_OPTIONS, ...options };
+  const merged: RedactOptions = { ...defaultOptions(), ...options };
   return visit(value, merged, merged.maxDepth, new WeakSet<object>());
 }

package/src/types.ts

@@ -1,10 +1,12 @@
 import type { CapturePolicy } from "./capture-policy.js";
+import type { PayloadLimits } from "./limits.js";
 
 export interface Config {
   publicKey: string;
   secretKey: string;
   host: string;
   capturePolicy?: CapturePolicy;
+  limits?: PayloadLimits;
 }
 
 export interface LangfuseObservation {
@@ -57,6 +59,22 @@ export interface LangfuseScoreClient {
   shutdown?: () => Promise<void>;
 }
 
+export interface PendingScore {
+  traceId?: string;
+  sessionId?: string;
+  observationId?: string;
+  name: string;
+  value: number;
+  dataType?: "NUMERIC" | "BOOLEAN";
+  environment?: string;
+}
+
+export interface LangfuseRuntimeConfig {
+  publicKey: string;
+  secretKey: string;
+  host: string;
+}
+
 export interface LangfuseRuntime {
   startObservation: (
     name: string,
@@ -77,6 +95,15 @@ export interface LangfuseRuntime {
   tracerProvider?: { forceFlush?: () => Promise<void>; shutdown?: () => Promise<void> };
   clearTracerProvider?: () => void;
   restFallback?: unknown;
+  pendingScores?: PendingScore[];
+  scoreFlushAt?: number;
+  scoreFlushIntervalMs?: number;
+  scoreRequestTimeoutMs?: number;
+  scoreFlushTimer?: NodeJS.Timeout;
+  scoreFlushPromise?: Promise<void>;
+  scoreFlushController?: AbortController;
+  scoreFlushStopped?: boolean;
+  runtimeConfig?: LangfuseRuntimeConfig;
 }
 
 export interface GenerationState {

package/src/utils.ts

@@ -1,11 +1,4 @@
-import {
-  MAX_ARRAY_ITEMS,
-  MAX_DEPTH,
-  MAX_OBJECT_KEYS,
-  MAX_PAYLOAD_NODES,
-  MAX_STRING_LENGTH,
-  MAX_TOOL_PAYLOAD_LENGTH,
-} from "./constants.js";
+import { getLimits } from "./limits.js";
 import { createCapturePolicy, type CapturePolicy } from "./capture-policy.js";
 import { redactValue } from "./redaction.js";
 import { state } from "./state.js";
@@ -14,7 +7,9 @@ export function getCapturePolicy(): CapturePolicy {
   return state.config?.capturePolicy ?? createCapturePolicy();
 }
 
-export function truncate(value: string, maxLength = MAX_STRING_LENGTH): string {
+export { getLimits };
+
+export function truncate(value: string, maxLength = getLimits().maxString): string {
   return value.length > maxLength ? `${value.slice(0, maxLength)}... [truncated]` : value;
 }
 
@@ -35,11 +30,22 @@ const PAYLOAD_TOO_LARGE = "[payload too large]";
 
 export function shapePayload(
   value: unknown,
-  options: { maxString?: number; depth?: number; maxNodes?: number; redact?: boolean; parseJson?: boolean } = {},
+  options: {
+    maxString?: number;
+    depth?: number;
+    maxNodes?: number;
+    maxArrayItems?: number;
+    maxObjectKeys?: number;
+    redact?: boolean;
+    parseJson?: boolean;
+  } = {},
 ): unknown {
-  const maxString = options.maxString ?? MAX_STRING_LENGTH;
-  const depth = options.depth ?? MAX_DEPTH;
-  const maxNodes = options.maxNodes ?? MAX_PAYLOAD_NODES;
+  const limits = getLimits();
+  const maxString = options.maxString ?? limits.maxString;
+  const depth = options.depth ?? limits.maxDepth;
+  const maxNodes = options.maxNodes ?? limits.maxNodes;
+  const maxArrayItems = options.maxArrayItems ?? limits.maxArrayItems;
+  const maxObjectKeys = options.maxObjectKeys ?? limits.maxObjectKeys;
   const budget = { exhausted: false, nodeCount: 0 };
 
   function visit(item: unknown, remainingDepth: number, seen: WeakSet<object>): unknown {
@@ -88,7 +94,7 @@ export function shapePayload(
 
     if (Array.isArray(item)) {
       const output: unknown[] = [];
-      const limit = Math.min(item.length, MAX_ARRAY_ITEMS);
+      const limit = Math.min(item.length, maxArrayItems);
       for (let index = 0; index < limit; index++) {
         output.push(visit(item[index], remainingDepth - 1, seen));
         if (budget.exhausted) {
@@ -120,7 +126,7 @@ export function shapePayload(
         }
         output[key] = visit((item as Record<string, unknown>)[key], remainingDepth - 1, seen);
         keyCount++;
-        if (budget.exhausted || keyCount >= MAX_OBJECT_KEYS) {
+        if (budget.exhausted || keyCount >= maxObjectKeys) {
           break;
         }
       }
@@ -136,12 +142,12 @@ export function shapePayload(
     : redactValue(shaped, {
         maxDepth: depth,
         maxStringLength: maxString,
-        maxArrayItems: MAX_ARRAY_ITEMS,
-        maxObjectKeys: MAX_OBJECT_KEYS,
+        maxArrayItems,
+        maxObjectKeys,
       });
 }
 
-export function safeSerialize(value: unknown, maxLength = MAX_TOOL_PAYLOAD_LENGTH): string {
+export function safeSerialize(value: unknown, maxLength = getLimits().maxToolPayload): string {
   try {
     return truncate(JSON.stringify(shapePayload(value, { maxString: maxLength }), null, 2), maxLength);
   } catch {
@@ -149,7 +155,7 @@ export function safeSerialize(value: unknown, maxLength = MAX_TOOL_PAYLOAD_LENGT
   }
 }
 
-export function estimatePayloadBytes(value: unknown, maxLength = MAX_TOOL_PAYLOAD_LENGTH): number {
+export function estimatePayloadBytes(value: unknown, maxLength = getLimits().maxToolPayload): number {
   return new TextEncoder().encode(safeSerialize(value, maxLength)).length;
 }