@amaster.ai/dsh-langfuse 0.1.25 → 0.1.27

package/lib/client.js

@@ -252,18 +252,23 @@ export class LangfuseReporter {
         if (!tracing || !api)
             return null;
         try {
-            const parent = parentContext(input.context?.traceparent);
+            const externalParent = parentContext(input.context?.traceparent);
+            const parent = externalParent === NO_PARENT && input.traceId
+                ? { traceId: input.traceId, spanId: '0000000000000001', traceFlags: 1 }
+                : externalParent;
             input = this.mask(input);
-            const root = api.context.with(api.ROOT_CONTEXT, () => tracing.startObservation(input.name, { metadata: input.metadata }, { parentSpanContext: parent }));
+            const root = api.context.with(api.ROOT_CONTEXT, () => tracing.startObservation(input.name, { metadata: input.metadata }, { parentSpanContext: parent, startTime: input.startTime }));
             this.stampTraceContext(root, {
                 sessionId: input.sessionId,
-                traceName: parent === NO_PARENT ? input.name : undefined,
+                traceName: externalParent === NO_PARENT ? input.name : undefined,
                 userId: input.context?.userId ?? this.config.userId,
                 tags: input.context?.tags ?? this.config.tags,
             });
             // External traces retain their owner's trace name and trace-level IO.
-            if (parent === NO_PARENT)
+            if (externalParent === NO_PARENT) {
                 this.roots.add(root);
+                root.otelSpan.setAttribute(tracing.LangfuseOtelSpanAttributes.IS_APP_ROOT, true);
+            }
             else
                 root.otelSpan.setAttribute(tracing.LangfuseOtelSpanAttributes.IS_APP_ROOT, false);
             return root;
@@ -273,6 +278,25 @@ export class LangfuseReporter {
             return null;
         }
     }
+    /** A running task keeps its trace identity; late host context is a link. */
+    updateContext(span, context) {
+        if (!span)
+            return;
+        try {
+            const previous = this.traceContext.get(span);
+            this.stampTraceContext(span, {
+                ...previous,
+                userId: context.userId ?? previous?.userId,
+                tags: context.tags ?? previous?.tags,
+            });
+            const parent = parentContext(context.traceparent);
+            if (parent !== NO_PARENT)
+                span.otelSpan.addLink({ context: parent });
+        }
+        catch (error) {
+            console.error('[dsh-langfuse] context update failed:', error);
+        }
+    }
     /** Open a generation (one per LLM call) under any observation parent. */
     startGeneration(parent, input) {
         const api = this.api;
@@ -327,9 +351,14 @@ export class LangfuseReporter {
                 input: input.input,
                 metadata: input.metadata,
             };
-            const span = api.context.with(api.ROOT_CONTEXT, () => input.asType === 'tool'
-                ? parent.startObservation(input.name, attributes, { asType: 'tool' })
-                : parent.startObservation(input.name, attributes));
+            const span = api.context.with(api.ROOT_CONTEXT, () => input.startTime && this.tracing
+                ? this.tracing.startObservation(input.name, attributes, {
+                    parentSpanContext: parent.otelSpan.spanContext(),
+                    startTime: input.startTime,
+                })
+                : input.asType === 'tool'
+                    ? parent.startObservation(input.name, attributes, { asType: 'tool' })
+                    : parent.startObservation(input.name, attributes));
             this.stampTraceContext(span, this.traceContext.get(parent));
             return span;
         }

package/lib/index.js

@@ -16,6 +16,8 @@
  *   (`turn/start` opens a root span — in the v5 SDK the root observation IS
  *   the trace — the turn's first `user/message` sets the input, `turn/end`
  *   stamps the end reason and ends the root, which is what exports it).
+ * - Native A2A inbox tasks own a trace spanning admission through task termination;
+ *   agent turns and queue controls are children of that task.
  * - subagent child sessions (`session/created` with `header.parentSession`)
  *   ride the parent's trace: a `subagent` **span** opened under the enclosing
  *   delegation tool span, the child's generations/tool spans nested under it,
@@ -28,6 +30,7 @@
  *
  * @module dsh-langfuse
  */
+import { createHash } from 'node:crypto';
 import Schema from '@deepseek-ai/schemastery';
 import { LangfuseReporter } from './client.js';
 import { isHookInvoked, isHookResult } from './hooks.js';
@@ -203,6 +206,10 @@ export function apply(ctx, config) {
         return;
     const reporter = new LangfuseReporter(config);
     const sessions = new Map();
+    const nativeInboxes = new Set();
+    const pendingTurns = new Map();
+    const inboxInputs = new Map();
+    const inboxTasks = new Map();
     const children = new Map();
     const completedTurns = new Map();
     function rememberTurn(sessionId, turn, parent, turnTrace) {
@@ -268,11 +275,98 @@ export function apply(ctx, config) {
             tags: context.tags ? [...context.tags] : undefined,
         });
     });
-    function openTrace(sessionId, metadata) {
+    function openTrace(sessionId, metadata, startTime) {
         const context = sessionId ? traceContexts.get(sessionId) : undefined;
         if (sessionId)
             traceContexts.delete(sessionId);
-        return reporter.openTrace({ name: config.traceName, sessionId, metadata, context });
+        return reporter.openTrace({ name: config.traceName, sessionId, metadata, context, startTime });
+    }
+    const inboxKey = (contextId, taskId) => JSON.stringify([contextId, taskId]);
+    function taskTrace(event) {
+        if (!event.taskId)
+            return;
+        const key = inboxKey(event.contextId, event.taskId);
+        let task = inboxTasks.get(key);
+        if (!task) {
+            const context = traceContexts.get(event.contextId);
+            traceContexts.delete(event.contextId);
+            task = {
+                key,
+                contextId: event.contextId,
+                taskId: event.taskId,
+                trace: reporter.openTrace({
+                    name: config.traceName === 'dsh-turn' ? 'a2a-task' : config.traceName,
+                    sessionId: event.contextId,
+                    metadata: { taskId: event.taskId, taskState: 'queued' },
+                    traceId: createHash('sha256').update(key).digest('hex').slice(0, 32),
+                    startTime: new Date(event.queuedAt ?? event.at),
+                }),
+                hasInput: false,
+                messageIds: new Set(),
+                nativeMessageIds: new Set(),
+                openTurns: 0,
+            };
+            if (context)
+                reporter.updateContext(task.trace, context);
+            inboxTasks.set(key, task);
+        }
+        if (event.messageId)
+            task.messageIds.add(event.messageId);
+        if (event.nativeMessageId)
+            task.nativeMessageIds.add(event.nativeMessageId);
+        if (!task.hasInput && config.captureContent && event.input) {
+            reporter.updateSpan(task.trace, { input: event.input });
+            task.hasInput = true;
+        }
+        reporter.updateSpan(task.trace, {
+            metadata: {
+                referenceTaskIds: event.referenceTaskIds?.length ? event.referenceTaskIds : undefined,
+                a2aMessageIds: [...task.messageIds],
+                nativeMessageIds: [...task.nativeMessageIds],
+            },
+        });
+        return task;
+    }
+    function closeTask(task, endedAt = new Date()) {
+        if (!task.end || task.openTurns)
+            return;
+        const end = task.end;
+        if (inboxInputs.get(task.contextId)?.[0]?.taskId === task.taskId)
+            inboxInputs.delete(task.contextId);
+        if (inboxTasks.get(task.key) === task)
+            inboxTasks.delete(task.key);
+        afterMedia(task.trace, (at) => reporter.endSpan(task.trace, {
+            output: end.phase === 'completed' && config.captureContent && task.lastOutput !== undefined
+                ? task.lastOutput
+                : end.output,
+            level: end.level,
+            metadata: { taskState: end.phase },
+        }, at), new Date(Math.max(end.at, endedAt.getTime())));
+    }
+    function endTurn(state, update = {}, endedAt) {
+        const task = state.taskKey ? inboxTasks.get(state.taskKey) : undefined;
+        if (task && state.lastAssistantText !== undefined)
+            task.lastOutput = state.lastAssistantText;
+        afterMedia(state.trace, (at) => {
+            reporter.endSpan(state.trace, update, at);
+            if (task) {
+                task.openTurns--;
+                closeTask(task, at);
+            }
+        }, endedAt);
+    }
+    function suspendTasks(contextId) {
+        for (const task of [...inboxTasks.values()]) {
+            if (contextId !== undefined && task.contextId !== contextId)
+                continue;
+            task.end ??= {
+                phase: 'suspended',
+                at: Date.now(),
+                output: { state: 'suspended' },
+                level: 'DEFAULT',
+            };
+            closeTask(task);
+        }
     }
     function rootSessionId(sessionId) {
         while (sessionId && children.has(sessionId))
@@ -314,10 +408,36 @@ export function apply(ctx, config) {
         const existing = id ? sessions.get(id) : undefined;
         if (existing)
             return existing.trace;
-        const trace = openTrace(id);
+        const pending = id ? pendingTurns.get(id) : undefined;
+        const turn = pending?.turn;
+        if (id && nativeInboxes.has(id)) {
+            const selected = inboxInputs.get(id)?.[0];
+            const task = selected ? taskTrace(selected) : undefined;
+            if (!task || task.end)
+                return null;
+            const context = traceContexts.get(id);
+            if (context) {
+                reporter.updateContext(task.trace, context);
+                traceContexts.delete(id);
+            }
+            const trace = reporter.startSpan(task.trace, {
+                name: 'agent:turn',
+                metadata: { turn, taskId: task.taskId },
+                startTime: pending?.startTime,
+            });
+            pendingTurns.delete(id);
+            if (trace) {
+                task.openTurns++;
+                sessions.set(id, { trace, hasInput: turn === undefined, turn, taskKey: task.key });
+            }
+            return trace;
+        }
+        const trace = openTrace(id, turn === undefined ? undefined : { turn }, pending?.startTime);
+        if (id)
+            pendingTurns.delete(id);
         // hasInput starts true: one-offs never take a turn's first-message input.
         if (trace && id)
-            sessions.set(id, { trace, hasInput: true });
+            sessions.set(id, { trace, hasInput: turn === undefined, turn });
         return trace;
     }
     /**
@@ -328,6 +448,129 @@ export function apply(ctx, config) {
         const child = sessionId ? children.get(sessionId) : undefined;
         return child?.span ?? traceFor(sessionId);
     }
+    ctx.on('a2a/inbox', (event) => {
+        try {
+            const id = event.contextId;
+            nativeInboxes.add(id);
+            if (event.phase === 'resolved')
+                return;
+            const metadata = {
+                taskId: event.taskId,
+                taskIds: event.taskIds,
+                messageId: event.messageId,
+                nativeMessageId: event.nativeMessageId,
+                pending: event.pending,
+                target: event.target,
+                position: event.position,
+                agentStatus: event.agentStatus,
+                turn: event.turn,
+                step: event.step,
+            };
+            const input = config.captureContent ? event.input : undefined;
+            const waitMs = event.queuedAt === undefined
+                ? undefined
+                : Math.max(0, (event.selectedAt ?? event.at) - event.queuedAt);
+            const output = {
+                state: event.phase,
+                target: event.target,
+                position: event.position,
+                pending: event.pending,
+                agentStatus: event.agentStatus,
+            };
+            if (event.phase === 'selected') {
+                const task = taskTrace(event);
+                if (task && task.selectedAt === undefined) {
+                    task.selectedAt = event.selectedAt ?? event.at;
+                    task.waitMs = waitMs;
+                }
+                if (task)
+                    reporter.updateSpan(task.trace, {
+                        metadata: { taskState: 'running', waitMs: task.waitMs },
+                    });
+                const inputs = inboxInputs.get(id) ?? [];
+                if (!inputs.some((input) => input.nativeMessageId === event.nativeMessageId))
+                    inputs.push(event);
+                inboxInputs.set(id, inputs);
+                return;
+            }
+            if (['prepared', 'prepare-failed', 'prepare-aborted'].includes(event.phase)) {
+                const parent = parentFor(id);
+                const inputs = inboxInputs.get(id) ?? [event];
+                const first = inputs[0];
+                const turnWaitMs = first.queuedAt === undefined
+                    ? undefined
+                    : Math.max(0, (first.selectedAt ?? first.at) - first.queuedAt);
+                reporter.updateSpan(parent, {
+                    input: sessions.get(id)?.hasInput ? undefined : input,
+                    metadata: {
+                        taskId: event.taskId,
+                        waitMs: turnWaitMs,
+                        a2aMessageIds: inputs.map((input) => input.messageId),
+                        nativeMessageIds: inputs.map((input) => input.nativeMessageId),
+                    },
+                });
+                const prepare = reporter.startSpan(parent, {
+                    name: event.target === 'next-step' ? 'inbox:steering' : 'inbox:prepare',
+                    input,
+                    startTime: new Date(event.selectedAt ?? event.at),
+                    metadata: {
+                        ...metadata,
+                        waitMs,
+                        prepareMs: event.selectedAt === undefined ? undefined : Math.max(0, event.at - event.selectedAt),
+                    },
+                });
+                reporter.endSpan(prepare, {
+                    output,
+                    level: event.phase === 'prepare-failed'
+                        ? 'ERROR'
+                        : event.phase === 'prepare-aborted'
+                            ? 'WARNING'
+                            : 'DEFAULT',
+                }, new Date(event.at));
+                return;
+            }
+            const tasks = event.taskId
+                ? [
+                    ['completed', 'failed', 'canceled'].includes(event.phase)
+                        ? inboxTasks.get(inboxKey(id, event.taskId))
+                        : taskTrace(event),
+                ].filter((task) => !!task)
+                : [...inboxTasks.values()].filter((task) => task.contextId === id &&
+                    !task.end &&
+                    (event.taskIds === undefined || event.taskIds.includes(task.taskId)));
+            for (const task of tasks) {
+                if (task.end)
+                    continue;
+                const details = { ...metadata, taskId: task.taskId };
+                const operation = reporter.startSpan(task.trace, {
+                    name: `inbox:${event.phase}`,
+                    input,
+                    startTime: new Date(event.at),
+                    metadata: details,
+                });
+                reporter.endSpan(operation, { output }, new Date(event.at));
+                const phase = event.phase === 'cleared' ? 'canceled' : event.phase;
+                if (['completed', 'failed', 'canceled'].includes(phase)) {
+                    task.end = {
+                        phase,
+                        at: event.at,
+                        output: { ...output, state: phase },
+                        level: phase === 'failed' ? 'ERROR' : phase === 'canceled' ? 'WARNING' : 'DEFAULT',
+                    };
+                    closeTask(task, new Date(event.at));
+                }
+            }
+            if (event.phase === 'disposed')
+                suspendTasks(id);
+            if (event.phase === 'disposed' || event.phase === 'cleared') {
+                nativeInboxes.delete(id);
+                inboxInputs.delete(id);
+            }
+        }
+        catch (error) {
+            console.error('[dsh-langfuse] inbox reporting failed:', error);
+        }
+    });
     // ------------------------------------------------------------------
     // Subagent child sessions: session/created precedes both subagent/start
     // and the child's first generation, and the durable header already links
@@ -385,8 +628,8 @@ export function apply(ctx, config) {
         }, endedAt));
     });
     // ------------------------------------------------------------------
-    // Trace lifecycle: one trace per turn (top-level sessions only — child
-    // sessions ride the parent's trace under their subagent span).
+    // Turn lifecycle: native tasks keep their root across turns; other sessions
+    // open one trace per turn. Subagents stay under their parent's trace.
     // ------------------------------------------------------------------
     ctx.on('session/event', (session, event) => {
         const sessionId = session.id;
@@ -407,7 +650,9 @@ export function apply(ctx, config) {
             if (previous?.root)
                 reporter.endSpan(previous.root, { level: 'WARNING' });
             const child = children.get(sessionId);
-            const inTurn = child ? child.turn === data.turn : sessions.get(sessionId)?.turn === data.turn;
+            const inTurn = child
+                ? child.turn === data.turn
+                : (sessions.get(sessionId)?.turn ?? pendingTurns.get(sessionId)?.turn) === data.turn;
             const completed = data.invocationId && !inTurn
                 ? completedTurns.get(JSON.stringify([sessionId, data.turn]))
                 : undefined;
@@ -553,7 +798,13 @@ export function apply(ctx, config) {
                 closeHooks(sessionId, true);
                 const stale = sessions.get(sessionId);
                 if (stale)
-                    afterMedia(stale.trace, (endedAt) => reporter.endSpan(stale.trace, {}, endedAt));
+                    endTurn(stale);
+                inboxInputs.delete(sessionId);
+                if (nativeInboxes.has(sessionId)) {
+                    sessions.delete(sessionId);
+                    pendingTurns.set(sessionId, { turn: event.data.turn, startTime: new Date(event.time) });
+                    break;
+                }
                 const trace = openTrace(sessionId, { turn: event.data.turn });
                 if (trace)
                     sessions.set(sessionId, { trace, hasInput: false, turn: event.data.turn });
@@ -575,13 +826,14 @@ export function apply(ctx, config) {
                 break;
             }
             case 'turn/end': {
+                if (pendingTurns.has(sessionId))
+                    traceFor(sessionId);
                 const state = sessions.get(sessionId);
                 if (state) {
                     sessions.delete(sessionId);
                     rememberTurn(sessionId, event.data.turn, state.trace, state.trace);
-                    // The turn's final answer becomes the trace's output; ending the
-                    // root span is what exports the trace (v5 exports spans on end).
-                    afterMedia(state.trace, (endedAt) => reporter.endSpan(state.trace, {
+                    // Native task roots stay open until the A2A terminal signal.
+                    endTurn(state, {
                         output: state.lastAssistantText,
                         level: event.data.reason.kind === 'error'
                             ? 'ERROR'
@@ -599,7 +851,7 @@ export function apply(ctx, config) {
                                 ? { errorCode: event.data.reason.error.code }
                                 : {}),
                         },
-                    }, endedAt));
+                    });
                 }
                 break;
             }
@@ -611,6 +863,9 @@ export function apply(ctx, config) {
         const state = sessions.get(sessionId);
         sessions.delete(sessionId);
         traceContexts.delete(sessionId);
+        pendingTurns.delete(sessionId);
+        nativeInboxes.delete(sessionId);
+        inboxInputs.delete(sessionId);
         for (const [key, completed] of completedTurns) {
             if (completed.sessionId === sessionId)
                 completedTurns.delete(key);
@@ -621,7 +876,8 @@ export function apply(ctx, config) {
         // trace) — v5 spans only export on end, so dropping it open would lose
         // everything it recorded.
         if (state)
-            afterMedia(state.trace, (endedAt) => reporter.endSpan(state.trace, {}, endedAt));
+            endTurn(state);
+        suspendTasks(sessionId);
         // Children: keep the entry — background/continuable subagents dispose
         // their session BEFORE subagent/end fires, and the span's close must ride
         // subagent/end (disposing first would either leak the span or close it
@@ -920,10 +1176,16 @@ export function apply(ctx, config) {
             // down — v5 spans only export on end, so unloading mid-turn (profile
             // reload) would otherwise silently drop them.
             for (const state of sessions.values())
-                reporter.endSpan(state.trace, {}, endedAt);
+                endTurn(state, {}, endedAt);
+            suspendTasks();
+            await drainMedia();
             for (const child of children.values())
                 reporter.endSpan(child.span, {}, endedAt);
             sessions.clear();
+            pendingTurns.clear();
+            nativeInboxes.clear();
+            inboxInputs.clear();
+            inboxTasks.clear();
             completedTurns.clear();
             traceContexts.clear();
             children.clear();

package/lib/types/client.d.ts

@@ -106,7 +106,11 @@ export declare class LangfuseReporter {
         sessionId?: string;
         metadata?: Record<string, unknown>;
         context?: LangfuseTraceContext;
+        startTime?: Date;
+        traceId?: string;
     }): LangfuseSpan | null;
+    /** A running task keeps its trace identity; late host context is a link. */
+    updateContext(span: Observation | null, context: LangfuseTraceContext): void;
     /** Open a generation (one per LLM call) under any observation parent. */
     startGeneration(parent: Observation | null, input: {
         name: string;
@@ -130,6 +134,7 @@ export declare class LangfuseReporter {
         input?: unknown;
         metadata?: Record<string, unknown>;
         asType?: 'tool';
+        startTime?: Date;
     }): LangfuseSpan | null;
     /**
      * Merge fields into an open span — subagent enrichment (label, provider),

package/lib/types/index.d.ts

@@ -16,6 +16,8 @@
  *   (`turn/start` opens a root span — in the v5 SDK the root observation IS
  *   the trace — the turn's first `user/message` sets the input, `turn/end`
  *   stamps the end reason and ends the root, which is what exports it).
+ * - Native A2A inbox tasks own a trace spanning admission through task termination;
+ *   agent turns and queue controls are children of that task.
  * - subagent child sessions (`session/created` with `header.parentSession`)
  *   ride the parent's trace: a `subagent` **span** opened under the enclosing
  *   delegation tool span, the child's generations/tool spans nested under it,
@@ -33,8 +35,29 @@ import Schema from '@deepseek-ai/schemastery';
 import { type LangfuseTraceContext } from './client.js';
 export type { LangfuseTraceContext } from './client.js';
 export { appendHookEvent, type HookInvoked, type HookResult } from './hooks.js';
+/** Optional protocol telemetry; no dependency on the A2A plugin. */
+interface A2aInboxEvent {
+    phase: string;
+    contextId: string;
+    at: number;
+    pending: number;
+    target?: 'next-turn' | 'next-step';
+    input?: string;
+    position?: number;
+    agentStatus?: string;
+    taskId?: string;
+    taskIds?: string[];
+    messageId?: string;
+    referenceTaskIds?: string[];
+    nativeMessageId?: string;
+    queuedAt?: number;
+    selectedAt?: number;
+    turn?: number;
+    step?: number;
+}
 declare module '@deepseek-ai/cordis' {
     interface Events {
+        'a2a/inbox'(detail: A2aInboxEvent): void;
         /** Bind standard labels/parent context before a session's next trace starts. */
         'langfuse/context': (sessionId: string, context: LangfuseTraceContext) => void;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-langfuse",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "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",
@@ -66,7 +66,7 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
     "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.1-rc.2",
     "@deepseek-ai/dsh-hook-protocol": "0.2.0-rc.2",
     "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
     "@deepseek-ai/dsh-llm": "0.2.0-rc.2",