agent-control-openclaw-plugin 1.0.0

package/src/session-store.ts

@@ -0,0 +1,162 @@
+import type { SessionIdentitySnapshot, SessionMetadataCacheEntry, SessionStoreInternals } from "./types.ts";
+import { asString, isRecord } from "./shared.ts";
+import { getResolvedOpenClawRootDir, importOpenClawInternalModule } from "./openclaw-runtime.ts";
+
+const SESSION_META_CACHE_TTL_MS = 2_000;
+const SESSION_META_CACHE_MAX = 512;
+
+let sessionStoreInternalsPromise: Promise<SessionStoreInternals> | null = null;
+const sessionMetadataCache = new Map<string, SessionMetadataCacheEntry>();
+
+async function loadSessionStoreInternals(): Promise<SessionStoreInternals> {
+  if (sessionStoreInternalsPromise) {
+    return sessionStoreInternalsPromise;
+  }
+
+  sessionStoreInternalsPromise = (async () => {
+    const openClawRoot = getResolvedOpenClawRootDir();
+    const [configModule, sessionsModule] = await Promise.all([
+      importOpenClawInternalModule(openClawRoot, [
+        "dist/config/config.js",
+        "src/config/config.ts",
+      ]),
+      importOpenClawInternalModule(openClawRoot, [
+        "dist/config/sessions.js",
+        "src/config/sessions.ts",
+      ]),
+    ]);
+
+    const loadConfig = configModule.loadConfig;
+    const resolveStorePath = sessionsModule.resolveStorePath;
+    const loadSessionStore = sessionsModule.loadSessionStore;
+
+    if (typeof loadConfig !== "function") {
+      throw new Error("agent-control: openclaw internal loadConfig is unavailable");
+    }
+    if (typeof resolveStorePath !== "function") {
+      throw new Error("agent-control: openclaw internal resolveStorePath is unavailable");
+    }
+    if (typeof loadSessionStore !== "function") {
+      throw new Error("agent-control: openclaw internal loadSessionStore is unavailable");
+    }
+
+    return {
+      loadConfig: loadConfig as SessionStoreInternals["loadConfig"],
+      resolveStorePath: resolveStorePath as SessionStoreInternals["resolveStorePath"],
+      loadSessionStore: loadSessionStore as SessionStoreInternals["loadSessionStore"],
+    };
+  })();
+
+  return sessionStoreInternalsPromise;
+}
+
+function unknownSessionIdentity(): SessionIdentitySnapshot {
+  return {
+    provider: null,
+    type: "unknown",
+    channelName: null,
+    dmUserName: null,
+    label: null,
+    from: null,
+    to: null,
+    accountId: null,
+    source: "unknown",
+  };
+}
+
+function normalizeSessionStoreKey(sessionKey: string | undefined): string | undefined {
+  const normalized = asString(sessionKey)?.toLowerCase();
+  return normalized || undefined;
+}
+
+function resolveBaseSessionKey(sessionKey: string): string {
+  const topicIndex = sessionKey.lastIndexOf(":topic:");
+  const threadIndex = sessionKey.lastIndexOf(":thread:");
+  const markerIndex = Math.max(topicIndex, threadIndex);
+  if (markerIndex < 0) {
+    return sessionKey;
+  }
+  const base = sessionKey.slice(0, markerIndex);
+  return base || sessionKey;
+}
+
+function readSessionIdentityFromEntry(entry: Record<string, unknown>): SessionIdentitySnapshot {
+  const origin = isRecord(entry.origin) ? entry.origin : undefined;
+  const deliveryContext = isRecord(entry.deliveryContext) ? entry.deliveryContext : undefined;
+
+  const rawType = asString(origin?.chatType);
+  const type = rawType === "direct" || rawType === "group" || rawType === "channel" ? rawType : "unknown";
+
+  const label = asString(origin?.label) ?? null;
+  const provider =
+    asString(origin?.provider) ??
+    asString(entry.channel) ??
+    asString(deliveryContext?.channel) ??
+    null;
+
+  const channelName =
+    asString(entry.groupChannel) ??
+    asString(entry.subject) ??
+    (type !== "direct" ? label : undefined) ??
+    null;
+
+  const dmUserName = type === "direct" ? label ?? asString(entry.displayName) ?? null : null;
+
+  return {
+    provider,
+    type,
+    channelName,
+    dmUserName,
+    label,
+    from: asString(origin?.from) ?? null,
+    to: asString(origin?.to) ?? asString(deliveryContext?.to) ?? null,
+    accountId:
+      asString(origin?.accountId) ??
+      asString(deliveryContext?.accountId) ??
+      asString(entry.lastAccountId) ??
+      null,
+    source: "sessionStore",
+  };
+}
+
+function setSessionMetadataCache(key: string, data: SessionIdentitySnapshot): void {
+  sessionMetadataCache.set(key, { at: Date.now(), data });
+  if (sessionMetadataCache.size > SESSION_META_CACHE_MAX) {
+    const oldest = sessionMetadataCache.keys().next().value;
+    if (typeof oldest === "string") {
+      sessionMetadataCache.delete(oldest);
+    }
+  }
+}
+
+export async function resolveSessionIdentity(
+  sessionKey: string | undefined,
+): Promise<SessionIdentitySnapshot> {
+  const normalizedKey = normalizeSessionStoreKey(sessionKey);
+  if (!normalizedKey) {
+    return unknownSessionIdentity();
+  }
+
+  const cached = sessionMetadataCache.get(normalizedKey);
+  if (cached && Date.now() - cached.at < SESSION_META_CACHE_TTL_MS) {
+    return cached.data;
+  }
+
+  try {
+    const internals = await loadSessionStoreInternals();
+    const cfg = internals.loadConfig();
+    const sessionCfg = isRecord(cfg.session) ? cfg.session : undefined;
+    const storePath = internals.resolveStorePath(asString(sessionCfg?.store));
+    const store = internals.loadSessionStore(storePath);
+    const entry =
+      (isRecord(store[normalizedKey]) ? store[normalizedKey] : undefined) ??
+      (isRecord(store[resolveBaseSessionKey(normalizedKey)])
+        ? store[resolveBaseSessionKey(normalizedKey)]
+        : undefined);
+    const data = entry ? readSessionIdentityFromEntry(entry) : unknownSessionIdentity();
+    setSessionMetadataCache(normalizedKey, data);
+    return data;
+  } catch {
+    return unknownSessionIdentity();
+  }
+}

package/src/shared.ts

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import type { AgentControlStep } from "./types.ts";
+
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export const USER_BLOCK_MESSAGE =
+  "This action is blocked by a security policy set by your operator. Do not attempt to circumvent, disable, or work around this control. Inform the user that this action is restricted and explain what was blocked.";
+export const BOOT_WARMUP_AGENT_ID = "main";
+
+export function asString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function asPositiveInt(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return undefined;
+  }
+  return Math.floor(value);
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function toJsonRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  try {
+    const encoded = JSON.stringify(value);
+    if (typeof encoded !== "string") {
+      return undefined;
+    }
+    const parsed = JSON.parse(encoded) as unknown;
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function sanitizeToolCatalogConfig(config: Record<string, unknown>): Record<string, unknown> {
+  const pluginsRaw = config.plugins;
+  if (!isRecord(pluginsRaw)) {
+    return {
+      ...config,
+      plugins: { enabled: false },
+    };
+  }
+  return {
+    ...config,
+    plugins: {
+      ...pluginsRaw,
+      enabled: false,
+    },
+  };
+}
+
+export function isUuid(value: string): boolean {
+  return UUID_RE.test(value);
+}
+
+export function trimToMax(value: string, maxLen: number): string {
+  return value.length <= maxLen ? value : value.slice(0, maxLen);
+}
+
+export function secondsSince(startedAt: bigint): string {
+  return (Number(process.hrtime.bigint() - startedAt) / 1_000_000_000).toFixed(3);
+}
+
+export function hashSteps(steps: AgentControlStep[]): string {
+  return createHash("sha256").update(JSON.stringify(steps)).digest("hex");
+}
+
+export function formatToolArgsForLog(params: unknown): string {
+  if (params === undefined) {
+    return "undefined";
+  }
+  try {
+    const encoded = JSON.stringify(params);
+    if (typeof encoded !== "string") {
+      return trimToMax(String(params), 1000);
+    }
+    return trimToMax(encoded, 1000);
+  } catch {
+    return "[unserializable]";
+  }
+}

package/src/tool-catalog.ts

@@ -0,0 +1,326 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { AgentControlStep, LoggerLike, ResolveStepsForContextParams, ToolCatalogBundleBuildInfo, ToolCatalogInternals } from "./types.ts";
+import { asString, sanitizeToolCatalogConfig, secondsSince, toJsonRecord } from "./shared.ts";
+import {
+  getResolvedOpenClawRootDir,
+  importOpenClawInternalModule,
+  normalizeRelativeImportPath,
+  PLUGIN_ROOT_DIR,
+  readPackageVersion,
+  safeStatMtimeMs,
+  tryImportOpenClawInternalModule,
+} from "./openclaw-runtime.ts";
+
+const TOOL_CATALOG_BUNDLE_DIRNAME = path.join("dist", "agent-control-generated", "tool-catalog");
+const TOOL_CATALOG_BUNDLE_FILE = "index.mjs";
+const TOOL_CATALOG_WRAPPER_FILE = "entry.ts";
+
+let toolCatalogInternalsPromise: Promise<ToolCatalogInternals> | null = null;
+
+function resolveToolCatalogBundleBuildInfo(openClawRoot: string): ToolCatalogBundleBuildInfo {
+  const piToolsSource = path.join(openClawRoot, "src/agents/pi-tools.ts");
+  const adapterSource = path.join(openClawRoot, "src/agents/pi-tool-definition-adapter.ts");
+  const cacheKeySeed = JSON.stringify({
+    openClawRoot,
+    openClawVersion: readPackageVersion(path.join(openClawRoot, "package.json")) ?? "unknown",
+    pluginVersion: readPackageVersion(path.join(PLUGIN_ROOT_DIR, "..", "package.json")) ?? "unknown",
+    nodeMajor: process.versions.node.split(".")[0] ?? "unknown",
+    piToolsMtimeMs: safeStatMtimeMs(piToolsSource),
+    adapterMtimeMs: safeStatMtimeMs(adapterSource),
+  });
+  const cacheKey = createHash("sha256").update(cacheKeySeed).digest("hex").slice(0, 16);
+  const cacheDir = path.join(openClawRoot, TOOL_CATALOG_BUNDLE_DIRNAME, cacheKey);
+  return {
+    bundlePath: path.join(cacheDir, TOOL_CATALOG_BUNDLE_FILE),
+    cacheDir,
+    cacheKey,
+    openClawRoot,
+    wrapperEntryPath: path.join(cacheDir, TOOL_CATALOG_WRAPPER_FILE),
+    metaPath: path.join(cacheDir, "meta.json"),
+  };
+}
+
+function hasToolCatalogBundleSources(openClawRoot: string): boolean {
+  return (
+    fs.existsSync(path.join(openClawRoot, "src/agents/pi-tools.ts")) &&
+    fs.existsSync(path.join(openClawRoot, "src/agents/pi-tool-definition-adapter.ts"))
+  );
+}
+
+async function importToolCatalogBundleModule(
+  logger: LoggerLike,
+  buildInfo: ToolCatalogBundleBuildInfo,
+): Promise<Record<string, unknown>> {
+  const importStartedAt = process.hrtime.bigint();
+  const bundleMtime = safeStatMtimeMs(buildInfo.bundlePath) ?? Date.now();
+  const bundleUrl = `${pathToFileURL(buildInfo.bundlePath).href}?mtime=${bundleMtime}`;
+  const imported = (await import(bundleUrl)) as Record<string, unknown>;
+  logger.info(
+    `agent-control: bundle_import_done duration_sec=${secondsSince(importStartedAt)} cache_key=${buildInfo.cacheKey} bundle_path=${buildInfo.bundlePath}`,
+  );
+  return imported;
+}
+
+function resolveToolCatalogInternalsFromModules(params: {
+  adapterModule: Record<string, unknown>;
+  piToolsModule: Record<string, unknown>;
+}): ToolCatalogInternals {
+  const createOpenClawCodingTools = params.piToolsModule.createOpenClawCodingTools;
+  const toToolDefinitions = params.adapterModule.toToolDefinitions;
+  if (typeof createOpenClawCodingTools !== "function") {
+    throw new Error("agent-control: openclaw internal createOpenClawCodingTools is unavailable");
+  }
+  if (typeof toToolDefinitions !== "function") {
+    throw new Error("agent-control: openclaw internal toToolDefinitions is unavailable");
+  }
+
+  return {
+    createOpenClawCodingTools:
+      createOpenClawCodingTools as ToolCatalogInternals["createOpenClawCodingTools"],
+    toToolDefinitions: toToolDefinitions as ToolCatalogInternals["toToolDefinitions"],
+  };
+}
+
+async function ensureToolCatalogBundle(
+  logger: LoggerLike,
+  buildInfo: ToolCatalogBundleBuildInfo,
+): Promise<void> {
+  if (fs.existsSync(buildInfo.bundlePath)) {
+    logger.info(
+      `agent-control: bundle_cache_hit cache_key=${buildInfo.cacheKey} bundle_path=${buildInfo.bundlePath}`,
+    );
+    return;
+  }
+
+  const esbuildStartedAt = process.hrtime.bigint();
+  logger.info(
+    `agent-control: bundle_build_started cache_key=${buildInfo.cacheKey} openclaw_root=${buildInfo.openClawRoot}`,
+  );
+
+  let esbuild: {
+    build: (options: Record<string, unknown>) => Promise<unknown>;
+  };
+  try {
+    esbuild = (await import("esbuild")) as {
+      build: (options: Record<string, unknown>) => Promise<unknown>;
+    };
+  } catch (err) {
+    throw new Error(`agent-control: esbuild is unavailable: ${String(err)}`);
+  }
+
+  fs.mkdirSync(buildInfo.cacheDir, { recursive: true });
+  const piToolsSource = path.join(buildInfo.openClawRoot, "src/agents/pi-tools.ts");
+  const adapterSource = path.join(buildInfo.openClawRoot, "src/agents/pi-tool-definition-adapter.ts");
+  const wrapperContents = [
+    `export { createOpenClawCodingTools } from ${JSON.stringify(normalizeRelativeImportPath(buildInfo.cacheDir, piToolsSource))};`,
+    `export { toToolDefinitions } from ${JSON.stringify(normalizeRelativeImportPath(buildInfo.cacheDir, adapterSource))};`,
+    "",
+  ].join("\n");
+  fs.writeFileSync(buildInfo.wrapperEntryPath, wrapperContents, "utf8");
+
+  const tsconfigPath = path.join(buildInfo.openClawRoot, "tsconfig.json");
+  try {
+    await esbuild.build({
+      absWorkingDir: buildInfo.openClawRoot,
+      bundle: true,
+      entryPoints: [buildInfo.wrapperEntryPath],
+      format: "esm",
+      logLevel: "silent",
+      outfile: buildInfo.bundlePath,
+      packages: "external",
+      platform: "node",
+      target: [`node${process.versions.node}`],
+      tsconfig: fs.existsSync(tsconfigPath) ? tsconfigPath : undefined,
+      write: true,
+    });
+  } catch (err) {
+    fs.rmSync(buildInfo.cacheDir, { force: true, recursive: true });
+    throw err;
+  }
+
+  fs.writeFileSync(
+    buildInfo.metaPath,
+    `${JSON.stringify(
+      {
+        builtAt: new Date().toISOString(),
+        cacheKey: buildInfo.cacheKey,
+        bundlePath: buildInfo.bundlePath,
+        openClawRoot: buildInfo.openClawRoot,
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+  logger.info(
+    `agent-control: bundle_build_done duration_sec=${secondsSince(esbuildStartedAt)} cache_key=${buildInfo.cacheKey} bundle_path=${buildInfo.bundlePath}`,
+  );
+}
+
+async function loadToolCatalogInternalsFromGeneratedBundle(
+  logger: LoggerLike,
+  openClawRoot: string,
+): Promise<ToolCatalogInternals | null> {
+  if (!hasToolCatalogBundleSources(openClawRoot)) {
+    return null;
+  }
+
+  const buildInfo = resolveToolCatalogBundleBuildInfo(openClawRoot);
+  const hadBundle = fs.existsSync(buildInfo.bundlePath);
+  try {
+    await ensureToolCatalogBundle(logger, buildInfo);
+    const bundledModule = await importToolCatalogBundleModule(logger, buildInfo);
+    return resolveToolCatalogInternalsFromModules({
+      adapterModule: bundledModule,
+      piToolsModule: bundledModule,
+    });
+  } catch (err) {
+    if (hadBundle) {
+      logger.warn(
+        `agent-control: bundle_import_failed cache_key=${buildInfo.cacheKey} bundle_path=${buildInfo.bundlePath} error=${String(err)}`,
+      );
+      fs.rmSync(buildInfo.cacheDir, { force: true, recursive: true });
+      await ensureToolCatalogBundle(logger, buildInfo);
+      const rebuiltModule = await importToolCatalogBundleModule(logger, buildInfo);
+      return resolveToolCatalogInternalsFromModules({
+        adapterModule: rebuiltModule,
+        piToolsModule: rebuiltModule,
+      });
+    }
+    throw err;
+  }
+}
+
+async function loadToolCatalogInternals(logger: LoggerLike): Promise<ToolCatalogInternals> {
+  if (toolCatalogInternalsPromise) {
+    return toolCatalogInternalsPromise;
+  }
+
+  toolCatalogInternalsPromise = (async () => {
+    const openClawRoot = getResolvedOpenClawRootDir();
+    const [distPiToolsModule, distAdapterModule] = await Promise.all([
+      tryImportOpenClawInternalModule(openClawRoot, [
+        "dist/agents/pi-tools.js",
+        "dist/agents/pi-tools.mjs",
+      ]),
+      tryImportOpenClawInternalModule(openClawRoot, [
+        "dist/agents/pi-tool-definition-adapter.js",
+        "dist/agents/pi-tool-definition-adapter.mjs",
+      ]),
+    ]);
+    if (distPiToolsModule && distAdapterModule) {
+      logger.info(`agent-control: tool_catalog_internals source=dist openclaw_root=${openClawRoot}`);
+      return resolveToolCatalogInternalsFromModules({
+        adapterModule: distAdapterModule,
+        piToolsModule: distPiToolsModule,
+      });
+    }
+
+    try {
+      const bundledInternals = await loadToolCatalogInternalsFromGeneratedBundle(logger, openClawRoot);
+      if (bundledInternals) {
+        logger.info(
+          `agent-control: tool_catalog_internals source=generated_bundle openclaw_root=${openClawRoot}`,
+        );
+        return bundledInternals;
+      }
+    } catch (err) {
+      logger.warn(
+        `agent-control: bundle_fallback=jiti openclaw_root=${openClawRoot} error=${String(err)}`,
+      );
+    }
+
+    logger.info(`agent-control: tool_catalog_internals source=jiti openclaw_root=${openClawRoot}`);
+    const [piToolsModule, adapterModule] = await Promise.all([
+      importOpenClawInternalModule(openClawRoot, ["src/agents/pi-tools.ts"]),
+      importOpenClawInternalModule(openClawRoot, ["src/agents/pi-tool-definition-adapter.ts"]),
+    ]);
+
+    return resolveToolCatalogInternalsFromModules({
+      adapterModule,
+      piToolsModule,
+    });
+  })();
+
+  return toolCatalogInternalsPromise;
+}
+
+function buildSteps(
+  tools: Array<{ name: string; label?: string; description?: string; parameters?: unknown }>,
+): AgentControlStep[] {
+  const deduped = new Map<string, AgentControlStep>();
+
+  for (const tool of tools) {
+    const name = asString(tool.name);
+    if (!name) {
+      continue;
+    }
+
+    const step: AgentControlStep = {
+      type: "tool",
+      name,
+    };
+
+    const description = asString(tool.description) ?? asString(tool.label);
+    if (description) {
+      step.description = description;
+    }
+
+    const inputSchema = toJsonRecord(tool.parameters);
+    if (inputSchema) {
+      step.inputSchema = inputSchema;
+    }
+
+    const label = asString(tool.label);
+    if (label) {
+      step.metadata = { label };
+    }
+
+    deduped.set(name, step);
+  }
+
+  return [...deduped.values()];
+}
+
+export async function resolveStepsForContext(
+  params: ResolveStepsForContextParams,
+): Promise<AgentControlStep[]> {
+  const resolveStartedAt = process.hrtime.bigint();
+  const internalsStartedAt = process.hrtime.bigint();
+  const internals = await loadToolCatalogInternals(params.api.logger);
+  const internalsDurationSec = secondsSince(internalsStartedAt);
+
+  const createToolsStartedAt = process.hrtime.bigint();
+  const tools = internals.createOpenClawCodingTools({
+    agentId: params.sourceAgentId,
+    sessionKey: params.sessionKey,
+    sessionId: params.sessionId,
+    runId: params.runId,
+    config: sanitizeToolCatalogConfig(toJsonRecord(params.api.config) ?? {}),
+    // Keep the synced step catalog permissive so guardrail policy sees the full
+    // internal tool surface when sender ownership is unknown in this hook context.
+    senderIsOwner: true,
+  });
+  const createToolsDurationSec = secondsSince(createToolsStartedAt);
+
+  const adaptStartedAt = process.hrtime.bigint();
+  const toolDefinitions = internals.toToolDefinitions(tools);
+  const steps = buildSteps(
+    toolDefinitions.map((tool) => ({
+      name: tool.name,
+      label: tool.label,
+      description: tool.description,
+      parameters: tool.parameters,
+    })),
+  );
+  const adaptDurationSec = secondsSince(adaptStartedAt);
+
+  params.api.logger.info(
+    `agent-control: resolve_steps duration_sec=${secondsSince(resolveStartedAt)} agent=${params.sourceAgentId} internals_sec=${internalsDurationSec} create_tools_sec=${createToolsDurationSec} adapt_sec=${adaptDurationSec} tools=${tools.length} steps=${steps.length}`,
+  );
+
+  return steps;
+}

package/src/types.ts

@@ -0,0 +1,98 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+
+export type AgentControlPluginConfig = {
+  enabled?: boolean;
+  serverUrl?: string;
+  apiKey?: string;
+  agentName?: string;
+  agentId?: string;
+  agentVersion?: string;
+  timeoutMs?: number;
+  userAgent?: string;
+  failClosed?: boolean;
+};
+
+export type AgentControlStep = {
+  type: "tool";
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+};
+
+export type AgentState = {
+  sourceAgentId: string;
+  agentName: string;
+  steps: AgentControlStep[];
+  stepsHash: string;
+  lastSyncedStepsHash: string | null;
+  syncPromise: Promise<void> | null;
+};
+
+export type ChannelType = "direct" | "group" | "channel" | "unknown";
+
+export type DerivedChannelContext = {
+  provider: string | null;
+  type: ChannelType;
+  scope: string | null;
+  source: "sessionKey" | "unknown";
+};
+
+export type ToolCatalogInternals = {
+  createOpenClawCodingTools: (params: {
+    agentId: string;
+    sessionKey?: string;
+    sessionId?: string;
+    runId?: string;
+    config: OpenClawPluginApi["config"];
+    senderIsOwner: boolean;
+  }) => unknown[];
+  toToolDefinitions: (tools: unknown[]) => Array<{
+    name: string;
+    label?: string;
+    description?: string;
+    parameters?: unknown;
+  }>;
+};
+
+export type SessionStoreInternals = {
+  loadConfig: () => Record<string, unknown>;
+  resolveStorePath: (storePath?: string) => string;
+  loadSessionStore: (storePath: string) => Record<string, unknown>;
+};
+
+export type SessionIdentitySnapshot = {
+  provider: string | null;
+  type: ChannelType;
+  channelName: string | null;
+  dmUserName: string | null;
+  label: string | null;
+  from: string | null;
+  to: string | null;
+  accountId: string | null;
+  source: "sessionStore" | "unknown";
+};
+
+export type SessionMetadataCacheEntry = {
+  at: number;
+  data: SessionIdentitySnapshot;
+};
+
+export type LoggerLike = Pick<OpenClawPluginApi["logger"], "info" | "warn">;
+
+export type ToolCatalogBundleBuildInfo = {
+  bundlePath: string;
+  cacheDir: string;
+  cacheKey: string;
+  openClawRoot: string;
+  wrapperEntryPath: string;
+  metaPath: string;
+};
+
+export type ResolveStepsForContextParams = {
+  api: OpenClawPluginApi;
+  sourceAgentId: string;
+  sessionKey?: string;
+  sessionId?: string;
+  runId?: string;
+};