@amaster.ai/dsh-langfuse 0.1.38 → 0.1.40

package/README.md

@@ -37,7 +37,7 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
         baseUrl: https://cloud.langfuse.com
         traceName: dsh-turn
         captureContent: true            # set false to record metadata only
-        maxPayloadBytes: 262144          # per-LLM-call request/raw/output cap (256 KiB)
+        maxPayloadBytes: 262144          # LLM payload and tool IO cap (256 KiB)
         userId: developer
         tags: [coding, experiment-a]
         environment: development
@@ -50,11 +50,11 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
 
 Explicit profile values take precedence over environment variables. Empty credentials/base URL fall back to `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, and `LANGFUSE_BASE_URL` (then the EU cloud URL). `userId` falls back to `LANGFUSE_USER_ID`. Empty environment/release values use the SDK's `LANGFUSE_TRACING_ENVIRONMENT` / `LANGFUSE_RELEASE` defaults. `LANGFUSE_TRACING_ENABLED=false` (or `0`) overrides the profile master switch; environment keys alone do not enable the plugin.
 
-Buffered spans drain on `session/flush(session)`; the exporter shuts down with the plugin fiber. Both checkpoints await pending display projections. Unload also closes outstanding model calls with their collected partial content/usage and marks incomplete calls `WARNING`, including calls whose stream was never consumed; the original stream can still settle without ending those observations twice. Attachment reads run in the background and never delay the agent's chunk stream or tool return value; a read that exceeds its deadline degrades to image metadata, even if the backend ignores cancellation. The SDK's `LANGFUSE_FLUSH_AT`, `LANGFUSE_FLUSH_INTERVAL`, and `LANGFUSE_TIMEOUT` control exporter batching and network timeouts.
+Buffered spans drain on `session/flush(session)`; the exporter shuts down with the plugin fiber. A session checkpoint awaits its own pending display projections, including descendant-session work already attached to its trace; unrelated sessions do not delay it. Session-less projections are included at any checkpoint. Unload drains all pending projections. The SDK exporter remains shared by the plugin. Unload also closes outstanding model calls with their collected partial content/usage and marks incomplete calls `WARNING`, including calls whose stream was never consumed; the original stream can still settle without ending those observations twice. Attachment reads run in the background and never delay the agent's chunk stream or tool return value; a read that exceeds its deadline degrades to image metadata, even if the backend ignores cancellation. The SDK's `LANGFUSE_FLUSH_AT`, `LANGFUSE_FLUSH_INTERVAL`, and `LANGFUSE_TIMEOUT` control exporter batching and network timeouts.
 
 With `captureContent: true`, both `llm-call` and `llm-request` inputs contain every `llm/stream` request option except the non-serializable `AbortSignal`. New request fields pass through without a plugin update. For image-bearing requests, generation input is updated to a display projection; `llm-request` retains the original attachment references. Langfuse's separate generation `modelParameters` attribute summarizes the known sampling fields; it is not part of either request input. These are dsh-side values, not exact provider HTTP payloads: adapters may add defaults, project messages/tools, or rename fields after this seam. With `captureContent: false`, the collector keeps chunk/tool-call counts and usage without buffering text, reasoning, tool arguments, or raw chunks; inputs keep structural counts while the separate `modelParameters` attribute keeps safe parameter metadata; reply excerpts, reasoning, tool arguments/results, error text, and media are withheld from observation names and IO.
 
-`maxPayloadBytes` independently bounds each captured request, raw chunk stream, and assembled output per LLM call (default 256 KiB). Oversized requests become a bounded preview; oversized streams retain only fitting chunks/prefixes and set `metadata.truncated`. These limits apply only to telemetry copies: forwarded chunks and original messages/results stay unchanged. Session disposal closes that session's active LLM/tool observations; a child whose activation rolls back before `subagent/start` closes immediately, while an already-started child still closes at `subagent/end`.
+`maxPayloadBytes` independently bounds each captured request, raw chunk stream, and assembled output per LLM call, and each tool input, output, and error status message (default 256 KiB). Span updates and endings also bound IO at the reporter boundary, including ordinary turn roots and A2A task roots; the legacy trace IO attributes receive the same bounded values. Oversized structured payloads become a bounded preview; oversized streams retain only fitting chunks/prefixes and set `metadata.truncated`. Oversized tool error status messages are omitted while severity and `metadata.truncated` remain available. These limits apply only to telemetry copies: forwarded chunks and original messages/results stay unchanged. Session disposal closes that session's active LLM/tool observations; a child whose activation rolls back before `subagent/start` closes immediately, while an already-started child still closes at `subagent/end`.
 
 Configured Langfuse credentials and `pk-lf-*` / `sk-lf-*` values are redacted across reporter payloads, names, status messages, and labels. `redactFields` replaces matching payload fields recursively, including JSON-encoded arguments, ignoring case. Name excerpts are derived after redaction. Delta blocks are also checked as assembled text so fragmented credentials cannot bypass the mask: affected blocks keep their record count/type/index, with sanitized text in the first delta and later deltas cleared. Redaction only changes telemetry copies; original messages/results and the forwarded stream stay intact. The exporter applies the same mask to IO and metadata as a final safeguard. User/tags are explicit metadata and remain when content capture is off.
 
@@ -62,7 +62,7 @@ Configured Langfuse credentials and `pk-lf-*` / `sk-lf-*` values are redacted ac
 
 Text-only generation output remains a string. When reasoning or tool calls are present, output uses the Langfuse chat format: `role: "assistant"`, optional `content`, `thinking` blocks, and `tool_calls` with the original call ID and function arguments. This renders thinking and invoked tools in the formatted preview. The original reasoning deltas remain in the nested `llm-request` output; no extra generation is created.
 
-`captureMedia: true` requires content capture and an available `ctx.attachments` service (`@deepseek-ai/dsh-attachment >=0.2.0-rc.1`). Prompt, generation-input, and tool-output image references are read through that service and converted to data URIs for the SDK's media uploader. Install the attachment bundle appropriate to the deployment; the plugin does not instantiate a storage backend. Missing/failed reads, offloaded images, unsupported MIME types, oversized images, and disabled media fall back to MIME/size/dimension metadata. A generation's byte budget covers all messages in that request. Observation end times are captured when the model, tool, or turn completes; delayed image reads do not extend business latency. `LANGFUSE_MEDIA_UPLOAD_ENABLED=false` (or `0`) overrides media capture. Verbatim file references remain metadata; their bytes are not uploaded.
+`captureMedia: true` requires content capture and an available `ctx.attachments` service (`@deepseek-ai/dsh-attachment >=0.2.0-rc.1 || >=0.2.2-rc.1`). Prompt, generation-input, and tool-output image references are read through that service and converted to data URIs for the SDK's media uploader. Install the attachment bundle appropriate to the deployment; the plugin does not instantiate a storage backend. Missing/failed reads, offloaded images, unsupported MIME types, oversized images, and disabled media fall back to MIME/size/dimension metadata. A generation's byte budget covers all messages in that request. Observation end times are captured when the model, tool, or turn completes; delayed image reads do not extend business latency. `LANGFUSE_MEDIA_UPLOAD_ENABLED=false` (or `0`) overrides media capture. Verbatim file references remain metadata; their bytes are not uploaded.
 
 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.
 

package/lib/client.js

@@ -33,6 +33,7 @@
  * before readiness are still dropped — a window that cannot exist once the
  * plugin fiber has been awaited.
  */
+import { boundPayload, newPayloadBudget } from './payload.js';
 /**
  * OTEL's canonical invalid span context as a literal (a static
  * `INVALID_SPAN_CONTEXT` import would load @opentelemetry/api eagerly, even
@@ -419,7 +420,13 @@ export class LangfuseReporter {
         if (!span)
             return;
         try {
-            update = this.mask(update);
+            const budget = newPayloadBudget(this.config.maxPayloadBytes ?? 256 * 1024);
+            const input = update.input === undefined ? undefined : boundPayload(update.input, budget, this);
+            update = this.mask({
+                ...update,
+                input,
+                ...(budget.truncated ? { metadata: { ...update.metadata, truncated: true } } : {}),
+            });
             span.update({ input: update.input, metadata: update.metadata });
             if (update.name)
                 span.otelSpan.updateName(update.name);
@@ -441,7 +448,13 @@ export class LangfuseReporter {
         if (!span)
             return;
         try {
-            update = this.mask(update);
+            const budget = newPayloadBudget(this.config.maxPayloadBytes ?? 256 * 1024);
+            const output = update.output === undefined ? undefined : boundPayload(update.output, budget, this);
+            update = this.mask({
+                ...update,
+                output,
+                ...(budget.truncated ? { metadata: { ...update.metadata, truncated: true } } : {}),
+            });
             span.update(update);
             if (update.output !== undefined && this.roots.has(span)) {
                 span.setTraceIO({ output: update.output });

package/lib/index.js

@@ -35,6 +35,7 @@ import Schema from '@deepseek-ai/schemastery';
 import { LangfuseReporter } from './client.js';
 import { isHookInvoked, isHookResult } from './hooks.js';
 import { displayBlocks } from './media.js';
+import { boundPayload, newPayloadBudget, takePayloadText } from './payload.js';
 export { appendHookEvent } from './hooks.js';
 export const name = 'dsh-langfuse';
 /**
@@ -58,7 +59,7 @@ export const Config = Schema.object({
         .min(1)
         .step(1)
         .default(256 * 1024)
-        .description('maximum captured request, raw-stream, and assembled-output bytes per LLM call'),
+        .description('maximum captured request, raw-stream, assembled-output, or tool input/output/status bytes'),
     redactFields: Schema.array(Schema.string())
         .default([])
         .description('case-insensitive payload fields to redact'),
@@ -130,195 +131,6 @@ function requestBodyOf(options, captureContent) {
     const { signal: _, ...body } = options;
     return body;
 }
-const newPayloadBudget = (maxBytes) => ({
-    remaining: maxBytes,
-    truncated: false,
-});
-/** Take a UTF-8 prefix without ever exceeding the remaining content-byte budget. */
-function takePayloadText(value, budget) {
-    const bytes = Buffer.byteLength(value);
-    if (bytes <= budget.remaining) {
-        budget.remaining -= bytes;
-        return value;
-    }
-    budget.truncated = true;
-    if (budget.remaining <= 0)
-        return '';
-    let low = 0;
-    let high = value.length;
-    while (low < high) {
-        const middle = Math.ceil((low + high) / 2);
-        if (Buffer.byteLength(value.slice(0, middle)) <= budget.remaining)
-            low = middle;
-        else
-            high = middle - 1;
-    }
-    budget.remaining = 0;
-    return value.slice(0, low);
-}
-/** Build a preview whose complete JSON value, including its wrapper, fits the remaining cap. */
-function previewPayload(serialized, budget) {
-    const remaining = budget.remaining;
-    const marker = { truncated: true };
-    const withPreview = { ...marker, preview: '' };
-    if (Buffer.byteLength(JSON.stringify(withPreview)) <= remaining) {
-        let low = 0;
-        let high = serialized.length;
-        while (low < high) {
-            const middle = Math.ceil((low + high) / 2);
-            const candidate = { ...marker, preview: serialized.slice(0, middle) };
-            if (Buffer.byteLength(JSON.stringify(candidate)) <= remaining)
-                low = middle;
-            else
-                high = middle - 1;
-        }
-        budget.remaining = 0;
-        return { ...marker, preview: serialized.slice(0, low) };
-    }
-    if (Buffer.byteLength(JSON.stringify(marker)) <= remaining) {
-        budget.remaining = 0;
-        return marker;
-    }
-    // Even the marker is too large: retain a plain string prefix, still capped
-    // after JSON quoting/escaping rather than by source-string bytes.
-    let low = 0;
-    let high = serialized.length;
-    while (low < high) {
-        const middle = Math.ceil((low + high) / 2);
-        if (Buffer.byteLength(JSON.stringify(serialized.slice(0, middle))) <= remaining)
-            low = middle;
-        else
-            high = middle - 1;
-    }
-    budget.remaining = 0;
-    return low > 0 ? serialized.slice(0, low) : remaining >= 2 ? '' : 0;
-}
-const MAX_ATOMIC_MASK_BYTES = 64 * 1024;
-/** Redact leaves while serializing, so an oversized payload never needs a full mask or stringify. */
-function boundMaskedPayload(input, budget, reporter) {
-    const seen = new WeakSet();
-    const parts = [];
-    let remaining = budget.remaining;
-    let overflow = false;
-    const append = (text) => {
-        if (overflow || text === undefined)
-            return;
-        const bytes = Buffer.byteLength(text);
-        if (bytes > remaining) {
-            // The node was already masked atomically; a serialized prefix is safe.
-            parts.push(takePayloadText(text, { remaining, truncated: true }));
-            remaining = 0;
-            overflow = true;
-            return;
-        }
-        parts.push(text);
-        remaining -= bytes;
-    };
-    const write = (value) => {
-        if (overflow || value === undefined)
-            return undefined;
-        if (value === null || typeof value !== 'object' || value instanceof Date) {
-            if (typeof value === 'string' &&
-                Buffer.byteLength(value) > MAX_ATOMIC_MASK_BYTES &&
-                Buffer.byteLength(value) > remaining) {
-                overflow = true;
-                return undefined;
-            }
-            const masked = reporter.mask(value);
-            append(JSON.stringify(masked));
-            return masked;
-        }
-        if (seen.has(value)) {
-            append(JSON.stringify('[Circular]'));
-            return '[Circular]';
-        }
-        seen.add(value);
-        if (Array.isArray(value)) {
-            append('[');
-            const result = [];
-            for (const [index, item] of value.entries()) {
-                if (overflow)
-                    break;
-                if (index > 0)
-                    append(',');
-                if (item === undefined) {
-                    append('null');
-                    result.push(null);
-                }
-                else {
-                    const masked = write(item);
-                    if (!overflow)
-                        result.push(masked);
-                }
-            }
-            append(']');
-            seen.delete(value);
-            return result;
-        }
-        append('{');
-        const result = Object.create(null);
-        let first = true;
-        for (const key in value) {
-            if (overflow)
-                break;
-            if (!Object.hasOwn(value, key))
-                continue;
-            const child = value[key];
-            if (child === undefined && !reporter.shouldRedactField(key))
-                continue;
-            if (!first)
-                append(',');
-            first = false;
-            append(JSON.stringify(reporter.mask(key)));
-            append(':');
-            if (reporter.shouldRedactField(key)) {
-                append(JSON.stringify('[REDACTED]'));
-                result[key] = '[REDACTED]';
-            }
-            else {
-                const masked = write(child);
-                if (!overflow)
-                    result[key] = masked;
-            }
-        }
-        append('}');
-        seen.delete(value);
-        return result;
-    };
-    try {
-        const masked = write(input);
-        if (!overflow) {
-            budget.remaining = remaining;
-            return masked;
-        }
-    }
-    catch {
-        budget.truncated = true;
-        return previewPayload('', budget);
-    }
-    budget.truncated = true;
-    return previewPayload(parts.join(''), budget);
-}
-/** Bound a structured payload without changing its shape when it fits. */
-function boundPayload(input, budget, reporter) {
-    if (reporter)
-        return boundMaskedPayload(input, budget, reporter);
-    let serialized;
-    try {
-        serialized = JSON.stringify(input) ?? '';
-    }
-    catch {
-        budget.truncated = true;
-        return previewPayload('', budget);
-    }
-    const bytes = Buffer.byteLength(serialized);
-    if (bytes <= budget.remaining) {
-        budget.remaining -= bytes;
-        return input;
-    }
-    budget.truncated = true;
-    return previewPayload(serialized, budget);
-}
 /** Keep only whole chunks that fit; stream accounting still processes every original chunk. */
 function capturePayloadChunk(chunk, chunks, budget) {
     if (budget.remaining <= 0) {
@@ -530,7 +342,7 @@ export function apply(ctx, config) {
     const openOperations = new Set();
     const operationSessions = new Map();
     const traceContexts = new Map();
-    const pendingMedia = new Set();
+    const pendingMedia = new Map();
     const mediaFor = new WeakMap();
     const mediaOptions = {
         enabled: config.captureContent &&
@@ -539,36 +351,55 @@ export function apply(ctx, config) {
         maxBytes: config.maxMediaBytes ?? 5 * 1024 * 1024,
         timeoutMs: config.mediaTimeoutMs ?? 5000,
     };
-    function trackMedia(task) {
+    function mediaSessions(sessionId) {
+        const owners = [];
+        while (sessionId && !owners.includes(sessionId)) {
+            owners.push(sessionId);
+            sessionId = children.get(sessionId)?.parentSessionId;
+        }
+        return owners;
+    }
+    function trackMedia(task, owners) {
         const pending = task.catch((error) => {
             console.error('[dsh-langfuse] media finalization failed:', error);
         });
-        pendingMedia.add(pending);
+        pendingMedia.set(pending, owners);
         void pending.then(() => pendingMedia.delete(pending));
         return pending;
     }
-    function enrichInput(handle, input) {
+    function enrichInput(handle, input, sessionId) {
         if (!handle)
             return;
-        mediaFor.set(handle, trackMedia(input.then((value) => reporter.updateSpan(handle, { input: value }))));
+        const owners = mediaSessions(sessionId);
+        mediaFor.set(handle, {
+            pending: trackMedia(input.then((value) => reporter.updateSpan(handle, { input: value })), owners),
+            sessions: owners,
+        });
     }
     function afterMedia(handle, close, endedAt = new Date()) {
         const task = handle ? mediaFor.get(handle) : undefined;
         if (task)
-            trackMedia(task.then(() => close(endedAt)));
+            trackMedia(task.pending.then(() => close(endedAt)), task.sessions);
         else
             close(endedAt);
     }
-    function setMessageInput(handle, content) {
+    function setMessageInput(handle, content, sessionId) {
         if (content.some((block) => block.type !== 'text')) {
-            enrichInput(handle, displayBlocks(content, ctx.get('attachments'), mediaOptions));
+            enrichInput(handle, displayBlocks(content, ctx.get('attachments'), mediaOptions), sessionId);
         }
         else
             reporter.updateSpan(handle, { input: messageText({ content }) });
     }
-    async function drainMedia() {
-        while (pendingMedia.size)
-            await Promise.all([...pendingMedia]);
+    async function drainMedia(sessionId) {
+        for (;;) {
+            // Session-less observations have no narrower durability checkpoint.
+            const pending = [...pendingMedia]
+                .filter(([, owners]) => !sessionId || !owners.length || owners.includes(sessionId))
+                .map(([task]) => task);
+            if (!pending.length)
+                return;
+            await Promise.all(pending);
+        }
     }
     ctx.on('langfuse/context', (sessionId, context) => {
         traceContexts.delete(sessionId);
@@ -1100,7 +931,7 @@ export function apply(ctx, config) {
             // The delegated prompt (the child's first user/message) is the
             // subagent span's input; the descriptor enriches the span name.
             if (event.type === 'user/message' && !child.hasInput && config.captureContent) {
-                setMessageInput(child.span, event.data.content);
+                setMessageInput(child.span, event.data.content, sessionId);
                 child.hasInput = true;
             }
             else if (event.type === 'subagent/descriptor') {
@@ -1141,7 +972,7 @@ export function apply(ctx, config) {
                     traceFor(sessionId);
                 const state = sessions.get(sessionId);
                 if (state && !state.hasInput && config.captureContent) {
-                    setMessageInput(state.trace, event.data.content);
+                    setMessageInput(state.trace, event.data.content, sessionId);
                     state.hasInput = true;
                 }
                 break;
@@ -1264,7 +1095,7 @@ export function apply(ctx, config) {
                 const enriched = boundPayload({ ...requestBody, messages }, enrichmentBudget, reporter);
                 requestBudget.truncated ||= enrichmentBudget.truncated;
                 return enriched;
-            }));
+            }), options.sessionId);
         }
         // The rawest request a plugin can observe: the loop-built GenerateOptions
         // verbatim, pre-adapter (the provider HTTP body is assembled inside the
@@ -1469,7 +1300,11 @@ export function apply(ctx, config) {
         // it — it rides this dispatch's (same one-off rule as llm/stream).
         const oneOffRoot = sessionId ? null : parent;
         // Argument summaries are argument content — they ride captureContent.
-        const args = config.captureContent ? reporter.mask(exec.arguments) : undefined;
+        const maxPayloadBytes = config.maxPayloadBytes ?? 256 * 1024;
+        const inputBudget = newPayloadBudget(maxPayloadBytes);
+        const args = config.captureContent
+            ? boundPayload(exec.arguments, inputBudget, reporter)
+            : undefined;
         const argSummary = config.captureContent ? toolCallSummary(args) : undefined;
         const span = reporter.startSpan(parent, {
             name: `tool:${exec.name}${argSummary ? ` [${argSummary}]` : ''}`,
@@ -1510,14 +1345,31 @@ export function apply(ctx, config) {
                     openToolSpans.delete(sessionId);
             }
             const end = (output = update.output) => {
-                reporter.endSpan(span, { ...update, output }, endedAt);
+                const outputBudget = newPayloadBudget(maxPayloadBytes);
+                const bounded = output === undefined ? undefined : boundPayload(output, outputBudget, reporter);
+                const statusBudget = newPayloadBudget(maxPayloadBytes);
+                const status = update.statusMessage === undefined
+                    ? undefined
+                    : boundPayload(update.statusMessage, statusBudget, reporter);
+                reporter.endSpan(span, {
+                    ...update,
+                    output: bounded,
+                    statusMessage: typeof status === 'string' ? status : undefined,
+                    metadata: {
+                        ...update.metadata,
+                        truncated: inputBudget.truncated ||
+                            outputBudget.truncated ||
+                            statusBudget.truncated ||
+                            undefined,
+                    },
+                }, endedAt);
                 reporter.endSpan(oneOffRoot, {}, endedAt);
             };
             if (display)
                 trackMedia(display.then(end).catch((error) => {
                     console.error('[dsh-langfuse] media projection failed:', error);
                     end();
-                }));
+                }), mediaSessions(sessionId));
             else
                 end();
         }
@@ -1548,8 +1400,8 @@ export function apply(ctx, config) {
         toolResults.get(exec)?.(result);
     });
     // Durability checkpoint: the store awaits every session/flush listener.
-    ctx.on('session/flush', async () => {
-        await drainMedia();
+    ctx.on('session/flush', async (session) => {
+        await drainMedia(session.id);
         await reporter.flush();
     });
     // Lifecycle: this cordis fork has no ready/dispose events — cleanup rides

package/lib/payload.js

@@ -0,0 +1,189 @@
+export const newPayloadBudget = (maxBytes) => ({
+    remaining: maxBytes,
+    truncated: false,
+});
+/** Take a UTF-8 prefix without ever exceeding the remaining content-byte budget. */
+export function takePayloadText(value, budget) {
+    const bytes = Buffer.byteLength(value);
+    if (bytes <= budget.remaining) {
+        budget.remaining -= bytes;
+        return value;
+    }
+    budget.truncated = true;
+    if (budget.remaining <= 0)
+        return '';
+    let low = 0;
+    let high = value.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(value.slice(0, middle)) <= budget.remaining)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    budget.remaining = 0;
+    return value.slice(0, low);
+}
+/** Build a preview whose complete JSON value, including its wrapper, fits the remaining cap. */
+function previewPayload(serialized, budget) {
+    const remaining = budget.remaining;
+    const marker = { truncated: true };
+    const withPreview = { ...marker, preview: '' };
+    if (Buffer.byteLength(JSON.stringify(withPreview)) <= remaining) {
+        let low = 0;
+        let high = serialized.length;
+        while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            const candidate = { ...marker, preview: serialized.slice(0, middle) };
+            if (Buffer.byteLength(JSON.stringify(candidate)) <= remaining)
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        budget.remaining = 0;
+        return { ...marker, preview: serialized.slice(0, low) };
+    }
+    if (Buffer.byteLength(JSON.stringify(marker)) <= remaining) {
+        budget.remaining = 0;
+        return marker;
+    }
+    // Even the marker is too large: retain a plain string prefix, still capped
+    // after JSON quoting/escaping rather than by source-string bytes.
+    let low = 0;
+    let high = serialized.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(JSON.stringify(serialized.slice(0, middle))) <= remaining)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    budget.remaining = 0;
+    return low > 0 ? serialized.slice(0, low) : remaining >= 2 ? '' : 0;
+}
+const MAX_ATOMIC_MASK_BYTES = 64 * 1024;
+/** Redact leaves while serializing, so an oversized payload never needs a full mask or stringify. */
+function boundMaskedPayload(input, budget, reporter) {
+    const seen = new WeakSet();
+    const parts = [];
+    let remaining = budget.remaining;
+    let overflow = false;
+    const append = (text) => {
+        if (overflow || text === undefined)
+            return;
+        const bytes = Buffer.byteLength(text);
+        if (bytes > remaining) {
+            // The node was already masked atomically; a serialized prefix is safe.
+            parts.push(takePayloadText(text, { remaining, truncated: true }));
+            remaining = 0;
+            overflow = true;
+            return;
+        }
+        parts.push(text);
+        remaining -= bytes;
+    };
+    const write = (value) => {
+        if (overflow || value === undefined)
+            return undefined;
+        if (value === null || typeof value !== 'object' || value instanceof Date) {
+            if (typeof value === 'string' &&
+                Buffer.byteLength(value) > MAX_ATOMIC_MASK_BYTES &&
+                Buffer.byteLength(value) > remaining) {
+                overflow = true;
+                return undefined;
+            }
+            const masked = reporter.mask(value);
+            append(JSON.stringify(masked));
+            return masked;
+        }
+        if (seen.has(value)) {
+            append(JSON.stringify('[Circular]'));
+            return '[Circular]';
+        }
+        seen.add(value);
+        if (Array.isArray(value)) {
+            append('[');
+            const result = [];
+            for (const [index, item] of value.entries()) {
+                if (overflow)
+                    break;
+                if (index > 0)
+                    append(',');
+                if (item === undefined) {
+                    append('null');
+                    result.push(null);
+                }
+                else {
+                    const masked = write(item);
+                    if (!overflow)
+                        result.push(masked);
+                }
+            }
+            append(']');
+            seen.delete(value);
+            return result;
+        }
+        append('{');
+        const result = Object.create(null);
+        let first = true;
+        for (const key in value) {
+            if (overflow)
+                break;
+            if (!Object.hasOwn(value, key))
+                continue;
+            const child = value[key];
+            if (child === undefined && !reporter.shouldRedactField(key))
+                continue;
+            if (!first)
+                append(',');
+            first = false;
+            append(JSON.stringify(reporter.mask(key)));
+            append(':');
+            if (reporter.shouldRedactField(key)) {
+                append(JSON.stringify('[REDACTED]'));
+                result[key] = '[REDACTED]';
+            }
+            else {
+                const masked = write(child);
+                if (!overflow)
+                    result[key] = masked;
+            }
+        }
+        append('}');
+        seen.delete(value);
+        return result;
+    };
+    try {
+        const masked = write(input);
+        if (!overflow) {
+            budget.remaining = remaining;
+            return masked;
+        }
+    }
+    catch {
+        budget.truncated = true;
+        return previewPayload('', budget);
+    }
+    budget.truncated = true;
+    return previewPayload(parts.join(''), budget);
+}
+/** Bound a structured payload without changing its shape when it fits. */
+export function boundPayload(input, budget, reporter) {
+    if (reporter)
+        return boundMaskedPayload(input, budget, reporter);
+    let serialized;
+    try {
+        serialized = JSON.stringify(input) ?? '';
+    }
+    catch {
+        budget.truncated = true;
+        return previewPayload('', budget);
+    }
+    const bytes = Buffer.byteLength(serialized);
+    if (bytes <= budget.remaining) {
+        budget.remaining -= bytes;
+        return input;
+    }
+    budget.truncated = true;
+    return previewPayload(serialized, budget);
+}

package/lib/types/client.d.ts

@@ -46,6 +46,7 @@ export interface LangfuseConnectionConfig {
     tags?: string[];
     captureContent?: boolean;
     captureMedia?: boolean;
+    maxPayloadBytes?: number;
 }
 export type ObservationLevel = 'DEFAULT' | 'WARNING' | 'ERROR';
 /** Standard request context supplied by a host for one session's next trace. */

package/lib/types/payload.d.ts

@@ -0,0 +1,15 @@
+import type { LangfuseReporter } from './client.js';
+export interface PayloadBudget {
+    remaining: number;
+    truncated: boolean;
+}
+export declare const newPayloadBudget: (maxBytes: number) => PayloadBudget;
+/** Take a UTF-8 prefix without ever exceeding the remaining content-byte budget. */
+export declare function takePayloadText(value: string, budget: PayloadBudget): string;
+type BoundedPayload<T> = T | {
+    truncated: true;
+    preview?: string;
+} | string | number;
+/** Bound a structured payload without changing its shape when it fits. */
+export declare function boundPayload<T>(input: T, budget: PayloadBudget, reporter?: LangfuseReporter): BoundedPayload<T>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-langfuse",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "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",
@@ -36,11 +36,11 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-attachment": ">=0.2.0-rc.1 || >=0.2.1-rc.1",
-    "@deepseek-ai/dsh-llm": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1",
-    "@deepseek-ai/dsh-session": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1",
-    "@deepseek-ai/dsh-subagent": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1",
-    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1",
+    "@deepseek-ai/dsh-attachment": ">=0.2.0-rc.1 || >=0.2.1-rc.1 || >=0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1 || >=0.2.2-rc.1",
+    "@deepseek-ai/dsh-session": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1 || >=0.2.2-rc.1",
+    "@deepseek-ai/dsh-subagent": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1 || >=0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1 || >=0.2.2-rc.1",
     "@langfuse/otel": "^5.10.1",
     "@langfuse/tracing": "^5.10.1",
     "@opentelemetry/api": "^1.9.0",
@@ -64,17 +64,17 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.5",
-    "@deepseek-ai/dsh-agent": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-attachment": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-hook-protocol": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-llm": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-session": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-session-projection": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-subagent": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-tools": "0.2.1-rc.5",
-    "@deepseek-ai/dsh-util-time": "0.2.1-rc.5",
+    "@deepseek-ai/cordis": "4.1.0",
+    "@deepseek-ai/dsh-agent": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-attachment": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-hook-protocol": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-session-projection": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-subagent": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-util-time": "0.2.2-rc.1",
     "@langfuse/otel": "5.10.1",
     "@langfuse/tracing": "5.10.1",
     "@opentelemetry/api": "^1.9.1",
@@ -82,7 +82,8 @@
     "@opentelemetry/sdk-trace-node": "^2.10.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.6.3",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "@deepseek-ai/dsh-tool-executor-native": "0.2.2-rc.1"
   },
   "engines": {
     "node": "^20.19 || ^22.12 || >=24.0"