@amaster.ai/dsh-langfuse 0.1.30 → 0.1.31

package/README.md

@@ -63,20 +63,32 @@ Text-only generation output remains a string. When reasoning or tool calls are p
 
 Root severity follows the final turn reason: errors are `ERROR`; cancellation, blocking, token limits, and interruptions are `WARNING`. A recovered intermediate generation/tool/hook/subagent error sets `hadErrors` metadata while a successful final turn remains `DEFAULT`. This keeps retry failures visible without treating recovery as a failed turn. Outstanding tools also close as `WARNING` at unload, including calls without an agent/session; late results still reach their original callers without repeated telemetry or media reads.
 
-## Per-request labels and distributed tracing
+## Per-request metadata, labels and distributed tracing
 
-Hosts can supply standard context before a session's next trace starts:
+Hosts can supply context before a session's next trace starts:
 
 ```ts
 ctx.emit('langfuse/context', session.id, {
   userId: 'user-123',
   tags: ['support', 'experiment-b'],
+  metadata: {
+    projectId: 'project-a',
+    requestId: 'request-123',
+    experiment: { name: 'retrieval', variant: 2 },
+    labels: ['interactive'],
+  },
   traceparent: '00-1234567890abcdef1234567890abcdef-1234567890abcdef-01',
 });
 ```
 
 The typed event is exported through this package's Cordis augmentation. Context is consumed once by the next turn trace (or an out-of-turn trace created first); send it again for another request. Labels override profile defaults for that trace and propagate through generations, tools, hooks, and nested subagents. Queued context is discarded when the session is disposed or the plugin unloads. Concurrent sessions have independent context; no process-global request environment is modified.
 
+`metadata` accepts a plain JSON object with arbitrary string keys and nested values: plain objects, dense arrays, finite numbers, booleans, null and strings (including empty strings). The event validates, snapshots and masks the context immediately, so later caller mutations cannot change it. Request metadata is carried by every observation; plugin-generated fields such as `turn`, `provider`, `toolName` and `taskId` take precedence on that observation. Existing credential masking and `redactFields` apply, and explicit metadata remains available when `captureContent: false`.
+
+Non-JSON metadata rejects the entire submitted context with a diagnostic, without interrupting the agent or retaining an earlier pending context. This includes non-finite numbers, undefined, functions, symbols, BigInt, circular references, throwing getters, class instances (including Date, Map and Set), sparse arrays, extra array properties, and symbol-keyed or non-enumerable object properties. Values are never silently converted or dropped, and custom `toJSON` functions are not invoked. Omitted optional context fields remain supported. For an existing A2A task, supplying new metadata replaces its request metadata for the task root and subsequently created turns and their descendants; already-created observations retain their context.
+
+The plugin preserves JSON types in its OTLP payload. Langfuse server APIs may normalize the stored values: for example, v3's read API parses a top-level metadata string `"123"` as the number `123`.
+
 Only explicit W3C version-00 parents with non-zero trace/span IDs are joined. Invalid headers log a prefixed diagnostic and start an independent trace. Without a header the plugin always starts an independent trace. Each observation is created inside native OTEL `ROOT_CONTEXT`: foreign spans and Langfuse baggage (user/tags/metadata) are excluded, while explicit parents and plugin labels are preserved. This scoped context does not replace the host's global provider or context manager. When joining an external trace, dsh's turn is an observation under the supplied parent; the SDK's automatic app-root claim is disabled and the external owner's trace name and trace-level IO stay intact.
 
 ## Token usage and cost

package/lib/client.js

@@ -243,6 +243,16 @@ export class LangfuseReporter {
             observation.otelSpan.setAttribute('user.id', this.mask(context.userId));
         if (context.tags?.length)
             observation.otelSpan.setAttribute('langfuse.trace.tags', this.mask(context.tags));
+        if (context.metadata) {
+            // Langfuse merges the JSON object with observation.metadata.<key>
+            // attributes, giving the latter (our runtime facts) precedence. The
+            // object form also preserves null/empty strings that SDK v5's
+            // per-key serializer omits, without inheriting a parent's runtime facts.
+            // Do not also set trace.metadata: v4 gives it precedence over even
+            // observation-specific fields, which would undo that collision policy.
+            const metadata = JSON.stringify(this.mask(context.metadata));
+            observation.otelSpan.setAttribute('langfuse.observation.metadata', metadata);
+        }
         this.traceContext.set(observation, context);
     }
     /** Open a trace (one per agent turn, or one-off for session-less calls). */
@@ -263,6 +273,7 @@ export class LangfuseReporter {
                 traceName: externalParent === NO_PARENT ? input.name : undefined,
                 userId: input.context?.userId ?? this.config.userId,
                 tags: input.context?.tags ?? this.config.tags,
+                metadata: input.context?.metadata,
             });
             // External traces retain their owner's trace name and trace-level IO.
             if (externalParent === NO_PARENT) {
@@ -288,6 +299,7 @@ export class LangfuseReporter {
                 ...previous,
                 userId: context.userId ?? previous?.userId,
                 tags: context.tags ?? previous?.tags,
+                metadata: context.metadata ?? previous?.metadata,
             });
             const parent = parentContext(context.traceparent);
             if (parent !== NO_PARENT)

package/lib/index.js

@@ -192,6 +192,47 @@ function redactChunks(chunks, reporter) {
     }
     return output;
 }
+/** Validate and copy together: JSON.stringify silently rewrites non-JSON values. */
+function snapshotMetadata(metadata) {
+    const ancestors = new Set();
+    function snapshot(value) {
+        if (value === null ||
+            typeof value === 'string' ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && Number.isFinite(value)))
+            return value;
+        if (typeof value !== 'object' || ancestors.has(value))
+            throw new TypeError('Invalid metadata');
+        const array = Array.isArray(value);
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== null && prototype !== (array ? Array.prototype : Object.prototype))
+            throw new TypeError('Invalid metadata');
+        ancestors.add(value);
+        let copy;
+        if (array) {
+            // Reject holes and extra properties instead of turning them into null or dropping them.
+            if (Reflect.ownKeys(value).length !== value.length + 1)
+                throw new TypeError('Invalid metadata');
+            copy = Array.from({ length: value.length }, (_, index) => {
+                if (!Object.hasOwn(value, index))
+                    throw new TypeError('Invalid metadata');
+                return snapshot(value[index]);
+            });
+        }
+        else {
+            copy = Object.fromEntries(Reflect.ownKeys(value).map((key) => {
+                if (typeof key !== 'string' || !Object.prototype.propertyIsEnumerable.call(value, key))
+                    throw new TypeError('Invalid metadata');
+                return [key, snapshot(value[key])];
+            }));
+        }
+        ancestors.delete(value);
+        return copy;
+    }
+    if (metadata === null || typeof metadata !== 'object' || Array.isArray(metadata))
+        throw new TypeError('Invalid metadata');
+    return snapshot(metadata);
+}
 export function apply(ctx, config) {
     if (!config.enabled || /^(false|0)$/i.test(process.env.LANGFUSE_TRACING_ENABLED ?? ''))
         return;
@@ -270,10 +311,23 @@ export function apply(ctx, config) {
             await Promise.all([...pendingMedia]);
     }
     ctx.on('langfuse/context', (sessionId, context) => {
-        traceContexts.set(sessionId, {
-            ...context,
-            tags: context.tags ? [...context.tags] : undefined,
-        });
+        traceContexts.delete(sessionId);
+        try {
+            // Snapshot at submission, not trace creation: the host may reuse or
+            // mutate its request object before the next event opens the trace.
+            const { userId, tags, traceparent, metadata } = context;
+            const snapshot = {
+                userId,
+                tags,
+                traceparent,
+                metadata: metadata === undefined ? undefined : snapshotMetadata(metadata),
+            };
+            traceContexts.set(sessionId, reporter.mask(JSON.parse(JSON.stringify(snapshot))));
+        }
+        catch {
+            // Never include caller data or serialization errors in diagnostics.
+            console.error('[dsh-langfuse] invalid request context; ignoring context');
+        }
     });
     function openTrace(sessionId, metadata, startTime) {
         const context = sessionId ? traceContexts.get(sessionId) : undefined;

package/lib/types/client.d.ts

@@ -53,6 +53,8 @@ export interface LangfuseTraceContext {
     userId?: string;
     tags?: string[];
     traceparent?: string;
+    /** Strict JSON request dimensions inherited by every observation; non-JSON values reject context. */
+    metadata?: Record<string, unknown>;
 }
 /** Any observation that can parent a span (trace root span or nested span/generation). */
 type Observation = LangfuseSpan | LangfuseGeneration;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-langfuse",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "Langfuse observability plugin for DeepSeek Harness: one generation per LLM call with a nested llm-request span, one span per tool call, one trace per session turn, subagent child sessions nested under the parent's tree.",
   "type": "module",
   "main": "lib/index.js",