nemo-relay-openclaw 0.3.0 → 0.4.0

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

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 import { emitMark, toJsonRecord, toJsonValue } from './marks.js';
-import { evictExpiredCorrelationRecords, ensureSession, insertBoundedRecord, resolveSessionKey, } from './session.js';
+import { evictExpiredCorrelationRecords, ensureSession, insertBoundedRecord, resolveSessionOwnerKey, } from './session.js';
 import { llmKey, modelTimingKey, modelTimingLlmKey, nowMicros, startMicrosFromDuration } from './correlation.js';
 /**
  * Store one OpenClaw llm_input snapshot and replay it immediately if the matching
@@ -9,12 +9,14 @@ import { llmKey, modelTimingKey, modelTimingLlmKey, nowMicros, startMicrosFromDu
  */
 export function recordLlmInput(manager, event, ctx) {
     evictExpiredReplayRecords(manager);
+    const observedAtMicros = nowMicros();
     const session = ensureSession(manager, {
         sessionId: event.sessionId,
         sessionKey: ctx.sessionKey,
         runId: event.runId,
         agentId: ctx.agentId,
         source: 'lazy_session',
+        timestamp: observedAtMicros,
     });
     if (!session) {
         return;
@@ -26,7 +28,7 @@ export function recordLlmInput(manager, event, ctx) {
     const key = llmKey(event);
     const input = createInputRecord(session, event);
     insertBoundedRecord(manager.state.llmInputs, key, input, manager.config.correlation.maxRecordsPerKey);
-    const pending = shiftOldest(manager.state.llmOutputsPendingInput, key, (record) => record.sessionKey === session.sessionId);
+    const pending = shiftOldest(manager.state.llmOutputsPendingInput, key, (record) => record.sessionOwnerKey === session.ownerKey);
     if (!pending) {
         return;
     }
@@ -48,22 +50,24 @@ export function recordLlmInput(manager, event, ctx) {
  */
 export function recordLlmOutput(manager, event, ctx) {
     evictExpiredReplayRecords(manager);
+    const observedAtMicros = nowMicros();
     const session = ensureSession(manager, {
         sessionId: event.sessionId,
         sessionKey: ctx.sessionKey,
         runId: event.runId,
         agentId: ctx.agentId,
         source: 'lazy_session',
+        timestamp: observedAtMicros,
     });
     if (!session) {
         return;
     }
     const key = llmKey(event);
     if (hasTrajectoryReplay(session, event.runId)) {
-        shiftOldest(manager.state.llmInputs, key, (record) => record.sessionKey === session.sessionId);
+        shiftOldest(manager.state.llmInputs, key, (record) => record.sessionOwnerKey === session.ownerKey);
         return;
     }
-    const input = shiftOldest(manager.state.llmInputs, key, (record) => record.sessionKey === session.sessionId);
+    const input = shiftOldest(manager.state.llmInputs, key, (record) => record.sessionOwnerKey === session.ownerKey);
     if (input) {
         replayLlmOutput({
             manager,
@@ -75,7 +79,7 @@ export function recordLlmOutput(manager, event, ctx) {
         return;
     }
     const pending = {
-        sessionKey: session.sessionId,
+        sessionOwnerKey: session.ownerKey,
         sessionId: event.sessionId,
         runId: event.runId,
         provider: event.provider,
@@ -120,7 +124,7 @@ export function recordBeforeMessageWrite(manager, event, ctx) {
         if (provider && model && (assistantTexts.length > 0 || assistantToolCalls.length > 0 || usage !== undefined)) {
             session.assistantMessageWrites ??= [];
             session.assistantMessageWrites.push({
-                sessionKey: session.sessionId,
+                sessionOwnerKey: session.ownerKey,
                 provider,
                 model,
                 assistantTexts,
@@ -158,7 +162,7 @@ export function recordModelCallStarted(manager, event, ctx) {
         return;
     }
     insertBoundedRecord(manager.state.modelCallsByCallId, modelTimingKey(event), {
-        sessionKey: session.sessionId,
+        sessionOwnerKey: session.ownerKey,
         sessionId: session.sessionId,
         runId: event.runId,
         callId: event.callId,
@@ -191,7 +195,7 @@ export function recordModelCallEnded(manager, event, ctx) {
     const existing = latestUnendedRecord(manager.state.modelCallsByCallId.get(byCallKey), session);
     const record = existing ??
         {
-            sessionKey: session.sessionId,
+            sessionOwnerKey: session.ownerKey,
             sessionId: session.sessionId,
             runId: event.runId,
             callId: event.callId,
@@ -205,7 +209,7 @@ export function recordModelCallEnded(manager, event, ctx) {
         insertBoundedRecord(manager.state.modelCallsByCallId, byCallKey, record, manager.config.correlation.maxRecordsPerKey);
     }
     insertBoundedRecord(manager.state.modelTimingsByLlmKey, modelTimingLlmKey({
-        sessionId: session.sessionId,
+        sessionId: session.ownerKey,
         runId: event.runId,
         provider: event.provider,
         model: event.model,
@@ -219,7 +223,7 @@ export function replayPendingLlmOutputsForSession(manager, session, options) {
     for (const [key, records] of [...manager.state.llmOutputsPendingInput]) {
         const remaining = [];
         for (const record of records) {
-            if (record.sessionKey !== session.sessionId) {
+            if (record.sessionOwnerKey !== session.ownerKey) {
                 remaining.push(record);
                 continue;
             }
@@ -274,7 +278,7 @@ export function replayAgentEndMessages(manager, event, ctx, session) {
 export function emitUnpairedModelCallTimingMarks(manager, session) {
     for (const records of manager.state.modelCallsByCallId.values()) {
         for (const record of records) {
-            if (record.sessionKey !== session.sessionId || record.consumed || record.endedAtMs !== undefined) {
+            if (record.sessionOwnerKey !== session.ownerKey || record.consumed || record.endedAtMs !== undefined) {
                 continue;
             }
             emitModelTimingMark(manager, session, 'openclaw.model_call_timing_unpaired', record);
@@ -284,7 +288,7 @@ export function emitUnpairedModelCallTimingMarks(manager, session) {
     const unpairedEnded = [];
     for (const records of manager.state.modelTimingsByLlmKey.values()) {
         for (const record of records) {
-            if (record.sessionKey !== session.sessionId || record.consumed) {
+            if (record.sessionOwnerKey !== session.ownerKey || record.consumed) {
                 continue;
             }
             unpairedEnded.push(record);
@@ -362,7 +366,7 @@ function replayExpiredPendingOutput(manager, key, record) {
         if (!removeRecord(manager.state.llmOutputsPendingInput, key, record)) {
             return;
         }
-        const session = manager.state.sessions.get(record.sessionKey);
+        const session = manager.state.sessions.get(record.sessionOwnerKey);
         if (!session) {
             manager.state.counters.skippedEvents += 1;
             return;
@@ -408,7 +412,9 @@ function replayLlmOutput(params) {
     const metadata = toJsonRecord({
         source,
         runId: event.runId,
-        sessionId: event.sessionId,
+        sessionId: session.sessionId,
+        sessionKey: session.sessionKey,
+        agentId: session.agentId,
         provider: event.provider,
         model: event.model,
         callId: timing?.callId,
@@ -452,7 +458,7 @@ function replayAssistantMessageWrites(manager, session, event, ctx) {
             },
             ctx,
             input: {
-                sessionKey: session.sessionId,
+                sessionOwnerKey: session.ownerKey,
                 sessionId: session.sessionId,
                 runId,
                 provider: record.provider,
@@ -475,13 +481,13 @@ function replayAssistantMessageWrites(manager, session, event, ctx) {
 /** Consume the next unpaired timing record for message-write trajectory replay. */
 function consumeNextTimingCandidate(manager, session, input) {
     const key = modelTimingLlmKey({
-        sessionId: session.sessionId,
+        sessionId: session.ownerKey,
         runId: input.runId,
         provider: input.provider,
         model: input.model,
     });
     const records = manager.state.modelTimingsByLlmKey.get(key) ?? [];
-    const candidate = records.find((record) => record.sessionKey === session.sessionId && !record.consumed);
+    const candidate = records.find((record) => record.sessionOwnerKey === session.ownerKey && !record.consumed);
     if (!candidate) {
         return undefined;
     }
@@ -491,12 +497,12 @@ function consumeNextTimingCandidate(manager, session, input) {
 /** Consume a timing candidate only when the public hook data makes it unambiguous. */
 function consumeTimingCandidate(manager, session, event) {
     const key = modelTimingLlmKey({
-        sessionId: session.sessionId,
+        sessionId: session.ownerKey,
         runId: event.runId,
         provider: event.provider,
         model: event.model,
     });
-    const candidates = (manager.state.modelTimingsByLlmKey.get(key) ?? []).filter((record) => record.sessionKey === session.sessionId && !record.consumed);
+    const candidates = (manager.state.modelTimingsByLlmKey.get(key) ?? []).filter((record) => record.sessionOwnerKey === session.ownerKey && !record.consumed);
     if (candidates.length === 1) {
         const candidate = candidates[0];
         if (!candidate) {
@@ -580,7 +586,7 @@ function emitModelTimingSummaryMark(manager, session, records) {
 /** Convert an OpenClaw llm_input event into the buffered request record. */
 function createInputRecord(session, event) {
     return {
-        sessionKey: session.sessionId,
+        sessionOwnerKey: session.ownerKey,
         sessionId: event.sessionId,
         runId: event.runId,
         provider: event.provider,
@@ -594,15 +600,23 @@ function createInputRecord(session, event) {
 }
 /** Resolve an existing session for before_message_write without creating a fake one. */
 function existingSessionForMessageWrite(manager, event, ctx) {
-    const key = resolveSessionKey(manager.state, {
+    const key = resolveSessionOwnerKey(manager.state, {
         sessionKey: event.sessionKey ?? ctx.sessionKey,
     });
-    return key === undefined ? undefined : manager.state.sessions.get(key);
+    if (key === undefined) {
+        return undefined;
+    }
+    const session = manager.state.sessions.get(key);
+    const sessionKey = event.sessionKey ?? ctx.sessionKey;
+    if (session && session.sessionKey === undefined && sessionKey !== undefined) {
+        session.sessionKey = sessionKey;
+    }
+    return session;
 }
 /** Build a minimal request placeholder when only an llm_output hook is available. */
 function placeholderInputRecord(record) {
     return {
-        sessionKey: record.sessionKey,
+        sessionOwnerKey: record.sessionOwnerKey,
         sessionId: record.sessionId,
         runId: record.runId,
         provider: record.provider,
@@ -941,19 +955,33 @@ function incrementHookLlmOutputReplayCount(session, runId, maxRuns) {
 }
 /** Build the per-session run key used for trajectory de-duplication. */
 function trajectoryRunKey(session, runId) {
-    return runId ?? session.sessionId;
+    return runId ?? session.ownerKey;
 }
-/** Normalize provider usage into OpenInference-friendly token/cost fields. */
+/** Normalize provider usage into NeMo Relay token and cost fields. */
 function mapUsage(usage) {
     if (!isRecord(usage)) {
         return undefined;
     }
     const mapped = {};
-    const input = numberField(usage, 'input') ?? numberField(usage, 'prompt_tokens');
-    const output = numberField(usage, 'output') ?? numberField(usage, 'completion_tokens');
-    const cacheRead = numberField(usage, 'cacheRead') ?? numberField(usage, 'cache_read_tokens');
-    const cacheWrite = numberField(usage, 'cacheWrite') ?? numberField(usage, 'cache_write_tokens');
-    const total = numberField(usage, 'total') ?? numberField(usage, 'totalTokens') ?? numberField(usage, 'total_tokens');
+    const input = numberField(usage, 'input') ??
+        numberField(usage, 'prompt_tokens') ??
+        numberField(usage, 'input_tokens') ??
+        numberField(usage, 'inputTokens');
+    const output = numberField(usage, 'output') ??
+        numberField(usage, 'completion_tokens') ??
+        numberField(usage, 'output_tokens') ??
+        numberField(usage, 'outputTokens');
+    const cacheRead = numberField(usage, 'cacheRead') ??
+        numberField(usage, 'cache_read_tokens') ??
+        numberField(usage, 'cache_read_input_tokens') ??
+        nestedNumberField(usage, 'input_tokens_details', 'cached_tokens') ??
+        nestedNumberField(usage, 'prompt_tokens_details', 'cached_tokens');
+    const cacheWrite = numberField(usage, 'cacheWrite') ??
+        numberField(usage, 'cache_write_tokens') ??
+        numberField(usage, 'cache_creation_input_tokens');
+    const total = numberField(usage, 'total') ??
+        numberField(usage, 'totalTokens') ??
+        numberField(usage, 'total_tokens');
     const totalCanIncludeCompletion = total === undefined || output === undefined || total >= output;
     const prompt = total !== undefined && output !== undefined && totalCanIncludeCompletion ? total - output : input;
     const totalCanIncludePrompt = total === undefined || prompt === undefined || total >= prompt;
@@ -993,6 +1021,11 @@ function numberField(record, key) {
     const value = record[key];
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
+/** Read a finite numeric field nested one object deep from a generic hook record. */
+function nestedNumberField(record, objectKey, fieldKey) {
+    const value = record[objectKey];
+    return isRecord(value) ? numberField(value, fieldKey) : undefined;
+}
 /** Copy model_call_ended details into a retained timing record. */
 function applyModelCallEnd(record, event, nowMs) {
     record.observedAtMs = nowMs;
@@ -1015,7 +1048,7 @@ function latestUnendedRecord(records, session) {
     }
     for (let index = records.length - 1; index >= 0; index -= 1) {
         const record = records[index];
-        if (record?.sessionKey === session.sessionId && record.endedAtMs === undefined) {
+        if (record?.sessionOwnerKey === session.ownerKey && record.endedAtMs === undefined) {
             return record;
         }
     }

package/dist/src/hook-replay/marks.d.ts

@@ -16,6 +16,7 @@ export declare function emitMark(params: {
     session: SessionState;
     name: string;
     data: JsonRecord;
+    metadata?: JsonRecord | null;
     timestamp?: number;
 }): void;
 /** Return a blocked-tool event payload when OpenClaw denied the tool call. */

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

@@ -6,7 +6,7 @@ export function emitMark(params) {
         params.state.counters.skippedEvents += 1;
         return;
     }
-    params.nf.event(params.name, params.session.rootHandle, params.data, null, params.timestamp ?? null);
+    params.nf.event(params.name, params.session.rootHandle, params.data, params.metadata ?? null, params.timestamp ?? null);
     params.state.counters.marksEmitted += 1;
 }
 /** Return a blocked-tool event payload when OpenClaw denied the tool call. */

package/dist/src/hook-replay/session.d.ts

@@ -19,11 +19,16 @@ export type SessionLookupInput = {
 };
 export type EnsureSessionInput = SessionLookupInput & {
     agentId?: string | undefined;
+    parentHandle?: ReturnType<NemoRelayRuntimeModule['pushScope']> | undefined;
+    scopeRole?: 'subagent' | undefined;
     source: 'session_start' | 'lazy_session';
     resumedFrom?: string | undefined;
     timestamp?: number | undefined;
+    deferRootOpen?: boolean | undefined;
 };
 export type SessionState = {
+    /** Immutable internal owner key used for replay buffers and alias lookups. */
+    ownerKey: string;
     sessionId: string;
     sessionKey?: string;
     agentId?: string;
@@ -42,9 +47,17 @@ export type SessionState = {
     assistantMessageWrites?: AssistantMessageRecord[];
     stack: ReturnType<NemoRelayRuntimeModule['createScopeStack']>;
     rootHandle?: ReturnType<NemoRelayRuntimeModule['pushScope']>;
+    scopeRole?: 'subagent';
+    pendingRootOpen?: boolean;
+    pendingRootTimestampMicros?: number;
+    pendingRootRunId?: string;
+    pendingCapturedEmits?: Array<{
+        label: string;
+        emit: () => void;
+    }>;
 };
 export type PendingLlmOutputRecord = {
-    sessionKey: string;
+    sessionOwnerKey: string;
     sessionId: string;
     runId: string;
     provider: string;
@@ -55,7 +68,7 @@ export type PendingLlmOutputRecord = {
     timer?: ReturnType<typeof setTimeout> | undefined;
 };
 export type LlmInputRecord = {
-    sessionKey: string;
+    sessionOwnerKey: string;
     sessionId: string;
     runId: string;
     provider: string;
@@ -68,7 +81,7 @@ export type LlmInputRecord = {
     placeholderRequest?: boolean | undefined;
 };
 export type AssistantMessageRecord = {
-    sessionKey: string;
+    sessionOwnerKey: string;
     provider: string;
     model: string;
     assistantTexts: string[];
@@ -80,7 +93,7 @@ export type AssistantMessageRecord = {
     usage?: unknown;
 };
 export type ModelCallRecord = {
-    sessionKey: string;
+    sessionOwnerKey: string;
     runId: string;
     callId: string;
     provider: string;
@@ -130,23 +143,26 @@ export type SessionManager = {
     }) => void;
     emitUnpairedModelCallTimingMarks: (session: SessionState) => void;
     logBoundedWarn: (key: string, message: string) => void;
+    resolveSessionRootContext?: (input: EnsureSessionInput) => Partial<EnsureSessionInput> | undefined;
 };
 /** Return all keys that may identify an existing OpenClaw session. */
 export declare function lookupSessionKeys(input: SessionLookupInput): string[];
-/** 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 declare function aliasSessionKeys(input: SessionLookupInput): string[];
-/** Resolve a hook's session identity to the canonical session id used in replay state. */
-export declare function resolveSessionKey(state: HookReplayBackendState, input: SessionLookupInput): string | undefined;
-/** Remember equivalent hook identifiers so later events attach to the same root span. */
+/** Resolve a hook's session identity to the stable owner key used in replay state. */
+export declare function resolveSessionOwnerKey(state: HookReplayBackendState, input: SessionLookupInput): string | undefined;
+/** Remember equivalent hook identifiers so later events attach to the same owner and root span. */
 export declare function rememberSessionAliases(state: HookReplayBackendState, session: SessionState, input: SessionLookupInput): void;
 /** Create the mutable in-memory state used by the hook replay backend. */
 export declare function createHookReplayState(): HookReplayBackendState;
 /** Return an existing session or lazily create a root session scope for replay. */
 export declare function ensureSession(manager: SessionManager, input: EnsureSessionInput): SessionState | undefined;
+/** Queue an emit callback until a deferred session root can open with honest lineage. */
+export declare function queueCapturedEmit(session: SessionState, label: string, emit: () => void): boolean;
 /** Flush pending LLM output/timing state before the root session closes. */
 export declare function drainSession(manager: SessionManager, session: SessionState): void;
 /** Close the root session scope with separate lifecycle summary and user-visible output. */
-export declare function closeSessionRoot(manager: SessionManager, session: SessionState, summary: JsonRecord, rootOutput?: JsonRecord, timestamp?: number): void;
+export declare function closeSessionRoot(manager: SessionManager, session: SessionState, summary: JsonRecord, rootOutput?: JsonRecord, metadata?: JsonRecord | null, timestamp?: number): void;
 /** Remove a closed session from active replay state. */
 export declare function deleteSession(state: HookReplayBackendState, session: SessionState): void;
 /** Insert a correlation record while bounding retained entries per key. */
@@ -155,3 +171,5 @@ export declare function insertBoundedRecord<T>(map: Map<string, T[]>, key: strin
 export declare function tupleKey(parts: Array<string | undefined>): string;
 /** Evict stale cross-hook correlation records across all replay maps. */
 export declare function evictExpiredCorrelationRecords(state: HookReplayBackendState, nowMs: number, ttlMs: number): void;
+/** Open a deferred or new root session scope and flush queued child emissions. */
+export declare function materializeSessionRoot(manager: SessionManager, session: SessionState, input: EnsureSessionInput): void;