nemo-relay-openclaw 0.0.0 → 0.3.0-beta.2

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

@@ -0,0 +1,52 @@
+/**
+ * LLM span reconstruction for OpenClaw hook replay.
+ *
+ * OpenClaw currently exposes public hooks for request snapshots, assistant
+ * outputs, message writes, and model-call timing as separate event streams. This
+ * module correlates those signals into NeMo Relay LLM spans while staying on the
+ * public plugin API. The reconstruction is intentionally best-effort until
+ * OpenClaw exposes a first-class provider-call lifecycle hook with a stable
+ * call id, request, response, usage, and timing in one contract.
+ */
+import type { NemoRelayHookBackendConfig } from '../config.js';
+import type { PluginHookAgentContext, PluginHookAgentEndEvent, PluginHookBeforeMessageWriteContext, PluginHookBeforeMessageWriteEvent, PluginHookLlmInputEvent, PluginHookLlmOutputEvent, PluginHookModelCallEndedEvent, PluginHookModelCallStartedEvent } from '../openclaw-hook-types.js';
+import type { JsonObject as JsonRecord, JsonValue } from 'nemo-relay-node/typed';
+import { type LlmInputRecord, type ModelCallRecord, type SessionManager, type SessionState } from './session.js';
+/**
+ * Store one OpenClaw llm_input snapshot and replay it immediately if the matching
+ * llm_output arrived first.
+ */
+export declare function recordLlmInput(manager: SessionManager, event: PluginHookLlmInputEvent, ctx: PluginHookAgentContext): void;
+/**
+ * Replay one llm_output event or hold it briefly for a late llm_input snapshot.
+ *
+ * The grace window keeps traces accurate for out-of-order hooks without blocking
+ * the OpenClaw process or keeping Node alive.
+ */
+export declare function recordLlmOutput(manager: SessionManager, event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext): void;
+/**
+ * Capture assistant message writes as a higher-fidelity fallback for LLM outputs.
+ *
+ * Some OpenClaw paths expose the clearest assistant text, tool calls, and usage
+ * during message persistence rather than through llm_output.
+ */
+export declare function recordBeforeMessageWrite(manager: SessionManager, event: PluginHookBeforeMessageWriteEvent, ctx: PluginHookBeforeMessageWriteContext): void;
+/** Record the start of a provider call when OpenClaw supplies a model call id. */
+export declare function recordModelCallStarted(manager: SessionManager, event: PluginHookModelCallStartedEvent, ctx: PluginHookAgentContext): void;
+/** Record provider-call timing and byte counters for later LLM span correlation. */
+export declare function recordModelCallEnded(manager: SessionManager, event: PluginHookModelCallEndedEvent, ctx: PluginHookAgentContext): void;
+/** Flush pending llm_output records for a session before the root span closes. */
+export declare function replayPendingLlmOutputsForSession(manager: SessionManager, session: SessionState, options: {
+    allowPlaceholderRequest: boolean;
+}): void;
+/**
+ * Reconstruct final-run LLM spans from agent_end/message-write data when direct
+ * llm_output replay did not already produce the trajectory.
+ */
+export declare function replayAgentEndMessages(manager: SessionManager, event: PluginHookAgentEndEvent, ctx: PluginHookAgentContext, session: SessionState): JsonRecord | undefined;
+/** Emit diagnostic marks for provider-call timing records that could not pair to an LLM span. */
+export declare function emitUnpairedModelCallTimingMarks(manager: SessionManager, session: SessionState): void;
+/** Build the request payload passed to NeMo Relay for a replayed LLM span. */
+export declare function buildReplayLlmRequest(input: LlmInputRecord, output: PluginHookLlmOutputEvent, config: NemoRelayHookBackendConfig, source?: string): JsonValue;
+/** Build the response payload passed to NeMo Relay for a replayed LLM span. */
+export declare function buildReplayLlmResponse(event: PluginHookLlmOutputEvent, timing: ModelCallRecord | undefined, config: NemoRelayHookBackendConfig): JsonValue;