@amaster.ai/dsh-langfuse 0.1.11 → 0.1.13

package/README.md

@@ -6,6 +6,7 @@ Langfuse observability for [DeepSeek Harness (dsh)](https://github.com/deepseek-
 
 - one **generation** per LLM call (`llm/stream` waterfall), plus a nested `llm-request` span carrying the verbatim loop-built request
 - one **span** per tool call (`tools/execute` waterfall)
+- one **span** per `hook/invoked` / `hook/result` pair, with hook point, decision, exit code, and duration (stderr summary follows `captureContent`)
 - one **trace** per session turn (`session/event`) — in the v5 SDK the trace IS its root span, ended (and thereby exported) at `turn/end`
 - subagent child sessions nested under the parent's tree (`session/created` header link + `subagent/start` / `subagent/end`)
 
@@ -38,6 +39,8 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
 
 Buffered spans drain on `session/flush(session)`; the exporter shuts down with the plugin fiber.
 
+Hook spans appear when a dsh hook bridge emits the paired session records. The current `hook/result` record does not contain stdout; successful script output can appear in the LLM request when the bridge injects it as context, while the hook span reports decision, exit code, duration, and bounded stderr. `SessionStart` runs before the first turn and does not emit these records, so it has no hook span.
+
 Observability is a no-throw seam: backend errors are logged with a `[dsh-langfuse]` prefix and never escape into the agent loop.
 
 ## Compatibility

package/lib/index.js

@@ -12,6 +12,7 @@
  * - `tools/execute` waterfall → one Langfuse **span** per tool dispatch
  *   (routed to the session's trace via `exec.agent.id` — the agent/session
  *   shared identity).
+ * - `hook/invoked` / `hook/result` session records → one **span** per hook run.
  * - `session/event` emit    → one Langfuse **trace** per agent turn
  *   (`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`
@@ -145,6 +146,13 @@ export function apply(ctx, config) {
     const children = new Map();
     /** Per-session stack of currently open tools/execute spans (for subagent parenting). */
     const openToolSpans = new Map();
+    const openHooks = new Map();
+    function closeHooks(sessionId) {
+        for (const span of openHooks.get(sessionId)?.values() ?? []) {
+            reporter.endSpan(span, { level: 'WARNING', statusMessage: 'hook result not observed' });
+        }
+        openHooks.delete(sessionId);
+    }
     /**
      * The trace an observation for `sessionId` belongs to: the session's open
      * turn trace, else a per-session one-off trace shared by that session's
@@ -230,6 +238,59 @@ export function apply(ctx, config) {
     // ------------------------------------------------------------------
     ctx.on('session/event', (session, event) => {
         const sessionId = session.id;
+        const hookEvent = event;
+        if (hookEvent.type === 'hook/invoked') {
+            const data = hookEvent.data;
+            if (!data || typeof data.handlerId !== 'string' || typeof data.point !== 'string')
+                return;
+            const pending = openHooks.get(sessionId) ?? new Map();
+            if (pending.has(data.handlerId)) {
+                reporter.endSpan(pending.get(data.handlerId) ?? null, {
+                    level: 'WARNING',
+                    statusMessage: 'hook result not observed',
+                });
+            }
+            pending.set(data.handlerId, reporter.startSpan(parentFor(sessionId), {
+                name: `hook:${data.point}`,
+                metadata: {
+                    turn: data.turn,
+                    point: data.point,
+                    dialect: data.dialect,
+                    matcher: data.matcher,
+                    handlerId: data.handlerId,
+                },
+            }));
+            openHooks.set(sessionId, pending);
+            return;
+        }
+        if (hookEvent.type === 'hook/result') {
+            const data = hookEvent.data;
+            if (!data || typeof data.handlerId !== 'string' || typeof data.decision !== 'string')
+                return;
+            const pending = openHooks.get(sessionId);
+            const span = pending?.get(data.handlerId);
+            if (span) {
+                reporter.endSpan(span, {
+                    output: {
+                        decision: data.decision,
+                        exitCode: data.exitCode,
+                        stderrSummary: config.captureContent ? data.stderrSummary : undefined,
+                    },
+                    level: data.exitCode === undefined || (data.exitCode !== 0 && data.exitCode !== 2)
+                        ? 'ERROR'
+                        : data.decision === 'block' || data.decision === 'deny' || data.decision === 'stop'
+                            ? 'WARNING'
+                            : 'DEFAULT',
+                    metadata: { durationMs: data.durationMs },
+                });
+            }
+            pending?.delete(data.handlerId);
+            if (pending?.size === 0)
+                openHooks.delete(sessionId);
+            return;
+        }
+        if (event.type === 'turn/end')
+            closeHooks(sessionId);
         const child = children.get(sessionId);
         if (child) {
             // The delegated prompt (the child's first user/message) is the
@@ -255,6 +316,7 @@ export function apply(ctx, config) {
                 // whose `turn/end` was never seen (crash-orphaned): end and replace
                 // it — v5 spans only export on end, so the stale root must close to
                 // keep what it already recorded.
+                closeHooks(sessionId);
                 const stale = sessions.get(sessionId);
                 if (stale)
                     reporter.endSpan(stale.trace);
@@ -299,6 +361,7 @@ export function apply(ctx, config) {
     });
     ctx.on('session/disposed', (session) => {
         const sessionId = session.id;
+        closeHooks(sessionId);
         const state = sessions.get(sessionId);
         sessions.delete(sessionId);
         openToolSpans.delete(sessionId);
@@ -518,6 +581,8 @@ export function apply(ctx, config) {
             // down — v5 spans only export on end, so unloading mid-turn (profile
             // reload) would otherwise silently drop them. (An in-flight generation
             // isn't tracked; its own tee finally closes it if the stream settles.)
+            for (const sessionId of openHooks.keys())
+                closeHooks(sessionId);
             for (const state of sessions.values())
                 reporter.endSpan(state.trace);
             for (const child of children.values())

package/lib/types/index.d.ts

@@ -12,6 +12,7 @@
  * - `tools/execute` waterfall → one Langfuse **span** per tool dispatch
  *   (routed to the session's trace via `exec.agent.id` — the agent/session
  *   shared identity).
+ * - `hook/invoked` / `hook/result` session records → one **span** per hook run.
  * - `session/event` emit    → one Langfuse **trace** per agent turn
  *   (`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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-langfuse",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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",