agent-control-openclaw-plugin 1.0.0

package/src/agent-control-plugin.ts

@@ -0,0 +1,333 @@
+import { AgentControlClient } from "agent-control";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { resolveStepsForContext } from "./tool-catalog.ts";
+import { buildEvaluationContext } from "./session-context.ts";
+import {
+  asPositiveInt,
+  asString,
+  BOOT_WARMUP_AGENT_ID,
+  formatToolArgsForLog,
+  hashSteps,
+  isRecord,
+  isUuid,
+  secondsSince,
+  trimToMax,
+  USER_BLOCK_MESSAGE,
+} from "./shared.ts";
+import type { AgentControlPluginConfig, AgentState } from "./types.ts";
+
+function collectDenyControlNames(response: {
+  matches?: Array<{ action?: string; controlName?: string }>;
+  errors?: Array<{ action?: string; controlName?: string }>;
+}): string[] {
+  const names: string[] = [];
+  for (const match of [...(response.matches ?? []), ...(response.errors ?? [])]) {
+    if (
+      match.action === "deny" &&
+      typeof match.controlName === "string" &&
+      match.controlName.trim()
+    ) {
+      names.push(match.controlName.trim());
+    }
+  }
+  return [...new Set(names)];
+}
+
+function buildBlockReason(response: {
+  reason?: string | null;
+  matches?: Array<{ action?: string; controlName?: string }>;
+  errors?: Array<{ action?: string; controlName?: string }>;
+}): string {
+  const denyControls = collectDenyControlNames(response);
+  if (denyControls.length > 0) {
+    return `[agent-control] blocked by deny control(s): ${denyControls.join(", ")}`;
+  }
+  if (typeof response.reason === "string" && response.reason.trim().length > 0) {
+    return `[agent-control] ${response.reason.trim()}`;
+  }
+  return "[agent-control] blocked by policy evaluation";
+}
+
+function resolveSourceAgentId(agentId: string | undefined): string {
+  const normalized = asString(agentId);
+  return normalized ?? "default";
+}
+
+function loadPluginConfig(api: OpenClawPluginApi): AgentControlPluginConfig {
+  const raw = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+  return raw as unknown as AgentControlPluginConfig;
+}
+
+export default function register(api: OpenClawPluginApi) {
+  const cfg = loadPluginConfig(api);
+  if (cfg.enabled === false) {
+    return;
+  }
+
+  const serverUrl = asString(cfg.serverUrl) ?? asString(process.env.AGENT_CONTROL_SERVER_URL);
+  if (!serverUrl) {
+    api.logger.warn(
+      "agent-control: disabled because serverUrl is not configured (plugins.entries.agent-control.serverUrl)",
+    );
+    return;
+  }
+
+  const configuredAgentId = asString(cfg.agentId);
+  if (configuredAgentId && !isUuid(configuredAgentId)) {
+    api.logger.warn(`agent-control: configured agentId is not a UUID: ${configuredAgentId}`);
+  }
+  const hasConfiguredAgentId = configuredAgentId ? isUuid(configuredAgentId) : false;
+
+  const failClosed = cfg.failClosed === true;
+  const baseAgentName = asString(cfg.agentName) ?? "openclaw-agent";
+  const configuredAgentVersion = asString(cfg.agentVersion);
+  const pluginVersion = asString(api.version);
+  const clientTimeoutMs = asPositiveInt(cfg.timeoutMs);
+
+  const clientInitStartedAt = process.hrtime.bigint();
+  const client = new AgentControlClient();
+  client.init({
+    agentName: baseAgentName,
+    serverUrl,
+    apiKey: asString(cfg.apiKey) ?? asString(process.env.AGENT_CONTROL_API_KEY),
+    timeoutMs: clientTimeoutMs,
+    userAgent: asString(cfg.userAgent) ?? "openclaw-agent-control-plugin/0.1",
+  });
+  api.logger.info(
+    `agent-control: client_init duration_sec=${secondsSince(clientInitStartedAt)} timeout_ms=${clientTimeoutMs ?? "default"} server_url=${serverUrl}`,
+  );
+
+  const states = new Map<string, AgentState>();
+  let gatewayWarmupPromise: Promise<void> | null = null;
+  let gatewayWarmupStatus: "idle" | "running" | "done" | "failed" = "idle";
+
+  const getOrCreateState = (sourceAgentId: string): AgentState => {
+    const existing = states.get(sourceAgentId);
+    if (existing) {
+      return existing;
+    }
+
+    const agentName = hasConfiguredAgentId
+      ? trimToMax(baseAgentName, 255)
+      : trimToMax(`${baseAgentName}:${sourceAgentId}`, 255);
+
+    const created: AgentState = {
+      sourceAgentId,
+      agentName,
+      steps: [],
+      stepsHash: hashSteps([]),
+      lastSyncedStepsHash: null,
+      syncPromise: null,
+    };
+    states.set(sourceAgentId, created);
+    return created;
+  };
+
+  const ensureGatewayWarmup = (): Promise<void> => {
+    if (gatewayWarmupPromise) {
+      return gatewayWarmupPromise;
+    }
+
+    const warmupStartedAt = process.hrtime.bigint();
+    gatewayWarmupStatus = "running";
+    api.logger.info(`agent-control: gateway_boot_warmup started agent=${BOOT_WARMUP_AGENT_ID}`);
+
+    // Warm the exact resolver path used during tool evaluation so the gateway
+    // process retains the expensive module graph in memory after startup.
+    gatewayWarmupPromise = resolveStepsForContext({
+      api,
+      sourceAgentId: BOOT_WARMUP_AGENT_ID,
+    })
+      .then((steps) => {
+        gatewayWarmupStatus = "done";
+        api.logger.info(
+          `agent-control: gateway_boot_warmup done duration_sec=${secondsSince(warmupStartedAt)} agent=${BOOT_WARMUP_AGENT_ID} steps=${steps.length}`,
+        );
+      })
+      .catch((err) => {
+        gatewayWarmupStatus = "failed";
+        api.logger.warn(
+          `agent-control: gateway_boot_warmup failed duration_sec=${secondsSince(warmupStartedAt)} agent=${BOOT_WARMUP_AGENT_ID} error=${String(err)}`,
+        );
+      });
+
+    return gatewayWarmupPromise;
+  };
+
+  const syncAgent = async (state: AgentState): Promise<void> => {
+    if (state.syncPromise) {
+      await state.syncPromise;
+      return;
+    }
+    if (state.lastSyncedStepsHash === state.stepsHash) {
+      return;
+    }
+
+    const currentHash = state.stepsHash;
+    const promise = (async () => {
+      await client.agents.init({
+        agent: {
+          agentName: state.agentName,
+          agentVersion: configuredAgentVersion,
+          agentMetadata: {
+            source: "openclaw",
+            openclawAgentId: state.sourceAgentId,
+            ...(configuredAgentId ? { openclawConfiguredAgentId: configuredAgentId } : {}),
+            pluginId: api.id,
+          },
+        },
+        steps: state.steps,
+      });
+      state.lastSyncedStepsHash = currentHash;
+    })().finally(() => {
+      state.syncPromise = null;
+    });
+
+    state.syncPromise = promise;
+    await promise;
+
+    // If tools changed while we were syncing, reconcile immediately.
+    if (state.stepsHash !== state.lastSyncedStepsHash) {
+      await syncAgent(state);
+    }
+  };
+
+  api.on("gateway_start", async () => {
+    await ensureGatewayWarmup();
+  });
+
+  api.on("before_tool_call", async (event, ctx) => {
+    const beforeToolCallStartedAt = process.hrtime.bigint();
+    const sourceAgentId = resolveSourceAgentId(ctx.agentId);
+    const state = getOrCreateState(sourceAgentId);
+    const argsForLog = formatToolArgsForLog(event.params);
+    api.logger.info(
+      `agent-control: before_tool_call entered agent=${sourceAgentId} tool=${event.toolName} args=${argsForLog}`,
+    );
+
+    try {
+      if (gatewayWarmupStatus === "running" && gatewayWarmupPromise) {
+        const warmupWaitStartedAt = process.hrtime.bigint();
+        api.logger.info(
+          `agent-control: before_tool_call waiting_for_gateway_boot_warmup=true agent=${sourceAgentId} tool=${event.toolName}`,
+        );
+        await gatewayWarmupPromise;
+        api.logger.info(
+          `agent-control: before_tool_call phase=wait_boot_warmup duration_sec=${secondsSince(warmupWaitStartedAt)} agent=${sourceAgentId} tool=${event.toolName} warmup_status=${gatewayWarmupStatus}`,
+        );
+      }
+
+      try {
+        const resolveStepsStartedAt = process.hrtime.bigint();
+        const nextSteps = await resolveStepsForContext({
+          api,
+          sourceAgentId,
+          sessionKey: ctx.sessionKey,
+          sessionId: ctx.sessionId,
+          runId: ctx.runId,
+        });
+        const nextStepsHash = hashSteps(nextSteps);
+        if (nextStepsHash !== state.stepsHash) {
+          state.steps = nextSteps;
+          state.stepsHash = nextStepsHash;
+        }
+        api.logger.info(
+          `agent-control: before_tool_call phase=resolve_steps duration_sec=${secondsSince(resolveStepsStartedAt)} agent=${sourceAgentId} tool=${event.toolName} steps=${nextSteps.length}`,
+        );
+
+        const syncStartedAt = process.hrtime.bigint();
+        await syncAgent(state);
+        api.logger.info(
+          `agent-control: before_tool_call phase=sync_agent duration_sec=${secondsSince(syncStartedAt)} agent=${sourceAgentId} tool=${event.toolName} step_count=${state.steps.length}`,
+        );
+      } catch (err) {
+        api.logger.warn(
+          `agent-control: unable to sync agent=${sourceAgentId} before tool evaluation: ${String(err)}`,
+        );
+        if (failClosed) {
+          return {
+            block: true,
+            blockReason: USER_BLOCK_MESSAGE,
+          };
+        }
+        return;
+      }
+
+      try {
+        const contextBuildStartedAt = process.hrtime.bigint();
+        const context = await buildEvaluationContext({
+          api,
+          sourceAgentId,
+          state,
+          event: {
+            runId: event.runId,
+            toolCallId: event.toolCallId,
+          },
+          ctx: {
+            sessionKey: ctx.sessionKey,
+            sessionId: ctx.sessionId,
+            runId: ctx.runId,
+            toolCallId: ctx.toolCallId,
+          },
+          pluginVersion,
+          failClosed,
+          configuredAgentId,
+          configuredAgentVersion,
+        });
+        api.logger.info(
+          `agent-control: before_tool_call phase=build_context duration_sec=${secondsSince(contextBuildStartedAt)} agent=${sourceAgentId} tool=${event.toolName}`,
+        );
+
+        api.logger.info(
+          `agent-control: before_tool_call evaluated agent=${sourceAgentId} tool=${event.toolName} args=${argsForLog} context=${JSON.stringify(context, null, 2)}`,
+        );
+
+        const evaluateStartedAt = process.hrtime.bigint();
+        const evaluation = await client.evaluation.evaluate({
+          body: {
+            agentName: state.agentName,
+            stage: "pre",
+            step: {
+              type: "tool",
+              name: event.toolName,
+              input: event.params,
+              context,
+            },
+          },
+        });
+        api.logger.info(
+          `agent-control: before_tool_call phase=evaluate duration_sec=${secondsSince(evaluateStartedAt)} agent=${sourceAgentId} tool=${event.toolName} safe=${evaluation.isSafe}`,
+        );
+
+        if (evaluation.isSafe) {
+          api.logger.info("safe !");
+          return;
+        }
+
+        api.logger.info("unsafe !");
+        api.logger.warn(
+          `agent-control: blocked tool=${event.toolName} agent=${sourceAgentId} reason=${buildBlockReason(evaluation)}`,
+        );
+        return {
+          block: true,
+          blockReason: USER_BLOCK_MESSAGE,
+        };
+      } catch (err) {
+        api.logger.warn(
+          `agent-control: evaluation failed for agent=${sourceAgentId} tool=${event.toolName}: ${String(err)}`,
+        );
+        if (failClosed) {
+          return {
+            block: true,
+            blockReason: USER_BLOCK_MESSAGE,
+          };
+        }
+        return;
+      }
+    } finally {
+      api.logger.info(
+        `agent-control: before_tool_call duration_sec=${secondsSince(beforeToolCallStartedAt)} agent=${sourceAgentId} tool=${event.toolName}`,
+      );
+    }
+  });
+}

package/src/openclaw-runtime.ts

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createJiti } from "jiti";
+
+const requireFromPlugin = createRequire(import.meta.url);
+const jiti = createJiti(import.meta.url, {
+  interopDefault: true,
+  extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs", ".json"],
+});
+
+export const PLUGIN_ROOT_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+let resolvedOpenClawRootDir: string | null = null;
+
+function readPackageField(packageJsonPath: string, field: "name" | "version"): string | undefined {
+  try {
+    const raw = fs.readFileSync(packageJsonPath, "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object") {
+      return undefined;
+    }
+    const value = (parsed as { name?: unknown; version?: unknown })[field];
+    return typeof value === "string" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function readPackageName(packageJsonPath: string): string | undefined {
+  return readPackageField(packageJsonPath, "name");
+}
+
+export function readPackageVersion(packageJsonPath: string): string | undefined {
+  return readPackageField(packageJsonPath, "version");
+}
+
+export function safeStatMtimeMs(filePath: string): number | null {
+  try {
+    return fs.statSync(filePath).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+export function normalizeRelativeImportPath(fromDir: string, toFile: string): string {
+  const relativePath = path.relative(fromDir, toFile).replaceAll(path.sep, "/");
+  if (relativePath.startsWith(".")) {
+    return relativePath;
+  }
+  return `./${relativePath}`;
+}
+
+function findOpenClawRootFrom(startPath: string | undefined): string | undefined {
+  if (!startPath) {
+    return undefined;
+  }
+  let cursor = path.resolve(startPath);
+  while (true) {
+    const packageJson = path.join(cursor, "package.json");
+    if (fs.existsSync(packageJson) && readPackageName(packageJson) === "openclaw") {
+      return cursor;
+    }
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      return undefined;
+    }
+    cursor = parent;
+  }
+}
+
+function resolveOpenClawRootDir(): string {
+  try {
+    const pkgJson = requireFromPlugin.resolve("openclaw/package.json");
+    return path.dirname(pkgJson);
+  } catch {
+    // Fall through to process-based probing below.
+  }
+
+  const argvEntry = process.argv[1];
+  const argvEntryRealpath = (() => {
+    if (!argvEntry) {
+      return undefined;
+    }
+    try {
+      return fs.realpathSync(argvEntry);
+    } catch {
+      return undefined;
+    }
+  })();
+
+  const candidates = [
+    argvEntry ? findOpenClawRootFrom(path.dirname(argvEntry)) : undefined,
+    argvEntryRealpath ? findOpenClawRootFrom(path.dirname(argvEntryRealpath)) : undefined,
+    findOpenClawRootFrom(process.cwd()),
+  ];
+  const found = candidates.find((entry): entry is string => typeof entry === "string");
+  if (!found) {
+    throw new Error(
+      "agent-control: unable to resolve openclaw package root for internal tool schema access",
+    );
+  }
+  return found;
+}
+
+export function getResolvedOpenClawRootDir(): string {
+  if (!resolvedOpenClawRootDir) {
+    resolvedOpenClawRootDir = resolveOpenClawRootDir();
+  }
+  return resolvedOpenClawRootDir;
+}
+
+export async function tryImportOpenClawInternalModule(
+  openClawRoot: string,
+  candidates: string[],
+): Promise<Record<string, unknown> | null> {
+  for (const relativePath of candidates) {
+    const absolutePath = path.join(openClawRoot, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+      continue;
+    }
+    try {
+      return (await import(pathToFileURL(absolutePath).href)) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+export async function importOpenClawInternalModule(
+  openClawRoot: string,
+  candidates: string[],
+): Promise<Record<string, unknown>> {
+  let lastErr: unknown;
+  for (const relativePath of candidates) {
+    const absolutePath = path.join(openClawRoot, relativePath);
+    if (!fs.existsSync(absolutePath)) {
+      continue;
+    }
+    try {
+      if (absolutePath.endsWith(".ts")) {
+        return jiti(absolutePath) as Record<string, unknown>;
+      }
+      return (await import(pathToFileURL(absolutePath).href)) as Record<string, unknown>;
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  throw (
+    lastErr ??
+    new Error(
+      `agent-control: openclaw internal module not found (${candidates.join(", ")}) under ${openClawRoot}`,
+    )
+  );
+}

package/src/session-context.ts

@@ -0,0 +1,135 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { resolveSessionIdentity } from "./session-store.ts";
+import { asString } from "./shared.ts";
+import type { AgentState, ChannelType, DerivedChannelContext } from "./types.ts";
+
+function parseAgentSessionKey(sessionKey: string | undefined): { agentId: string; scope: string } | null {
+  const normalized = asString(sessionKey)?.toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  const parts = normalized.split(":").filter(Boolean);
+  if (parts.length < 3 || parts[0] !== "agent") {
+    return null;
+  }
+  const agentId = parts[1];
+  const scope = parts.slice(2).join(":");
+  if (!agentId || !scope) {
+    return null;
+  }
+  return { agentId, scope };
+}
+
+function deriveChannelType(scope: string): ChannelType {
+  const tokens = new Set(scope.split(":").filter(Boolean));
+  if (tokens.has("group")) {
+    return "group";
+  }
+  if (tokens.has("channel")) {
+    return "channel";
+  }
+  if (tokens.has("direct") || tokens.has("dm")) {
+    return "direct";
+  }
+  if (/^discord:(?:[^:]+:)?guild-[^:]+:channel-[^:]+$/.test(scope)) {
+    return "channel";
+  }
+  return "unknown";
+}
+
+function deriveChannelContext(sessionKey: string | undefined): DerivedChannelContext {
+  const parsed = parseAgentSessionKey(sessionKey);
+  if (!parsed) {
+    return {
+      provider: null,
+      type: "unknown",
+      scope: null,
+      source: "unknown",
+    };
+  }
+
+  const scopeTokens = parsed.scope.split(":").filter(Boolean);
+  const firstToken = scopeTokens[0];
+  const provider =
+    firstToken &&
+    !["main", "subagent", "cron", "acp", "memory", "heartbeat"].includes(firstToken)
+      ? firstToken
+      : null;
+
+  return {
+    provider,
+    type: deriveChannelType(parsed.scope),
+    scope: parsed.scope,
+    source: "sessionKey",
+  };
+}
+
+export async function buildEvaluationContext(params: {
+  api: OpenClawPluginApi;
+  sourceAgentId: string;
+  state: AgentState;
+  event: {
+    runId?: string;
+    toolCallId?: string;
+  };
+  ctx: {
+    sessionKey?: string;
+    sessionId?: string;
+    runId?: string;
+    toolCallId?: string;
+  };
+  pluginVersion?: string;
+  failClosed: boolean;
+  configuredAgentId?: string;
+  configuredAgentVersion?: string;
+}): Promise<Record<string, unknown>> {
+  const channelFromSessionKey = deriveChannelContext(params.ctx.sessionKey);
+  const sessionIdentity = await resolveSessionIdentity(params.ctx.sessionKey);
+  const mergedChannelType =
+    sessionIdentity.type !== "unknown" ? sessionIdentity.type : channelFromSessionKey.type;
+  const mergedChannelProvider = sessionIdentity.provider ?? channelFromSessionKey.provider;
+
+  const channel = {
+    provider: mergedChannelProvider,
+    type: mergedChannelType,
+    scope: channelFromSessionKey.scope,
+    source:
+      sessionIdentity.source === "sessionStore"
+        ? "sessionStore+sessionKey"
+        : channelFromSessionKey.source,
+    name: sessionIdentity.channelName,
+    dmUserName: sessionIdentity.dmUserName,
+    label: sessionIdentity.label,
+    from: sessionIdentity.from,
+    to: sessionIdentity.to,
+    accountId: sessionIdentity.accountId,
+  };
+
+  return {
+    openclawAgentId: params.sourceAgentId,
+    sessionKey: params.ctx.sessionKey ?? null,
+    sessionId: params.ctx.sessionId ?? null,
+    runId: params.ctx.runId ?? params.event.runId ?? null,
+    toolCallId: params.ctx.toolCallId ?? params.event.toolCallId ?? null,
+    channelType: mergedChannelType,
+    channelName: sessionIdentity.channelName,
+    dmUserName: sessionIdentity.dmUserName,
+    senderFrom: sessionIdentity.from,
+    channel,
+    plugin: {
+      id: params.api.id,
+      version: params.pluginVersion ?? null,
+    },
+    policy: {
+      failClosed: params.failClosed,
+      configuredAgentId: params.configuredAgentId ?? null,
+      configuredAgentVersion: params.configuredAgentVersion ?? null,
+    },
+    sync: {
+      agentName: params.state.agentName,
+      stepCount: params.state.steps.length,
+      stepsHash: params.state.stepsHash,
+      lastSyncedStepsHash: params.state.lastSyncedStepsHash,
+    },
+  };
+}