feat: add opt-in observability for pre-tool evaluations

README.md

@@ -66,6 +66,7 @@ openclaw config set plugins.entries.agent-control-openclaw-plugin.config.apiKey
 | `agentVersion` | string | — | Version string sent to Agent Control during agent sync. |
 | `timeoutMs` | integer | SDK default | Client timeout in milliseconds. |
 | `failClosed` | boolean | `false` | Block tool calls when Agent Control is unreachable. See [Fail-open vs fail-closed](#fail-open-vs-fail-closed). |
+| `observabilityEnabled` | boolean | `true` | Emit pre-tool control execution events to Agent Control observability. Enabled by default unless explicitly set to `false`. |
 | `logLevel` | string | `warn` | Logging verbosity. See [Logging](#logging). |
 | `userAgent` | string | `openclaw-agent-control-plugin/0.1` | Custom User-Agent header for requests to Agent Control. |
 
@@ -96,6 +97,20 @@ Set `failClosed` to `true` if you need the guarantee that no tool call executes
 openclaw config set plugins.entries.agent-control-openclaw-plugin.config.failClosed true
 ```
 
+## Observability
+
+Observability is enabled by default. Unless `observabilityEnabled` is explicitly set to `false`, the plugin sends control execution events to Agent Control's observability API after each `before_tool_call` evaluation.
+
+- Events are emitted only for the `pre` stage because the current OpenClaw plugin SDK typings expose a pre-tool hook but no post-tool hook.
+- Emission is best-effort and non-blocking. Ingest failures are logged at `warn` and do not change allow/block behavior.
+- The plugin stamps OpenTelemetry trace and span IDs when an active span exists, otherwise it generates OTEL-compatible IDs locally.
+
+Disable it with:
+
+```bash
+openclaw config set plugins.entries.agent-control-openclaw-plugin.config.observabilityEnabled false
+```
+
 ## Logging
 
 The plugin stays quiet by default and only emits warnings, errors, and tool block events.
@@ -133,6 +148,7 @@ openclaw plugins disable agent-control-openclaw-plugin
 openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.apiKey
 openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.logLevel
 openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.agentVersion
+openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.observabilityEnabled
 openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.userAgent
 ```
 

openclaw.plugin.json

@@ -31,6 +31,10 @@
       "failClosed": {
         "type": "boolean"
       },
+      "observabilityEnabled": {
+        "type": "boolean",
+        "default": true
+      },
       "logLevel": {
         "type": "string",
         "enum": ["warn", "info", "debug"]
@@ -54,6 +58,10 @@
       "label": "Fail Closed",
       "help": "If true, block tool invocations when Agent Control is unavailable."
     },
+    "observabilityEnabled": {
+      "label": "Enable Observability",
+      "help": "Defaults to true. Set false to disable best-effort pre-tool control execution events to Agent Control observability."
+    },
     "logLevel": {
       "label": "Log Level",
       "help": "Controls plugin verbosity: warn logs only warnings, errors, and block events; info adds high-level lifecycle logs; debug adds verbose diagnostics."

package.json

@@ -38,14 +38,15 @@
     "release": "semantic-release"
   },
   "dependencies": {
-    "agent-control": "^2.0.0",
+    "@opentelemetry/api": "^1.9.1",
+    "agent-control": "^2.2.0",
     "esbuild": "^0.27.3",
     "jiti": "^2.6.1"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.0.18",
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^24.5.2",
+    "@vitest/coverage-v8": "^4.0.18",
     "oxlint": "^0.15.0",
     "semantic-release": "^25.0.3",
     "typescript": "^5.9.2",

src/agent-control-plugin.ts

@@ -1,6 +1,13 @@
 import { AgentControlClient } from "agent-control";
+import type { JsonValue } from "agent-control";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import { createPluginLogger, resolveLogLevel } from "./logging.ts";
+import {
+  buildControlExecutionEvents,
+  buildControlObservabilityIndex,
+  emitControlExecutionEvents,
+  resolveTraceContext,
+} from "./observability.ts";
 import { resolveStepsForContext } from "./tool-catalog.ts";
 import { buildEvaluationContext } from "./session-context.ts";
 import {
@@ -74,6 +81,7 @@ export default function register(api: OpenClawPluginApi) {
   }
 
   const failClosed = cfg.failClosed === true;
+  const observabilityEnabled = cfg.observabilityEnabled !== false;
   const baseAgentName = asString(cfg.agentName) ?? "openclaw-agent";
   const configuredAgentVersion = asString(cfg.agentVersion);
   const pluginVersion = asString(api.version);
@@ -91,6 +99,9 @@ export default function register(api: OpenClawPluginApi) {
   logger.info(
     `agent-control: client_init duration_sec=${secondsSince(clientInitStartedAt)} timeout_ms=${clientTimeoutMs ?? "default"} server_url=${serverUrl}`,
   );
+  logger.info(
+    `agent-control: observability enabled=${observabilityEnabled}`,
+  );
 
   const states = new Map<string, AgentState>();
   let gatewayWarmupPromise: Promise<void> | null = null;
@@ -110,6 +121,7 @@ export default function register(api: OpenClawPluginApi) {
       steps: [],
       stepsHash: hashSteps([]),
       lastSyncedStepsHash: null,
+      controlObservabilityById: new Map(),
       syncPromise: null,
     };
     states.set(sourceAgentId, created);
@@ -160,7 +172,7 @@ export default function register(api: OpenClawPluginApi) {
     const currentHash = state.stepsHash;
     const promise = (async () => {
       const syncStartedAt = process.hrtime.bigint();
-      await client.agents.init({
+      const syncResponse = await client.agents.init({
         agent: {
           agentName: state.agentName,
           agentVersion: configuredAgentVersion,
@@ -172,6 +184,9 @@ export default function register(api: OpenClawPluginApi) {
         },
         steps: state.steps,
       });
+      if (Array.isArray(syncResponse?.controls)) {
+        state.controlObservabilityById = buildControlObservabilityIndex(syncResponse.controls);
+      }
       logger.info(
         `agent-control: sync_agent duration_sec=${secondsSince(syncStartedAt)} agent=${state.sourceAgentId} step_count=${state.steps.length}`,
       );
@@ -283,22 +298,43 @@ export default function register(api: OpenClawPluginApi) {
         );
 
         const evaluateStartedAt = process.hrtime.bigint();
+        const traceContext = observabilityEnabled ? resolveTraceContext() : null;
         const evaluation = await client.evaluation.evaluate({
-          body: {
-            agentName: state.agentName,
-            stage: "pre",
-            step: {
-              type: "tool",
-              name: event.toolName,
-              input: event.params,
-              context,
-            },
+          agentName: state.agentName,
+          stage: "pre",
+          step: {
+            type: "tool",
+            name: event.toolName,
+            input: (event.params ?? null) as JsonValue,
+            context: context as Record<string, JsonValue | null>,
           },
         });
         logger.debug(
           `agent-control: before_tool_call phase=evaluate duration_sec=${secondsSince(evaluateStartedAt)} agent=${sourceAgentId} tool=${event.toolName} safe=${evaluation.isSafe}`,
         );
 
+        if (observabilityEnabled && traceContext) {
+          emitControlExecutionEvents({
+            client,
+            logger,
+            events: buildControlExecutionEvents({
+              evaluation,
+              agentName: state.agentName,
+              stepName: event.toolName,
+              stepType: "tool",
+              checkStage: "pre",
+              traceContext,
+              controlObservabilityById: state.controlObservabilityById,
+              sourceAgentId,
+              pluginId: api.id,
+              runId: event.runId ?? ctx.runId,
+              toolCallId: event.toolCallId ?? ctx.toolCallId,
+            }),
+            agentName: state.agentName,
+            stepName: event.toolName,
+          });
+        }
+
         if (evaluation.isSafe) {
           return;
         }