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

package/dist/src/config.d.ts

@@ -0,0 +1,329 @@
+export type BackendKind = 'hooks';
+export type CaptureConfig = {
+    includePrompts: boolean;
+    includeResponses: boolean;
+    stripToolArgs: boolean;
+    stripToolResults: boolean;
+};
+export type CorrelationConfig = {
+    llmOutputGraceMs: number;
+    recordTtlMs: number;
+    maxRecordsPerKey: number;
+};
+export type NemoRelayPluginHostConfig = {
+    version: number;
+    components: unknown[];
+    [key: string]: unknown;
+};
+export type NemoRelayHookBackendConfig = {
+    enabled: boolean;
+    backend: BackendKind;
+    plugins: NemoRelayPluginHostConfig;
+    capture: CaptureConfig;
+    correlation: CorrelationConfig;
+};
+export declare const NEMO_RELAY_OPENCLAW_JSON_SCHEMA: {
+    type: string;
+    additionalProperties: boolean;
+    properties: {
+        enabled: {
+            type: string;
+            default: boolean;
+            description: string;
+        };
+        backend: {
+            type: string;
+            enum: string[];
+            default: string;
+            description: string;
+        };
+        plugins: {
+            $ref: string;
+            description: string;
+        };
+        capture: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                includePrompts: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+                includeResponses: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+                stripToolArgs: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+                stripToolResults: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+            };
+            description: string;
+        };
+        correlation: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                llmOutputGraceMs: {
+                    type: string;
+                    minimum: number;
+                    default: number;
+                    description: string;
+                };
+                recordTtlMs: {
+                    type: string;
+                    minimum: number;
+                    default: number;
+                    description: string;
+                };
+                maxRecordsPerKey: {
+                    type: string;
+                    minimum: number;
+                    default: number;
+                    description: string;
+                };
+            };
+            description: string;
+        };
+    };
+    $defs: {
+        nemoRelayPluginConfig: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                version: {
+                    type: string;
+                    default: number;
+                    description: string;
+                };
+                components: {
+                    type: string;
+                    items: {
+                        $ref: string;
+                    };
+                    default: never[];
+                    description: string;
+                };
+                policy: {
+                    $ref: string;
+                    description: string;
+                };
+            };
+            default: {
+                version: number;
+                components: never[];
+            };
+        };
+        pluginComponent: {
+            type: string;
+            required: string[];
+            additionalProperties: boolean;
+            properties: {
+                kind: {
+                    type: string;
+                    description: string;
+                };
+                enabled: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+                config: {
+                    type: string;
+                    additionalProperties: boolean;
+                    description: string;
+                };
+            };
+        };
+        pluginPolicy: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                unknown_component: {
+                    $ref: string;
+                };
+                unknown_field: {
+                    $ref: string;
+                };
+                unsupported_value: {
+                    $ref: string;
+                };
+            };
+        };
+        unsupportedBehavior: {
+            type: string;
+            enum: string[];
+        };
+    };
+    description: string;
+};
+export declare const DEFAULT_CONFIG: NemoRelayHookBackendConfig;
+export declare const nemoRelayConfigSchema: {
+    safeParse(value: unknown): {
+        success: true;
+        data: NemoRelayHookBackendConfig;
+        error?: never;
+    } | {
+        success: false;
+        error: {
+            issues: {
+                path: never[];
+                message: string;
+            }[];
+        };
+        data?: never;
+    };
+    jsonSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            enabled: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+            backend: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
+            plugins: {
+                $ref: string;
+                description: string;
+            };
+            capture: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    includePrompts: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    includeResponses: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    stripToolArgs: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    stripToolResults: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                };
+                description: string;
+            };
+            correlation: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    llmOutputGraceMs: {
+                        type: string;
+                        minimum: number;
+                        default: number;
+                        description: string;
+                    };
+                    recordTtlMs: {
+                        type: string;
+                        minimum: number;
+                        default: number;
+                        description: string;
+                    };
+                    maxRecordsPerKey: {
+                        type: string;
+                        minimum: number;
+                        default: number;
+                        description: string;
+                    };
+                };
+                description: string;
+            };
+        };
+        $defs: {
+            nemoRelayPluginConfig: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    version: {
+                        type: string;
+                        default: number;
+                        description: string;
+                    };
+                    components: {
+                        type: string;
+                        items: {
+                            $ref: string;
+                        };
+                        default: never[];
+                        description: string;
+                    };
+                    policy: {
+                        $ref: string;
+                        description: string;
+                    };
+                };
+                default: {
+                    version: number;
+                    components: never[];
+                };
+            };
+            pluginComponent: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    kind: {
+                        type: string;
+                        description: string;
+                    };
+                    enabled: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    config: {
+                        type: string;
+                        additionalProperties: boolean;
+                        description: string;
+                    };
+                };
+            };
+            pluginPolicy: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    unknown_component: {
+                        $ref: string;
+                    };
+                    unknown_field: {
+                        $ref: string;
+                    };
+                    unsupported_value: {
+                        $ref: string;
+                    };
+                };
+            };
+            unsupportedBehavior: {
+                type: string;
+                enum: string[];
+            };
+        };
+        description: string;
+    };
+};
+/** Parse OpenClaw plugin JSON into the normalized hook backend config. */
+export declare function parseConfig(value: unknown): NemoRelayHookBackendConfig;

package/dist/src/config.js

@@ -0,0 +1,185 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+import manifest from '../openclaw.plugin.json' with { type: 'json' };
+const DEFAULT_PLUGIN_HOST_CONFIG = {
+    version: 1,
+    components: [],
+};
+export const NEMO_RELAY_OPENCLAW_JSON_SCHEMA = manifest.configSchema;
+export const DEFAULT_CONFIG = {
+    enabled: true,
+    backend: 'hooks',
+    plugins: DEFAULT_PLUGIN_HOST_CONFIG,
+    capture: {
+        includePrompts: true,
+        includeResponses: true,
+        stripToolArgs: true,
+        stripToolResults: true,
+    },
+    correlation: {
+        llmOutputGraceMs: 250,
+        recordTtlMs: 600_000,
+        maxRecordsPerKey: 32,
+    },
+};
+export const nemoRelayConfigSchema = {
+    safeParse(value) {
+        try {
+            return { success: true, data: parseConfig(value) };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: {
+                    issues: [
+                        {
+                            path: [],
+                            message: error instanceof Error ? error.message : String(error),
+                        },
+                    ],
+                },
+            };
+        }
+    },
+    jsonSchema: NEMO_RELAY_OPENCLAW_JSON_SCHEMA,
+};
+/** Parse OpenClaw plugin JSON into the normalized hook backend config. */
+export function parseConfig(value) {
+    const raw = asRecord(value, 'config', true);
+    rejectRemovedFields(raw);
+    rejectUnknownFields(raw, 'config', ['enabled', 'backend', 'plugins', 'capture', 'correlation']);
+    const backend = optionalString(raw.backend, 'backend') ?? DEFAULT_CONFIG.backend;
+    if (backend !== 'hooks') {
+        throw new Error(`unsupported nemo-relay backend: ${backend}`);
+    }
+    const capture = asRecord(raw.capture, 'capture', true);
+    const correlation = asRecord(raw.correlation, 'correlation', true);
+    return {
+        enabled: optionalBoolean(raw.enabled, 'enabled') ?? DEFAULT_CONFIG.enabled,
+        backend,
+        plugins: parsePluginHostConfig(raw.plugins),
+        capture: {
+            includePrompts: optionalBoolean(capture.includePrompts, 'capture.includePrompts') ?? DEFAULT_CONFIG.capture.includePrompts,
+            includeResponses: optionalBoolean(capture.includeResponses, 'capture.includeResponses') ??
+                DEFAULT_CONFIG.capture.includeResponses,
+            stripToolArgs: optionalBoolean(capture.stripToolArgs, 'capture.stripToolArgs') ?? DEFAULT_CONFIG.capture.stripToolArgs,
+            stripToolResults: optionalBoolean(capture.stripToolResults, 'capture.stripToolResults') ??
+                DEFAULT_CONFIG.capture.stripToolResults,
+        },
+        correlation: {
+            llmOutputGraceMs: optionalNonNegativeInteger(correlation.llmOutputGraceMs, 'correlation.llmOutputGraceMs') ??
+                DEFAULT_CONFIG.correlation.llmOutputGraceMs,
+            recordTtlMs: optionalNonNegativeInteger(correlation.recordTtlMs, 'correlation.recordTtlMs') ??
+                DEFAULT_CONFIG.correlation.recordTtlMs,
+            maxRecordsPerKey: optionalPositiveInteger(correlation.maxRecordsPerKey, 'correlation.maxRecordsPerKey') ??
+                DEFAULT_CONFIG.correlation.maxRecordsPerKey,
+        },
+    };
+}
+/** Normalize the optional generic NeMo Relay plugin-host config embedded in OpenClaw config. */
+function parsePluginHostConfig(value) {
+    if (value === undefined) {
+        return clonePluginHostConfig(DEFAULT_PLUGIN_HOST_CONFIG);
+    }
+    const record = asRecord(value, 'plugins', false);
+    const version = optionalNumber(record.version, 'plugins.version') ?? 1;
+    const components = record.components === undefined ? [] : record.components;
+    if (!Array.isArray(components)) {
+        throw new Error('plugins.components must be an array');
+    }
+    return {
+        ...record,
+        version,
+        components: [...components],
+    };
+}
+/** Clone the mutable plugin-host component list before putting it in runtime state. */
+function clonePluginHostConfig(config) {
+    return {
+        ...config,
+        components: [...config.components],
+    };
+}
+/** Require an object config section, optionally treating undefined as an empty object. */
+function asRecord(value, path, optional) {
+    if (value === undefined && optional) {
+        return {};
+    }
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    throw new Error(`${path} must be an object`);
+}
+/** Reject config fields removed by the generic plugin-host pivot with direct migration hints. */
+function rejectRemovedFields(raw) {
+    if (raw.nemoRelay !== undefined) {
+        throw new Error('nemoRelay.pluginConfig was removed; use top-level plugins instead');
+    }
+    if (raw.atif !== undefined) {
+        throw new Error('atif was removed; configure plugins.components[].config.atif on the observability component');
+    }
+    if (raw.telemetry !== undefined) {
+        throw new Error('telemetry was removed; configure plugins.components[].config.opentelemetry or openinference on the observability component');
+    }
+}
+/** Keep parser behavior aligned with the manifest's additionalProperties=false contract. */
+function rejectUnknownFields(raw, path, allowed) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(raw)) {
+        if (!allowedSet.has(key)) {
+            throw new Error(`${path}.${key} is not supported`);
+        }
+    }
+}
+/** Parse an optional boolean while producing config-path-specific error messages. */
+function optionalBoolean(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'boolean') {
+        throw new Error(`${path} must be a boolean`);
+    }
+    return value;
+}
+/** Parse an optional finite number while preserving undefined for default fallback. */
+function optionalNumber(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`${path} must be a finite number`);
+    }
+    return value;
+}
+/** Parse an optional integer where zero is valid, such as timeouts. */
+function optionalNonNegativeInteger(value, path) {
+    const parsed = optionalNumber(value, path);
+    if (parsed === undefined) {
+        return undefined;
+    }
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`${path} must be a non-negative integer`);
+    }
+    return parsed;
+}
+/** Parse an optional integer where zero would disable required bounded storage. */
+function optionalPositiveInteger(value, path) {
+    const parsed = optionalNumber(value, path);
+    if (parsed === undefined) {
+        return undefined;
+    }
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`${path} must be a positive integer`);
+    }
+    return parsed;
+}
+/** Parse an optional string while rejecting accidental non-string config values. */
+function optionalString(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`${path} must be a string`);
+    }
+    return value;
+}

package/dist/src/health.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Health snapshot construction for the plugin gateway status method.
+ *
+ * Runtime state owns status transitions; this file turns that state into a
+ * stable, JSON-friendly status payload for operators and tests.
+ */
+import type { NemoRelayHookBackendConfig } from './config.js';
+import type { HookReplayBackendState } from './hook-replay/session.js';
+export type HookReplayBackendStatus = {
+    state: 'not_initialized';
+    reason?: string;
+} | {
+    state: 'disabled';
+    reason?: string;
+} | {
+    state: 'ready';
+} | {
+    state: 'degraded';
+    reason: string;
+} | {
+    state: 'stopping';
+} | {
+    state: 'stopped';
+    reason?: string;
+};
+export type OutputHealthState = 'enabled' | 'disabled' | 'degraded';
+export type NemoRelayHealthSnapshot = {
+    id: 'nemo-relay';
+    backend: 'hooks';
+    status: HookReplayBackendStatus;
+    initializedPluginHost: boolean;
+    state: HookReplayBackendStatus['state'];
+    outputs: {
+        atif: OutputHealthState;
+        otel: OutputHealthState;
+        openInference: OutputHealthState;
+    };
+    counters: HookReplayBackendState['counters'];
+    lastError?: string;
+};
+/** Build a complete health payload from runtime status, configured outputs, and counters. */
+export declare function createHealthSnapshot(params: {
+    status: HookReplayBackendStatus;
+    initializedPluginHost: boolean;
+    pluginHostOutputsHealthy: boolean;
+    config: NemoRelayHookBackendConfig;
+    counters?: HookReplayBackendState['counters'];
+}): NemoRelayHealthSnapshot;

package/dist/src/health.js

@@ -0,0 +1,63 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/** Build a complete health payload from runtime status, configured outputs, and counters. */
+export function createHealthSnapshot(params) {
+    const lastError = 'reason' in params.status ? params.status.reason : undefined;
+    const outputs = configuredObservabilityOutputs(params.config);
+    const pluginHostFailed = params.status.state === 'degraded' && !params.pluginHostOutputsHealthy;
+    return {
+        id: 'nemo-relay',
+        backend: 'hooks',
+        status: params.status,
+        initializedPluginHost: params.initializedPluginHost,
+        state: params.status.state,
+        outputs: {
+            atif: outputHealth(outputs.atif, pluginHostFailed),
+            otel: outputHealth(outputs.otel, pluginHostFailed),
+            openInference: outputHealth(outputs.openInference, pluginHostFailed),
+        },
+        counters: params.counters ?? emptyCounters(),
+        ...(lastError === undefined ? {} : { lastError }),
+    };
+}
+function outputHealth(enabled, pluginHostFailed) {
+    if (!enabled) {
+        return 'disabled';
+    }
+    return pluginHostFailed ? 'degraded' : 'enabled';
+}
+/** Inspect generic PluginConfig components for configured observability outputs. */
+function configuredObservabilityOutputs(config) {
+    const outputs = { atif: false, otel: false, openInference: false };
+    for (const component of config.plugins.components) {
+        const record = asRecord(component);
+        if (record?.kind !== 'observability' || record.enabled === false) {
+            continue;
+        }
+        const componentConfig = asRecord(record.config);
+        outputs.atif ||= sectionEnabled(componentConfig?.atif);
+        outputs.otel ||= sectionEnabled(componentConfig?.opentelemetry);
+        outputs.openInference ||= sectionEnabled(componentConfig?.openinference);
+    }
+    return outputs;
+}
+function sectionEnabled(value) {
+    const section = asRecord(value);
+    return section?.enabled === true;
+}
+function asRecord(value) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+/** Provide zero counters before hook replay has initialized. */
+function emptyCounters() {
+    return {
+        llmSpansReplayed: 0,
+        toolSpansReplayed: 0,
+        marksEmitted: 0,
+        replayErrors: 0,
+        skippedEvents: 0,
+    };
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Correlation-key and timestamp utilities for hook replay.
+ *
+ * OpenClaw emits request, response, timing, and tool events separately. These
+ * helpers keep key construction consistent across the replay modules.
+ */
+export type LlmKeyInput = {
+    sessionId?: string | undefined;
+    runId?: string | undefined;
+    provider?: string | undefined;
+    model?: string | undefined;
+};
+export type ModelTimingKeyInput = {
+    runId: string;
+    callId: string;
+};
+export type TimestampedRecord = {
+    observedAtMs?: number | undefined;
+    startedAtMs?: number | undefined;
+    endedAtMs?: number | undefined;
+};
+/** Serialize correlation tuple parts while preserving empty or missing fields as null. */
+export declare function tupleKey(parts: unknown[]): string;
+/** Build the best available key for pairing public llm_input and llm_output hooks. */
+export declare function llmKey(input: LlmKeyInput): string;
+/** Build the stronger key for model timing events that include a provider call id. */
+export declare function modelTimingKey(input: ModelTimingKeyInput): string;
+export declare const modelTimingLlmKey: typeof llmKey;
+/** Remove correlation records that are too old to safely pair with later events. */
+export declare function evictExpiredRecords<T extends TimestampedRecord>(map: Map<string, T[]>, nowMs: number, ttlMs: number): void;
+/** Return wall-clock microseconds for NeMo Relay span APIs. */
+export declare function nowMicros(): number;
+/** Infer a start timestamp when OpenClaw gives end time plus duration. */
+export declare function startMicrosFromDuration(endMicros: number, durationMs: number | undefined): number | null;

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

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/** Serialize correlation tuple parts while preserving empty or missing fields as null. */
+export function tupleKey(parts) {
+    return JSON.stringify(parts.map((part) => (typeof part === 'string' && part.length > 0 ? part : null)));
+}
+/** Build the best available key for pairing public llm_input and llm_output hooks. */
+export function llmKey(input) {
+    return tupleKey([input.sessionId, input.runId, input.provider, input.model]);
+}
+/** Build the stronger key for model timing events that include a provider call id. */
+export function modelTimingKey(input) {
+    return tupleKey([input.runId, input.callId]);
+}
+// Model timing fallback uses the same provider/model tuple as LLM replay.
+export const modelTimingLlmKey = llmKey;
+/** Remove correlation records that are too old to safely pair with later events. */
+export function evictExpiredRecords(map, nowMs, ttlMs) {
+    for (const [key, records] of map) {
+        const retained = records.filter((record) => nowMs - recordTimestamp(record) <= ttlMs);
+        if (retained.length === 0) {
+            map.delete(key);
+        }
+        else {
+            map.set(key, retained);
+        }
+    }
+}
+/** Return wall-clock microseconds for NeMo Relay span APIs. */
+export function nowMicros() {
+    return Date.now() * 1000;
+}
+/** Infer a start timestamp when OpenClaw gives end time plus duration. */
+export function startMicrosFromDuration(endMicros, durationMs) {
+    return durationMs === undefined ? null : endMicros - Math.round(durationMs * 1000);
+}
+/** Select the most recent timestamp field available on a correlation record. */
+function recordTimestamp(record) {
+    return record.observedAtMs ?? record.endedAtMs ?? record.startedAtMs ?? 0;
+}