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

package/dist/src/runtime-state.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Runtime lifecycle coordinator for the OpenClaw plugin.
+ *
+ * This module validates config, lazy-loads NeMo Relay Node bindings, registers
+ * OpenClaw service/lifecycle/gateway surfaces, and forwards hooks to the replay
+ * backend once runtime state is ready.
+ */
+import type { OpenClawPluginApi, PluginLogger, PluginRuntimeLifecycleRegistration } from 'openclaw/plugin-sdk/plugin-entry';
+import { type HookReplayBackendStatus } from './health.js';
+import type { PluginAgentToolCallMiddlewareContext } from './openclaw-hook-types.js';
+import { type NemoRelayModuleLoader } from './modules.js';
+import type { RuntimeStateOptions, StartContext } from './types.js';
+type RuntimeCleanupContext = Parameters<NonNullable<PluginRuntimeLifecycleRegistration['cleanup']>>[0];
+/** Owns one plugin runtime instance across OpenClaw service start/stop cycles. */
+export declare class NemoRelayRuntimeState {
+    private readonly api;
+    private readonly config;
+    private readonly moduleLoader;
+    private loadPromise;
+    private startPromise;
+    private statusValue;
+    private modulesValue?;
+    private backendValue;
+    private initializedPluginHost;
+    private pluginHostOutputsHealthy;
+    private started;
+    private beforeExitListener?;
+    private unavailableLogged;
+    private missingStartContextLogged;
+    private lastStartContext?;
+    private lastCounters?;
+    constructor(options: RuntimeStateOptions);
+    /** Return the current coarse backend status. */
+    status(): HookReplayBackendStatus;
+    /** Build the operator-facing health payload served through the gateway method. */
+    health(): import("./health.js").NemoRelayHealthSnapshot;
+    /** Start NeMo Relay modules, generic plugins, and the hook replay backend. */
+    start(ctx: StartContext): Promise<void>;
+    /** Do the startup work behind a single-flight guard. */
+    private startInternal;
+    /** Stop the runtime because OpenClaw service or gateway shutdown is happening. */
+    stop(reason: string, logger?: PluginLogger): Promise<void>;
+    /** Apply conditional-execution guardrails before an OpenClaw tool call proceeds. */
+    guardToolCall(ctx: PluginAgentToolCallMiddlewareContext): Promise<void>;
+    /** Shared stop implementation that controls the final health status. */
+    private stopWithStatus;
+    /** Handle OpenClaw runtime lifecycle cleanup for either a session or the backend. */
+    cleanup(ctx: RuntimeCleanupContext): Promise<void>;
+    /** Return a backend for a hook, lazily starting from runtime context if needed. */
+    private backendForHook;
+    /** Run a synchronous hook against the backend with fail-open replay handling. */
+    private replayWithBackend;
+    /** Run an asynchronous hook against the backend with fail-open replay handling. */
+    private replayWithBackendAsync;
+    /** Register every OpenClaw hook used by the observability backend. */
+    registerHooks(): void;
+    /** Reconstruct enough service-start context for hooks that arrive before service start. */
+    private startContextFromRuntime;
+    /** Register a process beforeExit cleanup guard for local OpenClaw shutdown paths. */
+    private registerBeforeExit;
+    /** Remove the beforeExit listener once normal shutdown begins. */
+    private removeBeforeExitListener;
+}
+/** Register the NeMo Relay observability plugin with the OpenClaw plugin API. */
+export declare function registerNemoRelayPlugin(api: OpenClawPluginApi, moduleLoader?: NemoRelayModuleLoader): void;
+export {};

package/dist/src/runtime-state.js

@@ -0,0 +1,420 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { parseConfig } from './config.js';
+import { createHealthSnapshot } from './health.js';
+import { HookReplayBackend } from './hooks-backend.js';
+import { defaultNemoRelayModuleLoader, } from './modules.js';
+const SERVICE_ID = 'nemo-relay-observability';
+const LIFECYCLE_ID = 'nemo-relay-observability-cleanup';
+const STATUS_METHOD = 'nemoRelay.status';
+/** Owns one plugin runtime instance across OpenClaw service start/stop cycles. */
+export class NemoRelayRuntimeState {
+    api;
+    config;
+    moduleLoader;
+    loadPromise;
+    startPromise;
+    statusValue = { state: 'not_initialized' };
+    modulesValue;
+    backendValue;
+    initializedPluginHost = false;
+    pluginHostOutputsHealthy = false;
+    started = false;
+    beforeExitListener;
+    unavailableLogged = false;
+    missingStartContextLogged = false;
+    lastStartContext;
+    lastCounters;
+    constructor(options) {
+        this.api = options.api;
+        this.config = options.config;
+        this.moduleLoader = options.moduleLoader ?? defaultNemoRelayModuleLoader;
+    }
+    /** Return the current coarse backend status. */
+    status() {
+        return this.statusValue;
+    }
+    /** Build the operator-facing health payload served through the gateway method. */
+    health() {
+        const backendState = this.backendValue?.state();
+        return createHealthSnapshot({
+            status: this.statusValue,
+            initializedPluginHost: this.initializedPluginHost,
+            pluginHostOutputsHealthy: this.pluginHostOutputsHealthy,
+            config: this.config,
+            ...(backendState === undefined
+                ? this.lastCounters === undefined
+                    ? {}
+                    : { counters: this.lastCounters }
+                : {
+                    counters: backendState.counters,
+                }),
+        });
+    }
+    /** Start NeMo Relay modules, generic plugins, and the hook replay backend. */
+    async start(ctx) {
+        this.lastStartContext = copyStartContext(ctx);
+        this.missingStartContextLogged = false;
+        if (this.started || this.statusValue.state === 'ready' || this.statusValue.state === 'degraded') {
+            return;
+        }
+        if (this.startPromise) {
+            await this.startPromise;
+            return;
+        }
+        this.startPromise = this.startInternal(ctx);
+        try {
+            await this.startPromise;
+        }
+        finally {
+            this.startPromise = undefined;
+        }
+    }
+    /** Do the startup work behind a single-flight guard. */
+    async startInternal(ctx) {
+        delete this.lastCounters;
+        this.initializedPluginHost = false;
+        this.pluginHostOutputsHealthy = false;
+        let modules;
+        try {
+            this.loadPromise ??= this.moduleLoader();
+            modules = await this.loadPromise;
+            this.modulesValue = modules;
+        }
+        catch (error) {
+            this.loadPromise = undefined;
+            this.statusValue = { state: 'degraded', reason: `failed to load nemo-relay-node: ${toMessage(error)}` };
+            if (!this.unavailableLogged) {
+                ctx.logger.warn?.(this.statusValue.reason);
+                this.unavailableLogged = true;
+            }
+            return;
+        }
+        const hostConfig = this.config.plugins;
+        let degradedReason;
+        const validationReport = validatePluginHostConfig(modules, hostConfig, ctx.logger);
+        if (!validationReport.ok) {
+            degradedReason = validationReport.reason;
+            ctx.logger.warn?.(degradedReason);
+        }
+        else if (validationReport.report.diagnostics.some((diagnostic) => diagnostic.level === 'error')) {
+            degradedReason = 'NeMo Relay plugin host config validation failed';
+        }
+        else {
+            if (validationReport.report.diagnostics.some((diagnostic) => diagnostic.level === 'warning') &&
+                degradedReason === undefined) {
+                degradedReason = 'NeMo Relay plugin host config validation produced warnings';
+            }
+            try {
+                const activationReport = await modules.pluginHost.initialize(hostConfig);
+                logDiagnostics(ctx.logger, activationReport.diagnostics);
+                this.initializedPluginHost = true;
+                const hasInitializationErrors = activationReport.diagnostics.some((diagnostic) => diagnostic.level === 'error');
+                this.pluginHostOutputsHealthy = !hasInitializationErrors;
+                if (hasInitializationErrors) {
+                    degradedReason ??= 'NeMo Relay plugin host initialization reported errors';
+                }
+            }
+            catch (error) {
+                degradedReason = `failed to initialize NeMo Relay plugin host: ${toMessage(error)}`;
+                ctx.logger.warn?.(degradedReason);
+            }
+        }
+        this.backendValue = new HookReplayBackend({
+            nf: modules.nf,
+            config: this.config,
+            logger: ctx.logger,
+            agentVersion: ctx.agentVersion,
+        });
+        this.registerBeforeExit(ctx.logger);
+        this.started = true;
+        this.statusValue =
+            degradedReason === undefined ? { state: 'ready' } : { state: 'degraded', reason: degradedReason };
+    }
+    /** Stop the runtime because OpenClaw service or gateway shutdown is happening. */
+    async stop(reason, logger) {
+        await this.stopWithStatus(reason, logger, { state: 'stopped', reason });
+    }
+    /** Apply conditional-execution guardrails before an OpenClaw tool call proceeds. */
+    async guardToolCall(ctx) {
+        const backend = await this.backendForHook(ctx.workspaceDir);
+        if (!backend) {
+            return;
+        }
+        await backend.onBeforeToolCall({
+            toolName: ctx.toolName,
+            params: ctx.params,
+            runId: ctx.runId,
+            toolCallId: ctx.toolCallId,
+        }, ctx);
+    }
+    /** Shared stop implementation that controls the final health status. */
+    async stopWithStatus(reason, logger, finalStatus) {
+        if (this.statusValue.state === 'stopped' ||
+            this.statusValue.state === 'disabled' ||
+            this.statusValue.state === 'stopping') {
+            return;
+        }
+        if (this.startPromise) {
+            await this.startPromise.catch((error) => {
+                const log = logger ?? this.api.logger;
+                log.warn?.(`failed to finish NeMo Relay startup before stop: ${toMessage(error)}`);
+            });
+        }
+        this.statusValue = { state: 'stopping' };
+        const log = logger ?? this.api.logger;
+        this.removeBeforeExitListener();
+        try {
+            await this.backendValue?.drainForGatewayStop(reason);
+        }
+        catch (error) {
+            log.warn?.(`failed to stop NeMo Relay hook backend: ${toMessage(error)}`);
+        }
+        const backendState = this.backendValue?.state();
+        if (backendState) {
+            this.lastCounters = { ...backendState.counters };
+        }
+        this.backendValue = undefined;
+        if (this.initializedPluginHost && this.modulesValue) {
+            try {
+                this.modulesValue.pluginHost.clear();
+            }
+            catch (error) {
+                log.warn?.(`failed to clear NeMo Relay plugin host: ${toMessage(error)}`);
+            }
+            this.initializedPluginHost = false;
+            this.pluginHostOutputsHealthy = false;
+        }
+        this.started = false;
+        this.statusValue = finalStatus;
+    }
+    /** Handle OpenClaw runtime lifecycle cleanup for either a session or the backend. */
+    async cleanup(ctx) {
+        if (ctx.sessionKey !== undefined || ctx.runId !== undefined) {
+            await this.backendValue?.cleanupSession({
+                reason: ctx.reason,
+                ...(ctx.sessionKey === undefined ? {} : { sessionKey: ctx.sessionKey }),
+                ...(ctx.runId === undefined ? {} : { runId: ctx.runId }),
+            });
+            return;
+        }
+        await this.stopWithStatus(ctx.reason, this.api.logger, ctx.reason === 'restart'
+            ? { state: 'not_initialized', reason: 'restart' }
+            : { state: 'stopped', reason: ctx.reason });
+    }
+    /** Return a backend for a hook, lazily starting from runtime context if needed. */
+    async backendForHook(workspaceDir) {
+        if (this.backendValue) {
+            return this.backendValue;
+        }
+        if (this.statusValue.state === 'disabled' || this.statusValue.state === 'stopping') {
+            return undefined;
+        }
+        const startContext = this.lastStartContext ?? this.startContextFromRuntime(workspaceDir);
+        if (!startContext) {
+            if (!this.missingStartContextLogged) {
+                this.api.logger.warn?.('nemo-relay skipped hook replay because OpenClaw service start context is unavailable');
+                this.missingStartContextLogged = true;
+            }
+            return undefined;
+        }
+        await this.start(startContext);
+        return this.backendValue;
+    }
+    /** Run a synchronous hook against the backend with fail-open replay handling. */
+    async replayWithBackend(label, workspaceDir, emit) {
+        const backend = await this.backendForHook(workspaceDir);
+        if (!backend) {
+            return;
+        }
+        backend.safeReplay(label, undefined, () => emit(backend));
+    }
+    /** Run an asynchronous hook against the backend with fail-open replay handling. */
+    async replayWithBackendAsync(label, workspaceDir, emit) {
+        const backend = await this.backendForHook(workspaceDir);
+        if (!backend) {
+            return;
+        }
+        await backend.safeReplayAsync(label, undefined, () => emit(backend));
+    }
+    /** Register every OpenClaw hook used by the observability backend. */
+    registerHooks() {
+        this.api.on('gateway_start', async (event, ctx) => {
+            await this.replayWithBackend('gateway_start', ctx.workspaceDir, (backend) => backend.onGatewayStart(event, ctx));
+        });
+        this.api.on('gateway_stop', async (event) => {
+            await this.stop(event.reason ?? 'gateway_stop', this.api.logger);
+        });
+        this.api.on('session_start', async (event, ctx) => {
+            await this.replayWithBackend('session_start', undefined, (backend) => backend.onSessionStart(event, ctx));
+        });
+        this.api.on('session_end', async (event, ctx) => {
+            await this.replayWithBackendAsync('session_end', undefined, (backend) => backend.onSessionEnd(event, ctx));
+        });
+        this.api.on('llm_input', async (event, ctx) => {
+            await this.replayWithBackend('llm_input', ctx.workspaceDir, (backend) => backend.onLlmInput(event, ctx));
+        });
+        this.api.on('llm_output', async (event, ctx) => {
+            await this.replayWithBackend('llm_output', ctx.workspaceDir, (backend) => backend.onLlmOutput(event, ctx));
+        });
+        this.api.on('model_call_started', async (event, ctx) => {
+            await this.replayWithBackend('model_call_started', ctx.workspaceDir, (backend) => backend.onModelCallStarted(event, ctx));
+        });
+        this.api.on('model_call_ended', async (event, ctx) => {
+            await this.replayWithBackend('model_call_ended', ctx.workspaceDir, (backend) => backend.onModelCallEnded(event, ctx));
+        });
+        this.api.on('after_tool_call', async (event, ctx) => {
+            await this.replayWithBackend('after_tool_call', undefined, (backend) => backend.onAfterToolCall(event, ctx));
+        });
+        this.api.on('before_message_write', (event, ctx) => {
+            const backend = this.backendValue;
+            if (!backend) {
+                return;
+            }
+            backend.safeReplay('before_message_write', undefined, () => backend.onBeforeMessageWrite(event, ctx));
+        });
+        this.api.on('agent_end', async (event, ctx) => {
+            await this.replayWithBackend('agent_end', ctx.workspaceDir, (backend) => backend.onAgentEnd(event, ctx));
+        });
+        this.api.on('before_agent_finalize', async (event, ctx) => {
+            await this.replayWithBackend('before_agent_finalize', ctx.workspaceDir, (backend) => backend.onBeforeAgentFinalize(event, ctx));
+        });
+        this.api.on('subagent_spawned', async (event, ctx) => {
+            await this.replayWithBackend('subagent_spawned', undefined, (backend) => backend.onSubagentSpawned(event, ctx));
+        });
+        this.api.on('subagent_ended', async (event, ctx) => {
+            await this.replayWithBackend('subagent_ended', undefined, (backend) => backend.onSubagentEnded(event, ctx));
+        });
+    }
+    /** Reconstruct enough service-start context for hooks that arrive before service start. */
+    startContextFromRuntime(workspaceDir) {
+        try {
+            const stateDir = this.api.runtime.state.resolveStateDir();
+            return {
+                stateDir,
+                logger: this.api.logger,
+                resolvePath: this.api.resolvePath,
+                agentVersion: this.api.version ?? 'unknown',
+                ...(workspaceDir === undefined ? {} : { workspaceDir }),
+            };
+        }
+        catch (error) {
+            this.api.logger.warn?.(`nemo-relay could not resolve OpenClaw runtime state dir: ${toMessage(error)}`);
+            return undefined;
+        }
+    }
+    /** Register a process beforeExit cleanup guard for local OpenClaw shutdown paths. */
+    registerBeforeExit(logger) {
+        if (this.beforeExitListener) {
+            return;
+        }
+        const listener = () => {
+            void this.stop('beforeExit', logger).catch((error) => {
+                logger.warn?.(`nemo-relay beforeExit cleanup failed: ${toMessage(error)}`);
+            });
+        };
+        process.on('beforeExit', listener);
+        this.beforeExitListener = listener;
+    }
+    /** Remove the beforeExit listener once normal shutdown begins. */
+    removeBeforeExitListener() {
+        if (!this.beforeExitListener) {
+            return;
+        }
+        process.removeListener('beforeExit', this.beforeExitListener);
+        delete this.beforeExitListener;
+    }
+}
+/** Register the NeMo Relay observability plugin with the OpenClaw plugin API. */
+export function registerNemoRelayPlugin(api, moduleLoader) {
+    if (api.registrationMode !== 'full') {
+        return;
+    }
+    let config;
+    try {
+        config = parseConfig(api.pluginConfig);
+    }
+    catch (error) {
+        api.logger.warn?.(`nemo-relay observability disabled because plugin config is invalid: ${toMessage(error)}`);
+        return;
+    }
+    if (!config.enabled) {
+        api.logger.info?.('nemo-relay observability disabled by plugin config');
+        return;
+    }
+    const runtime = new NemoRelayRuntimeState(moduleLoader === undefined ? { api, config } : { api, config, moduleLoader });
+    api.registerService({
+        id: SERVICE_ID,
+        start: (ctx) => runtime.start({
+            stateDir: ctx.stateDir,
+            logger: ctx.logger,
+            resolvePath: api.resolvePath,
+            agentVersion: api.version ?? 'unknown',
+            ...(ctx.workspaceDir === undefined ? {} : { workspaceDir: ctx.workspaceDir }),
+        }),
+        stop: (ctx) => runtime.stop('service_stop', ctx.logger),
+    });
+    api.registerRuntimeLifecycle({
+        id: LIFECYCLE_ID,
+        description: 'Clean up NeMo Relay OpenClaw observability plugin state',
+        cleanup: (ctx) => runtime.cleanup(ctx),
+    });
+    api.registerGatewayMethod?.(STATUS_METHOD, ({ respond }) => {
+        respond(true, runtime.health());
+    }, {
+        scope: 'operator.admin',
+    });
+    runtime.registerHooks();
+    registerToolCallMiddleware(api, runtime);
+}
+function registerToolCallMiddleware(api, runtime) {
+    const register = api.registerAgentToolCallMiddleware;
+    if (typeof register !== 'function') {
+        return;
+    }
+    register.call(api, async (ctx) => {
+        await runtime.guardToolCall(ctx);
+        return await ctx.execute(ctx.params);
+    }, { runtimes: ['pi'], priority: 100 });
+}
+/** Validate the NeMo Relay plugin-host config and log diagnostics. */
+function validatePluginHostConfig(modules, config, logger) {
+    try {
+        const report = modules.pluginHost.validate(config);
+        logDiagnostics(logger, report.diagnostics);
+        return { ok: true, report };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `failed to validate NeMo Relay plugin host config: ${toMessage(error)}`,
+        };
+    }
+}
+/** Log plugin-host diagnostics at warning or info level based on severity. */
+function logDiagnostics(logger, diagnostics) {
+    for (const diagnostic of diagnostics) {
+        const prefix = diagnostic.component ? `${diagnostic.component}: ` : '';
+        const message = `${prefix}${diagnostic.code}: ${diagnostic.message}`;
+        if (diagnostic.level === 'error') {
+            logger.warn?.(message);
+        }
+        else {
+            logger.info?.(message);
+        }
+    }
+}
+/** Copy service-start context so later lazy hook startup cannot mutate it. */
+function copyStartContext(ctx) {
+    return {
+        stateDir: ctx.stateDir,
+        logger: ctx.logger,
+        resolvePath: ctx.resolvePath,
+        agentVersion: ctx.agentVersion,
+        ...(ctx.workspaceDir === undefined ? {} : { workspaceDir: ctx.workspaceDir }),
+    };
+}
+/** Convert thrown values into stable log strings. */
+function toMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared runtime option and context types.
+ *
+ * These types avoid importing OpenClaw implementation modules outside the public
+ * plugin SDK surface and keep runtime-state constructor signatures explicit.
+ */
+import type { OpenClawPluginApi, OpenClawPluginServiceContext } from 'openclaw/plugin-sdk/plugin-entry';
+import type { NemoRelayHookBackendConfig } from './config.js';
+import type { HookReplayBackendStatus } from './health.js';
+import type { NemoRelayModuleLoader } from './modules.js';
+export type RuntimeStateOptions = {
+    api: OpenClawPluginApi;
+    config: NemoRelayHookBackendConfig;
+    moduleLoader?: NemoRelayModuleLoader;
+};
+export type StartContext = {
+    stateDir: string;
+    workspaceDir?: string;
+    logger: OpenClawPluginServiceContext['logger'];
+    resolvePath: OpenClawPluginApi['resolvePath'];
+    agentVersion: string;
+};
+export type RuntimeStateSnapshot = {
+    status: HookReplayBackendStatus;
+    initializedPluginHost: boolean;
+    unavailableReason?: string;
+};

package/dist/src/types.js

@@ -0,0 +1,3 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/index.ts

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * OpenClaw plugin entry point.
+ *
+ * This file should stay small: it declares the public plugin metadata and hands
+ * registration to the runtime-state module, where lifecycle and hook wiring live.
+ */
+import { definePluginEntry, type OpenClawPluginApi } from 'openclaw/plugin-sdk/plugin-entry';
+
+import { nemoRelayConfigSchema } from './src/config.js';
+import { registerNemoRelayPlugin } from './src/runtime-state.js';
+
+export default definePluginEntry({
+  id: 'nemo-relay',
+  name: 'NeMo Relay Observability',
+  description: 'ATIF, OpenInference, and OpenTelemetry telemetry through NeMo Relay',
+  configSchema: nemoRelayConfigSchema,
+  register(api: OpenClawPluginApi) {
+    registerNemoRelayPlugin(api);
+  },
+});