@amaster.ai/dsh-langfuse 0.1.24 → 0.1.26

package/README.md

@@ -134,7 +134,7 @@ Tool hooks should include the execution's `callId` in both records. The plugin m
 
 `hook/result.outcome` describes process execution independently of `decision`: `success` is normal completion, `failed` is execution failure, `timed-out` is deadline termination, and `cancelled` is cancellation. The producer maps its process semantics to these values; an exit code expressing a policy denial can still be a successful execution. Optional `exitCode` and `signal` preserve process details. Failed/timed-out executions receive ERROR observations, cancellation receives WARNING, and successful executions retain decision-based warnings. Records without an explicit outcome preserve the legacy exit-code interpretation (0/2 are non-error). The plugin records `durationMs` and never infers a timeout or cancellation from a missing exit code.
 
-For records admitted by the session, runs with `invocationId` retain correlation after `turn/end` and a subsequent `turn/start`; a late result ends the original hook span without attaching it to the new turn. Invocations arriving outside their originating turn receive a separate root with `detachedHook: true` and the original turn number; their result ends both hook and root so they export without waiting for another turn. These detached hook roots do not consume `langfuse/context` queued for the next turn. Detached producers must finish reporting before the session is disposed. Session disposal/plugin unload closes unfinished runs with `hook result not observed`; this means missing telemetry, not proof of execution failure. Legacy records without `invocationId` still close at turn boundaries.
+For records admitted by the session, runs with `invocationId` retain correlation after `turn/end` and a subsequent `turn/start`; a late result ends the original hook span without attaching it to the new turn. Delayed invocations, including `UserCancel`, reuse their originating turn's parent span even after the next turn starts. The plugin retains the latest 128 completed-turn associations across all sessions, clearing a session's associations on disposal and all associations on unload. Reporting never reopens the ended root or changes its end time or final status; each hook records its own duration. When the originating parent is unavailable or evicted, the invocation receives a separate root with `detachedHook: true` and the original turn number; its result ends both hook and fallback root. Neither path consumes `langfuse/context` queued for the next turn. Detached producers must finish reporting before the session is disposed. Session disposal/plugin unload closes unfinished runs with `hook result not observed`; this means missing telemetry, not proof of execution failure. Legacy records without `invocationId` still close at turn boundaries.
 
 Custom names, hook input, parsed results and raw process output follow `captureContent`; credentials and `redactFields` are masked by the existing reporter. New outcomes, correlation IDs, dialect, point, duration and process metadata remain available with content capture disabled. The event writer does not sanitize the session log itself: application producers remain responsible for what they persist. Applications must explicitly replace any private hook events with this standard producer path, reuse the same `invocationId`, and report the actual outcome; installing/upgrading the plugin does not adapt an application bridge or repair historical Trace overview IO (Issue #59).
 
@@ -146,6 +146,8 @@ Run `pnpm test:sdk` at the repository root for a secrets-free check using the re
 
 The independent `dsh-langfuse.tool-hooks` E2E leg boots the packed plugin in the real headless profile, asks the model to read a marker file, and executes BeforeTool/AfterTool scripts through an E2E-only producer. It requires both gateway and Langfuse credentials, then polls the real Observations API to verify named hooks, tool-call parenting, enclosing tool timestamps, script input and parsed output, credential masking, and stdout truncation. The existing `dsh-langfuse.hook` leg continues to check the upstream Codex UserPromptSubmit bridge; the new fixture verifies the shared event contract and does not substitute for the application's Gemini bridge integration.
 
+The `dsh-langfuse.cancel-hook` E2E leg cancels a real agent at a tool boundary, queues its next turn, and asynchronously runs a UserCancel process after that turn starts. Real Langfuse API read-back must show the hook under the cancelled turn's root and trace ID, with the root still aborted and ended before the hook's own duration. It requires the existing gateway and Langfuse secrets in `integration.yml`.
+
 ### Trace overview compatibility
 
 Overall input/output belongs to the `dsh-turn` root observation. The root is exported when the turn ends; while a long turn is running, child observations can already be visible before the root appears. After completion, allow asynchronous ingestion to settle.

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,7 +206,22 @@ 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) {
+        if (!parent)
+            return;
+        const key = JSON.stringify([sessionId, turn]);
+        completedTurns.delete(key);
+        completedTurns.set(key, { sessionId, parent, turnTrace });
+        // Bound retained SDK handles across all sessions; older hooks use the standalone fallback.
+        if (completedTurns.size > 128)
+            completedTurns.delete(completedTurns.keys().next().value);
+    }
     /** Per-session stack of currently open tool pipeline spans (for subagent parenting). */
     const openToolSpans = new Map();
     const toolCalls = new Map();
@@ -257,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))
@@ -303,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;
     }
     /**
@@ -317,6 +448,135 @@ 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,
+                paused: event.paused,
+                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,
+                paused: event.paused,
+                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));
+                }
+                else
+                    reporter.updateSpan(task.trace, {
+                        metadata: { taskState: event.phase === 'paused' ? 'paused' : undefined },
+                    });
+            }
+            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
@@ -374,8 +634,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;
@@ -396,8 +656,13 @@ 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 root = data.invocationId && !inTurn
+            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;
+            const root = data.invocationId && !inTurn && !completed
                 ? // A late hook must not consume context queued for the next turn.
                     reporter.openTrace({
                         name: config.traceName,
@@ -407,7 +672,12 @@ export function apply(ctx, config) {
                 : undefined;
             const tool = data.callId ? toolCalls.get(sessionId)?.get(data.callId) : undefined;
             const hookName = config.captureContent ? reporter.mask({ name: data.name }).name : undefined;
-            const span = reporter.startSpan(root === undefined ? (tool?.turn === data.turn ? tool.span : parentFor(sessionId)) : root, {
+            const span = reporter.startSpan(completed?.parent ??
+                (root === undefined
+                    ? tool?.turn === data.turn
+                        ? tool.span
+                        : parentFor(sessionId)
+                    : root), {
                 name: `hook:${data.point}${hookName ? `:${hookName}` : ''}`,
                 input: config.captureContent ? data.input : undefined,
                 metadata: {
@@ -429,7 +699,11 @@ export function apply(ctx, config) {
                 handlerId: data.handlerId,
                 persistent: !!data.invocationId,
                 callId: data.callId,
-                turnTrace: root === undefined ? (child?.turnTrace ?? sessions.get(sessionId)?.trace) : undefined,
+                turnTrace: completed
+                    ? completed.turnTrace
+                    : root === undefined
+                        ? (child?.turnTrace ?? sessions.get(sessionId)?.trace)
+                        : undefined,
             });
             openHooks.set(sessionId, pending);
             return;
@@ -500,8 +774,10 @@ export function apply(ctx, config) {
         if (child) {
             if (event.type === 'turn/start')
                 child.turn = event.data.turn;
-            if (event.type === 'turn/end')
+            if (event.type === 'turn/end') {
+                rememberTurn(sessionId, event.data.turn, child.span, child.turnTrace ?? null);
                 child.turn = undefined;
+            }
             // 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) {
@@ -528,7 +804,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 });
@@ -550,12 +832,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);
-                    // 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, {
+                    rememberTurn(sessionId, event.data.turn, state.trace, state.trace);
+                    // Native task roots stay open until the A2A terminal signal.
+                    endTurn(state, {
                         output: state.lastAssistantText,
                         level: event.data.reason.kind === 'error'
                             ? 'ERROR'
@@ -573,7 +857,7 @@ export function apply(ctx, config) {
                                 ? { errorCode: event.data.reason.error.code }
                                 : {}),
                         },
-                    }, endedAt));
+                    });
                 }
                 break;
             }
@@ -585,13 +869,21 @@ 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);
+        }
         openToolSpans.delete(sessionId);
         toolCalls.delete(sessionId);
         // End an abandoned root (crash-orphaned turn or between-turns one-off
         // 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
@@ -890,10 +1182,17 @@ 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();
             openToolSpans.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,30 @@ 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;
+    paused?: boolean;
+    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.24",
+  "version": "0.1.26",
   "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",