nemo-relay-openclaw 0.3.0 → 0.4.0

package/dist/src/hooks-backend.js

@@ -1,10 +1,10 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 import { emitMark, toJsonRecord } from './hook-replay/marks.js';
-import { llmKey } from './hook-replay/correlation.js';
+import { llmKey, nowMicros } from './hook-replay/correlation.js';
 import { emitUnpairedModelCallTimingMarks, recordBeforeMessageWrite, recordLlmInput, recordLlmOutput, recordModelCallEnded, recordModelCallStarted, replayAgentEndMessages, replayPendingLlmOutputsForSession, } from './hook-replay/llm.js';
 import { guardBeforeToolCall, replayAfterToolCall } from './hook-replay/tool.js';
-import { createHookReplayState, drainSession, closeSessionRoot, deleteSession, ensureSession, resolveSessionKey, } from './hook-replay/session.js';
+import { createHookReplayState, drainSession, closeSessionRoot, deleteSession, ensureSession, materializeSessionRoot, queueCapturedEmit, resolveSessionOwnerKey, } from './hook-replay/session.js';
 /** Replays OpenClaw public hook events into NeMo Relay scopes, spans, and marks. */
 export class HookReplayBackend {
     nf;
@@ -13,6 +13,8 @@ export class HookReplayBackend {
     agentVersion;
     stateValue = createHookReplayState();
     warningCounts = new Map();
+    pendingSubagentLineageByChildSessionKey = new Map();
+    pendingSubagentChildKeyByRunId = new Map();
     constructor(options) {
         this.nf = options.nf;
         this.config = options.config;
@@ -30,13 +32,16 @@ export class HookReplayBackend {
     }
     /** Open or alias an explicit OpenClaw session root. */
     onSessionStart(event, ctx) {
-        this.ensureSession({
+        const observedAtMicros = nowMicros();
+        const session = this.ensureSession({
             sessionId: event.sessionId,
             sessionKey: event.sessionKey ?? ctx.sessionKey,
             agentId: ctx.agentId,
             source: 'session_start',
             resumedFrom: event.resumedFrom,
+            timestamp: observedAtMicros,
         });
+        this.promoteDeferredSubagentSessionsForRequester(session?.sessionKey ?? event.sessionKey ?? ctx.sessionKey);
         // ensureSession opens the root scope and emits openclaw.session_start for both explicit and lazy sessions.
     }
     /** Close one explicit OpenClaw session and export its ATIF artifact. */
@@ -50,7 +55,13 @@ export class HookReplayBackend {
         if (!session) {
             return;
         }
-        await this.closeSession(session, sessionEndSummary(event));
+        await this.closeSession(session, sessionEndSummary(event), toJsonRecord({
+            source: 'openclaw.session_end',
+            hook_event_name: 'session_end',
+            sessionId: session.sessionId,
+            sessionKey: event.sessionKey ?? ctx.sessionKey,
+            agentId: ctx.agentId,
+        }));
     }
     /** Buffer an LLM request snapshot until a matching response or trajectory replay arrives. */
     onLlmInput(event, ctx) {
@@ -82,12 +93,14 @@ export class HookReplayBackend {
     }
     /** Finalize one agent run, replaying message-write trajectory when needed. */
     onAgentEnd(event, ctx) {
+        const observedAtMicros = nowMicros();
         const session = this.ensureSession({
             sessionId: ctx.sessionId,
             sessionKey: ctx.sessionKey,
             runId: event.runId ?? ctx.runId,
             agentId: ctx.agentId,
             source: 'lazy_session',
+            timestamp: observedAtMicros,
         });
         if (!session) {
             return;
@@ -102,16 +115,18 @@ export class HookReplayBackend {
             error: event.error,
             durationMs: event.durationMs,
             messageCount: event.messages.length,
-        }));
+        }), observedAtMicros);
     }
     /** Remember the last assistant text before OpenClaw finalizes the response. */
     onBeforeAgentFinalize(event, ctx) {
+        const observedAtMicros = nowMicros();
         const session = this.ensureSession({
             sessionId: event.sessionId,
             sessionKey: event.sessionKey ?? ctx.sessionKey,
             runId: event.runId ?? ctx.runId,
             agentId: ctx.agentId,
             source: 'lazy_session',
+            timestamp: observedAtMicros,
         });
         if (!session) {
             return;
@@ -132,19 +147,21 @@ export class HookReplayBackend {
             transcriptPath: event.transcriptPath,
             stopHookActive: event.stopHookActive,
             messageCount: event.messages?.length,
-        }));
+        }), observedAtMicros);
     }
     /** Attach subagent spawn metadata to the requester session when possible. */
     onSubagentSpawned(event, ctx) {
-        const session = this.ensureSession({
-            requesterSessionKey: ctx.requesterSessionKey,
-            source: 'lazy_session',
-        }) ??
+        const observedAtMicros = nowMicros();
+        this.trackPendingSubagentLineage(event, ctx, Math.trunc(observedAtMicros / 1000));
+        const requesterSession = this.ensureRequesterSessionAnchor(ctx.requesterSessionKey, observedAtMicros);
+        const childSessionKey = ctx.childSessionKey ?? event.childSessionKey;
+        const session = requesterSession ??
             this.ensureSession({
-                childSessionKey: ctx.childSessionKey ?? event.childSessionKey,
+                childSessionKey,
                 runId: ctx.runId ?? event.runId,
                 agentId: event.agentId,
                 source: 'lazy_session',
+                timestamp: observedAtMicros,
             });
         if (!session) {
             return;
@@ -156,22 +173,29 @@ export class HookReplayBackend {
             label: event.label,
             mode: event.mode,
             threadRequested: event.threadRequested,
-        }));
+        }), observedAtMicros);
+        if (!ctx.requesterSessionKey || requesterSession?.rootHandle) {
+            this.promoteDeferredSubagentSession(event.childSessionKey);
+        }
     }
     /** Attach subagent completion metadata to the requester or child session. */
     onSubagentEnded(event, ctx) {
+        const observedAtMicros = nowMicros();
         const session = this.ensureSession({
             requesterSessionKey: ctx.requesterSessionKey,
             source: 'lazy_session',
+            timestamp: observedAtMicros,
         }) ??
             this.ensureSession({
                 childSessionKey: ctx.childSessionKey ?? event.targetSessionKey,
                 runId: ctx.runId ?? event.runId,
                 source: 'lazy_session',
+                timestamp: observedAtMicros,
             });
         if (!session) {
             return;
         }
+        this.materializeDeferredSessionRoot(session);
         this.emitSessionMark('openclaw.subagent_ended', session, toJsonRecord({
             runId: event.runId ?? ctx.runId,
             targetSessionKey: event.targetSessionKey,
@@ -182,7 +206,7 @@ export class HookReplayBackend {
             endedAt: event.endedAt,
             sendFarewell: event.sendFarewell,
             accountId: event.accountId,
-        }));
+        }), observedAtMicros);
     }
     /** Drain all active sessions when the OpenClaw gateway is stopping. */
     async drainForGatewayStop(reason) {
@@ -190,11 +214,11 @@ export class HookReplayBackend {
     }
     /** Close one session selected by a runtime lifecycle cleanup hook. */
     async cleanupSession(input) {
-        const key = resolveSessionKey(this.stateValue, input);
-        if (!key) {
+        const ownerKey = resolveSessionOwnerKey(this.stateValue, input);
+        if (!ownerKey) {
             return;
         }
-        const session = this.stateValue.sessions.get(key);
+        const session = this.stateValue.sessions.get(ownerKey);
         if (!session) {
             return;
         }
@@ -226,6 +250,9 @@ export class HookReplayBackend {
     }
     /** Emit spans/marks under the stored session scope stack and ATIF capture window. */
     emitCapturedUnderSession(label, session, emit) {
+        if (queueCapturedEmit(session, label, emit)) {
+            return;
+        }
         this.safeReplay(label, session, () => {
             const previousStack = this.nf.currentScopeStack();
             try {
@@ -250,22 +277,36 @@ export class HookReplayBackend {
         return ensureSession(this.sessionManager(), input);
     }
     /** Drain, close, export, and delete one session. */
-    async closeSession(session, summary) {
+    async closeSession(session, summary, metadata) {
+        this.materializeDeferredSessionRoot(session);
         drainSession(this.sessionManager(), session);
-        closeSessionRoot(this.sessionManager(), session, summary, session.finalOutput ?? summary);
+        closeSessionRoot(this.sessionManager(), session, summary, session.finalOutput ?? summary, metadata);
         this.flushSubscriberDelivery('session_close');
+        this.forgetPendingSubagentLineage(session);
         deleteSession(this.stateValue, session);
     }
     /** Emit a session-level OpenClaw lifecycle mark. */
-    emitSessionMark(name, session, data) {
+    emitSessionMark(name, session, data, timestampMicros) {
         this.emitCapturedUnderSession(name, session, () => {
-            emitMark({
+            const params = {
                 nf: this.nf,
                 state: this.stateValue,
                 session,
                 name,
                 data,
-            });
+                metadata: toJsonRecord({
+                    source: name,
+                    hook_event_name: name.startsWith('openclaw.') ? name.slice('openclaw.'.length) : undefined,
+                    sessionId: session.sessionId,
+                    sessionKey: session.sessionKey,
+                    agentId: session.agentId,
+                    runId: typeof data.runId === 'string' ? data.runId : undefined,
+                }),
+            };
+            if (timestampMicros !== undefined) {
+                params.timestamp = timestampMicros;
+            }
+            emitMark(params);
         });
     }
     /** Close every active session with the same lifecycle summary. */
@@ -295,8 +336,170 @@ export class HookReplayBackend {
             replayPendingLlmOutputsForSession: (session, options) => this.replayPendingLlmOutputsForSession(session, options),
             emitUnpairedModelCallTimingMarks: (session) => this.emitUnpairedModelCallTimingMarks(session),
             logBoundedWarn: (key, message) => this.logBoundedWarn(key, message),
+            resolveSessionRootContext: (input) => this.resolveSessionRootContext(input),
         };
     }
+    /** Prefer nested child scopes only when the hook surface provides real subagent lineage. */
+    resolveSessionRootContext(input) {
+        this.pruneExpiredPendingSubagentLineage(microsToMs(input.timestamp) ?? Date.now());
+        const lineage = this.resolvePendingSubagentLineage(input);
+        if (lineage) {
+            const parentSession = this.resolveTrackedSession({ requesterSessionKey: lineage.requesterSessionKey });
+            return {
+                childSessionKey: input.childSessionKey ?? lineage.childSessionKey,
+                runId: input.runId ?? lineage.runId,
+                agentId: input.agentId ?? lineage.agentId,
+                scopeRole: 'subagent',
+                parentHandle: parentSession?.rootHandle,
+                deferRootOpen: input.deferRootOpen ?? (parentSession?.rootHandle ? false : true),
+            };
+        }
+        if (this.isDocumentedSubagentSessionKey(input.sessionKey ?? input.childSessionKey)) {
+            return {
+                scopeRole: 'subagent',
+                deferRootOpen: input.deferRootOpen ?? true,
+            };
+        }
+        return undefined;
+    }
+    /** Track stable parent/child lineage from subagent hooks until child session hooks can use it. */
+    trackPendingSubagentLineage(event, ctx, observedAtMs) {
+        this.pruneExpiredPendingSubagentLineage(observedAtMs);
+        const requesterSessionKey = ctx.requesterSessionKey?.trim();
+        const childSessionKey = (ctx.childSessionKey ?? event.childSessionKey)?.trim();
+        if (!requesterSessionKey || !childSessionKey) {
+            return;
+        }
+        this.pendingSubagentLineageByChildSessionKey.set(childSessionKey, {
+            childSessionKey,
+            requesterSessionKey,
+            runId: ctx.runId ?? event.runId,
+            agentId: event.agentId,
+            observedAtMs,
+        });
+        if (ctx.runId ?? event.runId) {
+            this.pendingSubagentChildKeyByRunId.set(ctx.runId ?? event.runId, childSessionKey);
+        }
+    }
+    /** Resolve the requester session if it exists, or seed a deferred lazy root placeholder for later promotion. */
+    ensureRequesterSessionAnchor(requesterSessionKey, timestampMicros) {
+        const trimmedRequesterSessionKey = requesterSessionKey?.trim();
+        if (!trimmedRequesterSessionKey) {
+            return undefined;
+        }
+        return (this.resolveTrackedSession({ requesterSessionKey: trimmedRequesterSessionKey }) ??
+            this.ensureSession({
+                sessionKey: trimmedRequesterSessionKey,
+                requesterSessionKey: trimmedRequesterSessionKey,
+                source: 'lazy_session',
+                timestamp: timestampMicros,
+                deferRootOpen: true,
+            }));
+    }
+    /** Open a deferred child session root once the requester scope is known. */
+    promoteDeferredSubagentSession(childSessionKey) {
+        const session = this.resolveTrackedSession({ sessionKey: childSessionKey, childSessionKey });
+        if (!session) {
+            return;
+        }
+        this.materializeDeferredSessionRoot(session);
+    }
+    /** Promote any deferred child sessions waiting on a requester root once it exists. */
+    promoteDeferredSubagentSessionsForRequester(requesterSessionKey) {
+        const trimmedRequesterSessionKey = requesterSessionKey?.trim();
+        if (!trimmedRequesterSessionKey) {
+            return;
+        }
+        const requesterSession = this.resolveTrackedSession({ requesterSessionKey: trimmedRequesterSessionKey });
+        if (!requesterSession?.rootHandle) {
+            return;
+        }
+        for (const lineage of this.pendingSubagentLineageByChildSessionKey.values()) {
+            if (lineage.requesterSessionKey === trimmedRequesterSessionKey) {
+                this.promoteDeferredSubagentSession(lineage.childSessionKey);
+            }
+        }
+    }
+    /** Materialize one deferred session root with nested lineage when available. */
+    materializeDeferredSessionRoot(session) {
+        if (session.rootHandle) {
+            return;
+        }
+        this.pruneExpiredPendingSubagentLineage(Date.now());
+        const lineage = this.resolvePendingSubagentLineage({
+            sessionId: session.sessionId,
+            sessionKey: session.sessionKey,
+        });
+        const parentSession = lineage === undefined
+            ? undefined
+            : this.ensureRequesterSessionAnchor(lineage.requesterSessionKey, session.pendingRootTimestampMicros);
+        if (parentSession && !parentSession.rootHandle) {
+            materializeSessionRoot(this.sessionManager(), parentSession, {
+                sessionId: parentSession.sessionId,
+                sessionKey: parentSession.sessionKey ?? lineage?.requesterSessionKey,
+                source: parentSession.source,
+                resumedFrom: parentSession.resumedFrom,
+                timestamp: parentSession.pendingRootTimestampMicros,
+            });
+        }
+        const parentHandle = parentSession?.rootHandle;
+        materializeSessionRoot(this.sessionManager(), session, {
+            sessionId: session.sessionId,
+            sessionKey: session.sessionKey,
+            runId: lineage?.runId,
+            agentId: session.agentId ?? lineage?.agentId,
+            source: session.source,
+            resumedFrom: session.resumedFrom,
+            scopeRole: session.scopeRole,
+            parentHandle,
+        });
+    }
+    /** Resolve stable subagent lineage from child session key first, then run id as a fallback. */
+    resolvePendingSubagentLineage(input) {
+        const childSessionKey = [input.sessionKey, input.childSessionKey]
+            .find((value) => this.isDocumentedSubagentSessionKey(value))
+            ?.trim();
+        if (childSessionKey) {
+            return this.pendingSubagentLineageByChildSessionKey.get(childSessionKey);
+        }
+        const runChildSessionKey = typeof input.runId === 'string' && input.runId.length > 0 ? this.pendingSubagentChildKeyByRunId.get(input.runId) : undefined;
+        return runChildSessionKey === undefined ? undefined : this.pendingSubagentLineageByChildSessionKey.get(runChildSessionKey);
+    }
+    /** Drop stale pending lineage entries so abandoned subagent spawns do not accumulate indefinitely. */
+    pruneExpiredPendingSubagentLineage(nowMs) {
+        const ttlMs = this.config.correlation.recordTtlMs;
+        for (const [childSessionKey, lineage] of this.pendingSubagentLineageByChildSessionKey) {
+            if (nowMs - lineage.observedAtMs > ttlMs) {
+                this.pendingSubagentLineageByChildSessionKey.delete(childSessionKey);
+            }
+        }
+        for (const [runId, childSessionKey] of this.pendingSubagentChildKeyByRunId) {
+            if (!this.pendingSubagentLineageByChildSessionKey.has(childSessionKey)) {
+                this.pendingSubagentChildKeyByRunId.delete(runId);
+            }
+        }
+    }
+    /** Resolve one session through the same alias map used by the replay state. */
+    resolveTrackedSession(input) {
+        const ownerKey = resolveSessionOwnerKey(this.stateValue, input);
+        return ownerKey === undefined ? undefined : this.stateValue.sessions.get(ownerKey);
+    }
+    /** Free lineage bookkeeping once the child session is closed. */
+    forgetPendingSubagentLineage(session) {
+        const childSessionKey = session.sessionKey;
+        if (childSessionKey) {
+            this.pendingSubagentLineageByChildSessionKey.delete(childSessionKey);
+        }
+        for (const [runId, trackedChildSessionKey] of this.pendingSubagentChildKeyByRunId) {
+            if (trackedChildSessionKey === childSessionKey) {
+                this.pendingSubagentChildKeyByRunId.delete(runId);
+            }
+        }
+    }
+    /** Match the documented native subagent session key shape without depending on private OpenClaw internals. */
+    isDocumentedSubagentSessionKey(value) {
+        return typeof value === 'string' && /^agent:[^:]+:subagent:/.test(value);
+    }
     /** Log one warning per key to avoid noisy repeated hook failures. */
     logBoundedWarn(key, message) {
         const count = this.warningCounts.get(key) ?? 0;
@@ -307,9 +510,12 @@ export class HookReplayBackend {
     }
 }
 export { llmKey };
-/** Expose session-key resolution for tests without exporting the full session module. */
-export function resolveBackendSessionKey(state, input) {
-    return resolveSessionKey(state, input);
+/** Expose owner-key resolution for tests without exporting the full session module. */
+export function resolveBackendSessionOwnerKey(state, input) {
+    return resolveSessionOwnerKey(state, input);
+}
+function microsToMs(timestampMicros) {
+    return timestampMicros === undefined ? undefined : Math.trunc(timestampMicros / 1000);
 }
 /** Build the lifecycle summary stored as the session_end mark payload. */
 function sessionEndSummary(event) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nemo-relay-openclaw",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "NeMo Relay-authored observability plugin for OpenClaw.",
   "type": "module",
   "repository": {
@@ -63,7 +63,7 @@
     "openclaw": "^2026.5.26"
   },
   "dependencies": {
-    "nemo-relay-node": "0.3.0"
+    "nemo-relay-node": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",