@amaster.ai/dsh-langfuse 0.1.16 → 0.1.18

package/lib/media.js

@@ -0,0 +1,57 @@
+/** Display-only projection. The attachment service owns byte/digest validation. */
+export async function displayBlocks(content, attachments, options, signal, budget = { remaining: options.maxBytes }) {
+    return Promise.all(content.map(async (block) => {
+        if (block.type !== 'image')
+            return block;
+        const ref = block.attachment;
+        const fallback = {
+            type: 'image',
+            mediaType: ref?.mediaType,
+            bytes: ref?.bytes,
+            width: ref?.width,
+            height: ref?.height,
+            offloaded: block.offloaded,
+        };
+        if (!options.enabled ||
+            !attachments ||
+            block.offloaded ||
+            !ref ||
+            !['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(ref.mediaType) ||
+            !Number.isSafeInteger(ref.bytes) ||
+            ref.bytes <= 0 ||
+            ref.bytes > budget.remaining)
+            return fallback;
+        budget.remaining -= ref.bytes;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new Error('image display timed out')), options.timeoutMs);
+        timer.unref();
+        const readSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+        let onAbort;
+        try {
+            readSignal.throwIfAborted();
+            const aborted = new Promise((_, reject) => {
+                onAbort = () => reject(readSignal.reason);
+                readSignal.addEventListener('abort', onAbort, { once: true });
+            });
+            const { data } = await Promise.race([attachments.readImage(ref, readSignal), aborted]);
+            readSignal.throwIfAborted();
+            if (data.byteLength !== ref.bytes)
+                throw new Error('image byte length does not match its reference');
+            return {
+                type: 'image_url',
+                image_url: {
+                    url: `data:${ref.mediaType};base64,${Buffer.from(data).toString('base64')}`,
+                },
+            };
+        }
+        catch (error) {
+            console.error('[dsh-langfuse] image display failed:', error);
+            return fallback;
+        }
+        finally {
+            clearTimeout(timer);
+            if (onAbort)
+                readSignal.removeEventListener('abort', onAbort);
+        }
+    }));
+}

package/lib/types/client.d.ts

@@ -39,8 +39,21 @@ export interface LangfuseConnectionConfig {
     publicKey: string;
     secretKey: string;
     baseUrl: string;
+    redactFields?: string[];
+    environment?: string;
+    release?: string;
+    userId?: string;
+    tags?: string[];
+    captureContent?: boolean;
+    captureMedia?: boolean;
 }
 export type ObservationLevel = 'DEFAULT' | 'WARNING' | 'ERROR';
+/** Standard request context supplied by a host for one session's next trace. */
+export interface LangfuseTraceContext {
+    userId?: string;
+    tags?: string[];
+    traceparent?: string;
+}
 /** Any observation that can parent a span (trace root span or nested span/generation). */
 type Observation = LangfuseSpan | LangfuseGeneration;
 /**
@@ -52,12 +65,13 @@ type Observation = LangfuseSpan | LangfuseGeneration;
  * INCLUDES reasoning (verified in dsh-llm-deepseek@0.1.6-alpha.2:
  * `outputTokens: usage.completion_tokens`, with reasoning split out of
  * `completion_tokens_details`), so the `output` bucket subtracts
- * `reasoningTokens` into `output_reasoning`. Only `usageDetails` is sent.
+ * `reasoningTokens` into `output_reasoning_tokens`. Only `usageDetails` is sent.
  */
 export declare function usageOf(usage: TokenUsage): Record<string, number>;
 export declare class LangfuseReporter {
     private config;
     private tracing;
+    private api;
     private provider;
     /**
      * Observation → its trace's correlating attributes; children inherit their
@@ -76,6 +90,8 @@ export declare class LangfuseReporter {
     /** Settles (never rejects) once the lazy SDK import+wiring finished. */
     readonly ready: Promise<void>;
     constructor(config: LangfuseConnectionConfig);
+    /** Clone telemetry only; never mutate harness-owned messages or tool results. */
+    mask<T>(data: T): T;
     /** Dynamically import the SDK and wire the isolated export pipeline. */
     private init;
     /**
@@ -89,6 +105,7 @@ export declare class LangfuseReporter {
         name: string;
         sessionId?: string;
         metadata?: Record<string, unknown>;
+        context?: LangfuseTraceContext;
     }): LangfuseSpan | null;
     /** Open a generation (one per LLM call) under any observation parent. */
     startGeneration(parent: Observation | null, input: {
@@ -106,12 +123,13 @@ export declare class LangfuseReporter {
         level?: ObservationLevel;
         statusMessage?: string;
         metadata?: Record<string, unknown>;
-    }): void;
+    }, endedAt?: Date): void;
     /** Open a span (one per tool dispatch, or a nested detail span) under any observation parent. */
     startSpan(parent: Observation | null, input: {
         name: string;
         input?: unknown;
         metadata?: Record<string, unknown>;
+        asType?: 'tool';
     }): LangfuseSpan | null;
     /**
      * Merge fields into an open span — subagent enrichment (label, provider),
@@ -121,7 +139,7 @@ export declare class LangfuseReporter {
      * deprecated `langfuse.trace.*` attributes (setTraceIO): older Langfuse
      * servers derive the trace row's IO from exactly those keys.
      */
-    updateSpan(span: LangfuseSpan | null, update: {
+    updateSpan(span: Observation | null, update: {
         name?: string;
         input?: unknown;
         metadata?: Record<string, unknown>;
@@ -137,7 +155,7 @@ export declare class LangfuseReporter {
         level?: ObservationLevel;
         statusMessage?: string;
         metadata?: Record<string, unknown>;
-    }): void;
+    }, endedAt?: Date): void;
     /** Drain buffered spans (the `session/flush` checkpoint). */
     flush(): Promise<void>;
     /** Shut the exporter down at fiber unload (provider.shutdown flushes internally). */

package/lib/types/index.d.ts

@@ -4,11 +4,10 @@
  * Instruments the documented seams, with zero core patches:
  *
  * - `llm/stream` waterfall  → one Langfuse **generation** per LLM call
- *   (input = full request; output, token usage and finish reason collected
+ *   (input = loop-built options; output, token usage and finish reason collected
  *   from the chunk stream), plus a nested `llm-request` **span** holding the
- *   verbatim loop-built request and the collected chunk stream (the rawest
- *   request/response a plugin can observe — the provider HTTP body is
- *   assembled inside the adapter).
+ *   same options and collected chunk stream (the rawest request/response a
+ *   plugin can observe — the provider HTTP body is assembled inside the adapter).
  * - `tools/execute` waterfall → one Langfuse **span** per tool dispatch
  *   (routed to the session's trace via `exec.agent.id` — the agent/session
  *   shared identity).
@@ -31,6 +30,14 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
+import { type LangfuseTraceContext } from './client.js';
+export type { LangfuseTraceContext } from './client.js';
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /** Bind standard labels/parent context before a session's next trace starts. */
+        'langfuse/context': (sessionId: string, context: LangfuseTraceContext) => void;
+    }
+}
 export declare const name = "dsh-langfuse";
 /**
  * Waterfall listeners only need the events to exist; no hard service
@@ -47,6 +54,14 @@ export declare const Config: Schema<Schemastery.ObjectS<{
     traceName: Schema<string, string>;
     /** Include full message/tool payloads in Langfuse IO. Disable to log metadata only. */
     captureContent: Schema<boolean, boolean>;
+    redactFields: Schema<string[], string[]>;
+    userId: Schema<string, string>;
+    tags: Schema<string[], string[]>;
+    environment: Schema<string, string>;
+    release: Schema<string, string>;
+    captureMedia: Schema<boolean, boolean>;
+    maxMediaBytes: Schema<number, number>;
+    mediaTimeoutMs: Schema<number, number>;
 }>, Schemastery.ObjectT<{
     enabled: Schema<boolean, boolean>;
     publicKey: Schema<string, string>;
@@ -55,6 +70,14 @@ export declare const Config: Schema<Schemastery.ObjectS<{
     traceName: Schema<string, string>;
     /** Include full message/tool payloads in Langfuse IO. Disable to log metadata only. */
     captureContent: Schema<boolean, boolean>;
+    redactFields: Schema<string[], string[]>;
+    userId: Schema<string, string>;
+    tags: Schema<string[], string[]>;
+    environment: Schema<string, string>;
+    release: Schema<string, string>;
+    captureMedia: Schema<boolean, boolean>;
+    maxMediaBytes: Schema<number, number>;
+    mediaTimeoutMs: Schema<number, number>;
 }>>;
 export interface LangfusePluginConfig {
     enabled: boolean;
@@ -63,5 +86,13 @@ export interface LangfusePluginConfig {
     baseUrl: string;
     traceName: string;
     captureContent: boolean;
+    redactFields?: string[];
+    userId?: string;
+    tags?: string[];
+    environment?: string;
+    release?: string;
+    captureMedia?: boolean;
+    maxMediaBytes?: number;
+    mediaTimeoutMs?: number;
 }
 export declare function apply(ctx: Context, config: LangfusePluginConfig): Promise<void> | void;

package/lib/types/media.d.ts

@@ -0,0 +1,11 @@
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+export interface MediaOptions {
+    enabled: boolean;
+    maxBytes: number;
+    timeoutMs: number;
+}
+/** Display-only projection. The attachment service owns byte/digest validation. */
+export declare function displayBlocks(content: readonly ContentBlock[], attachments: AttachmentStore | undefined, options: MediaOptions, signal?: AbortSignal, budget?: {
+    remaining: number;
+}): Promise<unknown[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-langfuse",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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,15 +36,23 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-attachment": ">=0.2.0-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",
     "@deepseek-ai/dsh-session": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-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",
     "@deepseek-ai/dsh-tools": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
     "@langfuse/otel": "^5.10.1",
     "@langfuse/tracing": "^5.10.1",
+    "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-trace-node": "^2.10.0"
   },
   "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-attachment": {
+      "optional": true
+    },
     "@langfuse/otel": {
       "optional": true
     },
@@ -57,17 +65,19 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
-    "@deepseek-ai/dsh-agent": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-ptc-runtime": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-session-projection": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-subagent": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-tools": "0.2.0-rc.1",
-    "@deepseek-ai/dsh-util-time": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-util-time": "0.2.0-rc.2",
     "@langfuse/otel": "5.10.1",
     "@langfuse/tracing": "5.10.1",
     "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "0.221.0",
     "@opentelemetry/sdk-trace-node": "^2.10.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.6.3",