nemo-relay-openclaw 0.3.0 → 0.5.0

package/dist/src/hook-replay/session.js

@@ -1,16 +1,34 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { evictExpiredRecords, tupleKey as tupleKeyFromCorrelation } from './correlation.js';
+import { evictExpiredRecords, tupleKey as tupleKeyFromCorrelation, } from './correlation.js';
+import { toJsonRecord } from './marks.js';
+/** Merge lineage/root-context defaults without letting undefined hook fields erase them. */
+function mergeEnsureSessionInput(input, context) {
+    if (!context) {
+        return input;
+    }
+    const merged = { ...context, ...input };
+    for (const [key, value] of Object.entries(context)) {
+        if (merged[key] === undefined && value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+/** Return the session key that belongs to the session itself, not a requester alias. */
+function ownSessionKey(input) {
+    return input.sessionKey ?? input.childSessionKey;
+}
 /** Return all keys that may identify an existing OpenClaw session. */
 export function lookupSessionKeys(input) {
     return [input.sessionId, input.sessionKey, input.requesterSessionKey, input.childSessionKey, input.runId].filter((value) => typeof value === 'string' && value.length > 0);
 }
-/** Return keys that should alias to a canonical session once it is known. */
+/** Return keys that should alias to one stable internal session owner. */
 export function aliasSessionKeys(input) {
-    return [input.sessionId, input.sessionKey, input.requesterSessionKey, input.runId].filter((value) => typeof value === 'string' && value.length > 0);
+    return [input.sessionId, input.sessionKey, input.childSessionKey, input.requesterSessionKey, input.runId].filter((value) => typeof value === 'string' && value.length > 0);
 }
-/** Resolve a hook's session identity to the canonical session id used in replay state. */
-export function resolveSessionKey(state, input) {
+/** Resolve a hook's session identity to the stable owner key used in replay state. */
+export function resolveSessionOwnerKey(state, input) {
     for (const key of lookupSessionKeys(input)) {
         const canonical = state.sessionAliases.get(key);
         if (canonical) {
@@ -19,10 +37,10 @@ export function resolveSessionKey(state, input) {
     }
     return input.sessionId ?? input.sessionKey ?? input.childSessionKey ?? input.runId;
 }
-/** Remember equivalent hook identifiers so later events attach to the same root span. */
+/** Remember equivalent hook identifiers so later events attach to the same owner and root span. */
 export function rememberSessionAliases(state, session, input) {
     for (const alias of aliasSessionKeys(input)) {
-        state.sessionAliases.set(alias, session.sessionId);
+        state.sessionAliases.set(alias, session.ownerKey);
     }
 }
 /** Create the mutable in-memory state used by the hook replay backend. */
@@ -45,42 +63,96 @@ export function createHookReplayState() {
 }
 /** Return an existing session or lazily create a root session scope for replay. */
 export function ensureSession(manager, input) {
-    const key = resolveSessionKey(manager.state, input);
-    if (!key) {
+    const resolvedInput = mergeEnsureSessionInput(input, manager.resolveSessionRootContext?.(input));
+    const ownerKey = resolveSessionOwnerKey(manager.state, resolvedInput);
+    if (!ownerKey) {
         manager.state.counters.skippedEvents += 1;
         manager.logBoundedWarn('missing-session-key', 'nemo-relay skipped replay because no session/run key was available');
         return undefined;
     }
-    const existing = manager.state.sessions.get(key);
+    const existing = manager.state.sessions.get(ownerKey);
     if (existing) {
-        rememberSessionAliases(manager.state, existing, input);
+        enrichSession(existing, resolvedInput);
+        rememberSessionAliases(manager.state, existing, resolvedInput);
+        if (!existing.rootHandle && resolvedInput.deferRootOpen !== true) {
+            materializeSessionRoot(manager, existing, resolvedInput);
+        }
         return existing;
     }
-    const canonicalSessionId = input.sessionId ?? key;
-    const aliased = manager.state.sessions.get(canonicalSessionId);
-    if (aliased) {
-        rememberSessionAliases(manager.state, aliased, input);
-        return aliased;
-    }
     const stack = manager.nf.createScopeStack();
     const session = {
-        sessionId: canonicalSessionId,
-        source: input.source,
+        ownerKey,
+        sessionId: resolvedInput.sessionId ?? ownerKey,
+        source: resolvedInput.source,
         stack,
     };
-    if (input.sessionKey !== undefined) {
-        session.sessionKey = input.sessionKey;
+    const sessionKey = ownSessionKey(resolvedInput);
+    if (sessionKey !== undefined) {
+        session.sessionKey = sessionKey;
+    }
+    if (resolvedInput.agentId !== undefined) {
+        session.agentId = resolvedInput.agentId;
+    }
+    if (resolvedInput.resumedFrom !== undefined) {
+        session.resumedFrom = resolvedInput.resumedFrom;
+    }
+    if (resolvedInput.scopeRole !== undefined) {
+        session.scopeRole = resolvedInput.scopeRole;
+    }
+    if (resolvedInput.deferRootOpen === true) {
+        session.pendingRootOpen = true;
+        if (resolvedInput.timestamp !== undefined) {
+            session.pendingRootTimestampMicros = resolvedInput.timestamp;
+        }
+        if (resolvedInput.runId !== undefined) {
+            session.pendingRootRunId = resolvedInput.runId;
+        }
+        session.pendingCapturedEmits = [];
+    }
+    else {
+        materializeSessionRoot(manager, session, resolvedInput);
+    }
+    manager.state.sessions.set(session.ownerKey, session);
+    rememberSessionAliases(manager.state, session, resolvedInput);
+    return session;
+}
+/** Fill stable session identifiers from later hooks without clobbering established values. */
+function enrichSession(session, input) {
+    const sessionKey = ownSessionKey(input);
+    if (session.sessionKey === undefined && sessionKey !== undefined) {
+        session.sessionKey = sessionKey;
     }
-    if (input.agentId !== undefined) {
+    if (session.agentId === undefined && input.agentId !== undefined) {
         session.agentId = input.agentId;
     }
-    if (input.resumedFrom !== undefined) {
+    if (session.resumedFrom === undefined && input.resumedFrom !== undefined) {
         session.resumedFrom = input.resumedFrom;
     }
-    openSessionRoot(manager, session, input);
-    manager.state.sessions.set(session.sessionId, session);
-    rememberSessionAliases(manager.state, session, input);
-    return session;
+    if (session.scopeRole === undefined && input.scopeRole !== undefined) {
+        session.scopeRole = input.scopeRole;
+    }
+    if (!session.rootHandle && input.sessionId !== undefined) {
+        session.sessionId = input.sessionId;
+    }
+    if (!session.rootHandle && session.source === 'lazy_session' && input.source === 'session_start') {
+        session.source = 'session_start';
+    }
+    if (!session.rootHandle && input.timestamp !== undefined) {
+        if (input.source === 'session_start' || session.pendingRootTimestampMicros === undefined) {
+            session.pendingRootTimestampMicros = input.timestamp;
+        }
+    }
+    if (!session.rootHandle && session.pendingRootRunId === undefined && input.runId !== undefined) {
+        session.pendingRootRunId = input.runId;
+    }
+}
+/** Queue an emit callback until a deferred session root can open with honest lineage. */
+export function queueCapturedEmit(session, label, emit) {
+    if (session.rootHandle || session.pendingRootOpen !== true) {
+        return false;
+    }
+    (session.pendingCapturedEmits ??= []).push({ label, emit });
+    return true;
 }
 /** Flush pending LLM output/timing state before the root session closes. */
 export function drainSession(manager, session) {
@@ -90,12 +162,12 @@ export function drainSession(manager, session) {
     evictSessionCorrelationRecords(manager.state, session);
 }
 /** Close the root session scope with separate lifecycle summary and user-visible output. */
-export function closeSessionRoot(manager, session, summary, rootOutput = summary, timestamp) {
+export function closeSessionRoot(manager, session, summary, rootOutput = summary, metadata, timestamp) {
     manager.emitCapturedUnderSession('session_end', session, () => {
         if (!session.rootHandle) {
             return;
         }
-        manager.nf.event('openclaw.session_end', session.rootHandle, summary, null, timestamp ?? null);
+        manager.nf.event('openclaw.session_end', session.rootHandle, summary, metadata ?? null, timestamp ?? null);
         manager.state.counters.marksEmitted += 1;
         manager.nf.popScope(session.rootHandle, rootOutput, timestamp ?? null);
         delete session.rootHandle;
@@ -103,7 +175,7 @@ export function closeSessionRoot(manager, session, summary, rootOutput = summary
 }
 /** Remove a closed session from active replay state. */
 export function deleteSession(state, session) {
-    state.sessions.delete(session.sessionId);
+    state.sessions.delete(session.ownerKey);
 }
 /** Insert a correlation record while bounding retained entries per key. */
 export function insertBoundedRecord(map, key, record, maxRecordsPerKey) {
@@ -125,27 +197,55 @@ export function evictExpiredCorrelationRecords(state, nowMs, ttlMs) {
     evictExpiredRecords(state.modelCallsByCallId, nowMs, ttlMs);
     evictExpiredRecords(state.modelTimingsByLlmKey, nowMs, ttlMs);
 }
-/** Open the root NeMo Relay scope for one OpenClaw session and emit session_start. */
-function openSessionRoot(manager, session, input) {
+/** Open a deferred or new root session scope and flush queued child emissions. */
+export function materializeSessionRoot(manager, session, input) {
+    if (session.rootHandle) {
+        return;
+    }
+    enrichSession(session, input);
+    const timestampMicros = input.timestamp ?? session.pendingRootTimestampMicros ?? null;
+    const rootRunId = input.runId ?? session.pendingRootRunId;
     const data = {
         sessionId: session.sessionId,
         source: session.source,
         ...(session.sessionKey === undefined ? {} : { sessionKey: session.sessionKey }),
         ...(session.agentId === undefined ? {} : { agentId: session.agentId }),
-        ...(input.runId === undefined ? {} : { runId: input.runId }),
+        ...(rootRunId === undefined ? {} : { runId: rootRunId }),
         ...(session.resumedFrom === undefined ? {} : { resumedFrom: session.resumedFrom }),
     };
-    manager.emitCapturedUnderSession('session_start', session, () => {
-        session.rootHandle = manager.nf.pushScope('openclaw.session', agentScopeType(manager.nf), null, null, data, null, null, input.timestamp ?? null);
-        manager.nf.event('openclaw.session_start', session.rootHandle, data, null, input.timestamp ?? null);
-        manager.state.counters.marksEmitted += 1;
+    const metadata = toJsonRecord({
+        source: session.source === 'session_start' ? 'openclaw.session_start' : 'openclaw.lazy_session',
+        hook_event_name: session.source === 'session_start' ? 'session_start' : undefined,
+        sessionId: session.sessionId,
+        sessionKey: session.sessionKey,
+        agentId: session.agentId,
+        runId: rootRunId,
+        nemo_relay_scope_role: session.scopeRole,
     });
+    const previousStack = manager.nf.currentScopeStack();
+    try {
+        manager.nf.setThreadScopeStack(session.stack);
+        session.rootHandle = manager.nf.pushScope('openclaw.session', agentScopeType(manager.nf), input.parentHandle ?? null, null, data, metadata, data, timestampMicros);
+        manager.nf.event('openclaw.session_start', session.rootHandle, data, metadata, timestampMicros);
+        manager.state.counters.marksEmitted += 1;
+    }
+    finally {
+        manager.nf.setThreadScopeStack(previousStack);
+    }
+    delete session.pendingRootOpen;
+    delete session.pendingRootTimestampMicros;
+    delete session.pendingRootRunId;
+    const pendingEmits = session.pendingCapturedEmits ?? [];
+    delete session.pendingCapturedEmits;
+    for (const pending of pendingEmits) {
+        manager.emitCapturedUnderSession(pending.label, session, pending.emit);
+    }
 }
 /** Cancel timers that would otherwise replay late LLM outputs after session close. */
 function cancelPendingLlmOutputTimers(state, session) {
     for (const records of state.llmOutputsPendingInput.values()) {
         for (const record of records) {
-            if (record.sessionKey === session.sessionId && record.timer) {
+            if (record.sessionOwnerKey === session.ownerKey && record.timer) {
                 clearTimeout(record.timer);
                 record.timer = undefined;
             }
@@ -154,20 +254,20 @@ function cancelPendingLlmOutputTimers(state, session) {
 }
 /** Remove all correlation records and aliases owned by a closed session. */
 function evictSessionCorrelationRecords(state, session) {
-    evictFromRecordMap(state.llmInputs, session.sessionId);
-    evictFromRecordMap(state.llmOutputsPendingInput, session.sessionId);
-    evictFromRecordMap(state.modelCallsByCallId, session.sessionId);
-    evictFromRecordMap(state.modelTimingsByLlmKey, session.sessionId);
-    for (const [alias, canonical] of state.sessionAliases) {
-        if (canonical === session.sessionId || alias === session.sessionId) {
+    evictFromRecordMap(state.llmInputs, session.ownerKey);
+    evictFromRecordMap(state.llmOutputsPendingInput, session.ownerKey);
+    evictFromRecordMap(state.modelCallsByCallId, session.ownerKey);
+    evictFromRecordMap(state.modelTimingsByLlmKey, session.ownerKey);
+    for (const [alias, ownerKey] of state.sessionAliases) {
+        if (ownerKey === session.ownerKey) {
             state.sessionAliases.delete(alias);
         }
     }
 }
 /** Drop records for one session from a single keyed correlation map. */
-function evictFromRecordMap(map, sessionKey) {
+function evictFromRecordMap(map, ownerKey) {
     for (const [key, records] of map) {
-        const retained = records.filter((record) => record.sessionKey !== sessionKey);
+        const retained = records.filter((record) => record.sessionOwnerKey !== ownerKey);
         if (retained.length === 0) {
             map.delete(key);
         }

package/dist/src/hook-replay/tool.js

@@ -5,12 +5,14 @@ import { ensureSession } from './session.js';
 import { nowMicros, startMicrosFromDuration } from './correlation.js';
 /** Run NeMo Relay tool conditional-execution guardrails before OpenClaw executes a tool. */
 export async function guardBeforeToolCall(manager, event, ctx) {
+    const observedAtMicros = nowMicros();
     const session = ensureSession(manager, {
         sessionId: ctx.sessionId,
         sessionKey: ctx.sessionKey,
         runId: event.runId ?? ctx.runId,
         agentId: ctx.agentId,
         source: 'lazy_session',
+        timestamp: observedAtMicros,
     });
     const args = toJsonValue(event.params ?? {});
     if (session) {
@@ -29,12 +31,15 @@ export async function guardBeforeToolCall(manager, event, ctx) {
 }
 /** Convert one OpenClaw after_tool_call event into a NeMo Relay tool span or blocked-tool mark. */
 export function replayAfterToolCall(manager, event, ctx) {
+    const endMicros = nowMicros();
+    const sessionTimestamp = startMicrosFromDuration(endMicros, event.durationMs) ?? endMicros;
     const session = ensureSession(manager, {
         sessionId: ctx.sessionId,
         sessionKey: ctx.sessionKey,
         runId: event.runId ?? ctx.runId,
         agentId: ctx.agentId,
         source: 'lazy_session',
+        timestamp: sessionTimestamp,
     });
     const blockedDetails = blockedToolDetails(event, { runId: event.runId ?? ctx.runId });
     if (session && blockedDetails) {
@@ -45,6 +50,16 @@ export function replayAfterToolCall(manager, event, ctx) {
                 session,
                 name: 'openclaw.tool_blocked',
                 data: blockedDetails,
+                metadata: toJsonRecord({
+                    source: 'openclaw.after_tool_call',
+                    hook_event_name: 'after_tool_call',
+                    sessionId: session.sessionId,
+                    sessionKey: session.sessionKey,
+                    agentId: session.agentId,
+                    runId: event.runId ?? ctx.runId,
+                    toolCallId: event.toolCallId ?? ctx.toolCallId,
+                }),
+                timestamp: endMicros,
             });
         });
         return;
@@ -52,12 +67,12 @@ export function replayAfterToolCall(manager, event, ctx) {
     if (!session) {
         return;
     }
-    const endMicros = nowMicros();
     const metadata = toJsonRecord({
         source: 'openclaw.after_tool_call',
         runId: event.runId ?? ctx.runId,
-        sessionId: ctx.sessionId,
-        sessionKey: ctx.sessionKey,
+        sessionId: session.sessionId,
+        sessionKey: session.sessionKey,
+        agentId: session.agentId,
         toolCallId: event.toolCallId ?? ctx.toolCallId,
         durationMs: event.durationMs,
     });

package/dist/src/hooks-backend.d.ts

@@ -7,7 +7,7 @@
  */
 import type { NemoRelayHookBackendConfig } from './config.js';
 import { llmKey } from './hook-replay/correlation.js';
-import { resolveSessionKey, type HookReplayBackendState, type SessionLookupInput, type SessionState } from './hook-replay/session.js';
+import { resolveSessionOwnerKey, type HookReplayBackendState, type SessionLookupInput, type SessionState } from './hook-replay/session.js';
 import type { NemoRelayRuntimeModule } from './modules.js';
 import type { PluginHookAfterToolCallEvent, PluginHookAgentContext, PluginHookAgentEndEvent, PluginHookBeforeAgentFinalizeEvent, PluginHookBeforeMessageWriteContext, PluginHookBeforeMessageWriteEvent, PluginHookBeforeToolCallEvent, PluginHookGatewayContext, PluginHookGatewayStartEvent, PluginHookLlmInputEvent, PluginHookLlmOutputEvent, PluginHookModelCallEndedEvent, PluginHookModelCallStartedEvent, PluginHookSessionContext, PluginHookSessionEndEvent, PluginHookSessionStartEvent, PluginHookSubagentContext, PluginHookSubagentEndedEvent, PluginHookSubagentSpawnedEvent, PluginHookToolContext } from './openclaw-hook-types.js';
 import type { PluginLogger } from 'openclaw/plugin-sdk/plugin-entry';
@@ -25,6 +25,8 @@ export declare class HookReplayBackend {
     private readonly agentVersion;
     private readonly stateValue;
     private readonly warningCounts;
+    private readonly pendingSubagentLineageByChildSessionKey;
+    private readonly pendingSubagentChildKeyByRunId;
     constructor(options: HookReplayBackendOptions);
     /** Return mutable replay state for tests and health snapshots. */
     state(): HookReplayBackendState;
@@ -88,9 +90,31 @@ export declare class HookReplayBackend {
     private flushSubscriberDelivery;
     /** Build the narrow manager interface consumed by focused replay modules. */
     private sessionManager;
+    /** Prefer nested child scopes only when the hook surface provides real subagent lineage. */
+    private resolveSessionRootContext;
+    /** Track stable parent/child lineage from subagent hooks until child session hooks can use it. */
+    private trackPendingSubagentLineage;
+    /** Resolve the requester session if it exists, or seed a deferred lazy root placeholder for later promotion. */
+    private ensureRequesterSessionAnchor;
+    /** Open a deferred child session root once the requester scope is known. */
+    private promoteDeferredSubagentSession;
+    /** Promote any deferred child sessions waiting on a requester root once it exists. */
+    private promoteDeferredSubagentSessionsForRequester;
+    /** Materialize one deferred session root with nested lineage when available. */
+    private materializeDeferredSessionRoot;
+    /** Resolve stable subagent lineage from child session key first, then run id as a fallback. */
+    private resolvePendingSubagentLineage;
+    /** Drop stale pending lineage entries so abandoned subagent spawns do not accumulate indefinitely. */
+    private pruneExpiredPendingSubagentLineage;
+    /** Resolve one session through the same alias map used by the replay state. */
+    private resolveTrackedSession;
+    /** Free lineage bookkeeping once the child session is closed. */
+    private forgetPendingSubagentLineage;
+    /** Match the documented native subagent session key shape without depending on private OpenClaw internals. */
+    private isDocumentedSubagentSessionKey;
     /** Log one warning per key to avoid noisy repeated hook failures. */
     private logBoundedWarn;
 }
 export { llmKey };
-/** Expose session-key resolution for tests without exporting the full session module. */
-export declare function resolveBackendSessionKey(state: HookReplayBackendState, input: Parameters<typeof resolveSessionKey>[1]): string | undefined;
+/** Expose owner-key resolution for tests without exporting the full session module. */
+export declare function resolveBackendSessionOwnerKey(state: HookReplayBackendState, input: Parameters<typeof resolveSessionOwnerKey>[1]): string | undefined;