@openclaw/feishu 2026.2.25 → 2026.3.2

package/src/streaming-card.ts

@@ -3,11 +3,19 @@
  */
 
 import type { Client } from "@larksuiteoapi/node-sdk";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk";
 import type { FeishuDomain } from "./types.js";
 
 type Credentials = { appId: string; appSecret: string; domain?: FeishuDomain };
 type CardState = { cardId: string; messageId: string; sequence: number; currentText: string };
 
+/** Optional header for streaming cards (title bar with color template) */
+export type StreamingCardHeader = {
+  title: string;
+  /** Color template: blue, green, red, orange, purple, indigo, wathet, turquoise, yellow, grey, carmine, violet, lime */
+  template?: string;
+};
+
 // Token cache (keyed by domain + appId)
 const tokenCache = new Map<string, { token: string; expiresAt: number }>();
 
@@ -21,6 +29,20 @@ function resolveApiBase(domain?: FeishuDomain): string {
   return "https://open.feishu.cn/open-apis";
 }
 
+function resolveAllowedHostnames(domain?: FeishuDomain): string[] {
+  if (domain === "lark") {
+    return ["open.larksuite.com"];
+  }
+  if (domain && domain !== "feishu" && domain.startsWith("http")) {
+    try {
+      return [new URL(domain).hostname];
+    } catch {
+      return [];
+    }
+  }
+  return ["open.feishu.cn"];
+}
+
 async function getToken(creds: Credentials): Promise<string> {
   const key = `${creds.domain ?? "feishu"}|${creds.appId}`;
   const cached = tokenCache.get(key);
@@ -28,17 +50,23 @@ async function getToken(creds: Credentials): Promise<string> {
     return cached.token;
   }
 
-  const res = await fetch(`${resolveApiBase(creds.domain)}/auth/v3/tenant_access_token/internal`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ app_id: creds.appId, app_secret: creds.appSecret }),
+  const { response, release } = await fetchWithSsrFGuard({
+    url: `${resolveApiBase(creds.domain)}/auth/v3/tenant_access_token/internal`,
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ app_id: creds.appId, app_secret: creds.appSecret }),
+    },
+    policy: { allowedHostnames: resolveAllowedHostnames(creds.domain) },
+    auditContext: "feishu.streaming-card.token",
   });
-  const data = (await res.json()) as {
+  const data = (await response.json()) as {
     code: number;
     msg: string;
     tenant_access_token?: string;
     expire?: number;
   };
+  await release();
   if (data.code !== 0 || !data.tenant_access_token) {
     throw new Error(`Token error: ${data.msg}`);
   }
@@ -78,13 +106,19 @@ export class FeishuStreamingSession {
   async start(
     receiveId: string,
     receiveIdType: "open_id" | "user_id" | "union_id" | "email" | "chat_id" = "chat_id",
+    options?: {
+      replyToMessageId?: string;
+      replyInThread?: boolean;
+      rootId?: string;
+      header?: StreamingCardHeader;
+    },
   ): Promise<void> {
     if (this.state) {
       return;
     }
 
     const apiBase = resolveApiBase(this.creds.domain);
-    const cardJson = {
+    const cardJson: Record<string, unknown> = {
       schema: "2.0",
       config: {
         streaming_mode: true,
@@ -95,35 +129,71 @@ export class FeishuStreamingSession {
         elements: [{ tag: "markdown", content: "⏳ Thinking...", element_id: "content" }],
       },
     };
+    if (options?.header) {
+      cardJson.header = {
+        title: { tag: "plain_text", content: options.header.title },
+        template: options.header.template ?? "blue",
+      };
+    }
 
     // Create card entity
-    const createRes = await fetch(`${apiBase}/cardkit/v1/cards`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${await getToken(this.creds)}`,
-        "Content-Type": "application/json",
+    const { response: createRes, release: releaseCreate } = await fetchWithSsrFGuard({
+      url: `${apiBase}/cardkit/v1/cards`,
+      init: {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ type: "card_json", data: JSON.stringify(cardJson) }),
       },
-      body: JSON.stringify({ type: "card_json", data: JSON.stringify(cardJson) }),
+      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+      auditContext: "feishu.streaming-card.create",
     });
     const createData = (await createRes.json()) as {
       code: number;
       msg: string;
       data?: { card_id: string };
     };
+    await releaseCreate();
     if (createData.code !== 0 || !createData.data?.card_id) {
       throw new Error(`Create card failed: ${createData.msg}`);
     }
     const cardId = createData.data.card_id;
+    const cardContent = JSON.stringify({ type: "card", data: { card_id: cardId } });
 
-    // Send card message
-    const sendRes = await this.client.im.message.create({
-      params: { receive_id_type: receiveIdType },
-      data: {
+    // Topic-group replies require root_id routing. Prefer create+root_id when available.
+    let sendRes;
+    if (options?.rootId) {
+      const createData = {
         receive_id: receiveId,
         msg_type: "interactive",
-        content: JSON.stringify({ type: "card", data: { card_id: cardId } }),
-      },
-    });
+        content: cardContent,
+        root_id: options.rootId,
+      };
+      sendRes = await this.client.im.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: createData,
+      });
+    } else if (options?.replyToMessageId) {
+      sendRes = await this.client.im.message.reply({
+        path: { message_id: options.replyToMessageId },
+        data: {
+          msg_type: "interactive",
+          content: cardContent,
+          ...(options.replyInThread ? { reply_in_thread: true } : {}),
+        },
+      });
+    } else {
+      sendRes = await this.client.im.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: {
+          receive_id: receiveId,
+          msg_type: "interactive",
+          content: cardContent,
+        },
+      });
+    }
     if (sendRes.code !== 0 || !sendRes.data?.message_id) {
       throw new Error(`Send card failed: ${sendRes.msg}`);
     }
@@ -138,18 +208,27 @@ export class FeishuStreamingSession {
     }
     const apiBase = resolveApiBase(this.creds.domain);
     this.state.sequence += 1;
-    await fetch(`${apiBase}/cardkit/v1/cards/${this.state.cardId}/elements/content/content`, {
-      method: "PUT",
-      headers: {
-        Authorization: `Bearer ${await getToken(this.creds)}`,
-        "Content-Type": "application/json",
+    await fetchWithSsrFGuard({
+      url: `${apiBase}/cardkit/v1/cards/${this.state.cardId}/elements/content/content`,
+      init: {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          content: text,
+          sequence: this.state.sequence,
+          uuid: `s_${this.state.cardId}_${this.state.sequence}`,
+        }),
       },
-      body: JSON.stringify({
-        content: text,
-        sequence: this.state.sequence,
-        uuid: `s_${this.state.cardId}_${this.state.sequence}`,
-      }),
-    }).catch((error) => onError?.(error));
+      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+      auditContext: "feishu.streaming-card.update",
+    })
+      .then(async ({ release }) => {
+        await release();
+      })
+      .catch((error) => onError?.(error));
   }
 
   async update(text: string): Promise<void> {
@@ -194,20 +273,29 @@ export class FeishuStreamingSession {
 
     // Close streaming mode
     this.state.sequence += 1;
-    await fetch(`${apiBase}/cardkit/v1/cards/${this.state.cardId}/settings`, {
-      method: "PATCH",
-      headers: {
-        Authorization: `Bearer ${await getToken(this.creds)}`,
-        "Content-Type": "application/json; charset=utf-8",
-      },
-      body: JSON.stringify({
-        settings: JSON.stringify({
-          config: { streaming_mode: false, summary: { content: truncateSummary(text) } },
+    await fetchWithSsrFGuard({
+      url: `${apiBase}/cardkit/v1/cards/${this.state.cardId}/settings`,
+      init: {
+        method: "PATCH",
+        headers: {
+          Authorization: `Bearer ${await getToken(this.creds)}`,
+          "Content-Type": "application/json; charset=utf-8",
+        },
+        body: JSON.stringify({
+          settings: JSON.stringify({
+            config: { streaming_mode: false, summary: { content: truncateSummary(text) } },
+          }),
+          sequence: this.state.sequence,
+          uuid: `c_${this.state.cardId}_${this.state.sequence}`,
         }),
-        sequence: this.state.sequence,
-        uuid: `c_${this.state.cardId}_${this.state.sequence}`,
-      }),
-    }).catch((e) => this.log?.(`Close failed: ${String(e)}`));
+      },
+      policy: { allowedHostnames: resolveAllowedHostnames(this.creds.domain) },
+      auditContext: "feishu.streaming-card.close",
+    })
+      .then(async ({ release }) => {
+        await release();
+      })
+      .catch((e) => this.log?.(`Close failed: ${String(e)}`));
 
     this.log?.(`Closed streaming: cardId=${this.state.cardId}`);
   }

package/src/targets.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { resolveReceiveIdType } from "./targets.js";
+import { looksLikeFeishuId, normalizeFeishuTarget, resolveReceiveIdType } from "./targets.js";
 
 describe("resolveReceiveIdType", () => {
   it("resolves chat IDs by oc_ prefix", () => {
@@ -13,4 +13,58 @@ describe("resolveReceiveIdType", () => {
   it("defaults unprefixed IDs to user_id", () => {
     expect(resolveReceiveIdType("u_123")).toBe("user_id");
   });
+
+  it("treats explicit group targets as chat_id", () => {
+    expect(resolveReceiveIdType("group:oc_123")).toBe("chat_id");
+  });
+
+  it("treats explicit channel targets as chat_id", () => {
+    expect(resolveReceiveIdType("channel:oc_123")).toBe("chat_id");
+  });
+
+  it("treats dm-prefixed open IDs as open_id", () => {
+    expect(resolveReceiveIdType("dm:ou_123")).toBe("open_id");
+  });
+});
+
+describe("normalizeFeishuTarget", () => {
+  it("strips provider and user prefixes", () => {
+    expect(normalizeFeishuTarget("feishu:user:ou_123")).toBe("ou_123");
+    expect(normalizeFeishuTarget("lark:user:ou_123")).toBe("ou_123");
+  });
+
+  it("strips provider and chat prefixes", () => {
+    expect(normalizeFeishuTarget("feishu:chat:oc_123")).toBe("oc_123");
+  });
+
+  it("normalizes group/channel prefixes to chat ids", () => {
+    expect(normalizeFeishuTarget("group:oc_123")).toBe("oc_123");
+    expect(normalizeFeishuTarget("feishu:group:oc_123")).toBe("oc_123");
+    expect(normalizeFeishuTarget("channel:oc_456")).toBe("oc_456");
+    expect(normalizeFeishuTarget("lark:channel:oc_456")).toBe("oc_456");
+  });
+
+  it("accepts provider-prefixed raw ids", () => {
+    expect(normalizeFeishuTarget("feishu:ou_123")).toBe("ou_123");
+  });
+
+  it("strips provider and dm prefixes", () => {
+    expect(normalizeFeishuTarget("lark:dm:ou_123")).toBe("ou_123");
+  });
+});
+
+describe("looksLikeFeishuId", () => {
+  it("accepts provider-prefixed user targets", () => {
+    expect(looksLikeFeishuId("feishu:user:ou_123")).toBe(true);
+  });
+
+  it("accepts provider-prefixed chat targets", () => {
+    expect(looksLikeFeishuId("lark:chat:oc_123")).toBe(true);
+  });
+
+  it("accepts group/channel targets", () => {
+    expect(looksLikeFeishuId("feishu:group:oc_123")).toBe(true);
+    expect(looksLikeFeishuId("group:oc_123")).toBe(true);
+    expect(looksLikeFeishuId("channel:oc_456")).toBe(true);
+  });
 });

package/src/targets.ts

@@ -4,6 +4,10 @@ const CHAT_ID_PREFIX = "oc_";
 const OPEN_ID_PREFIX = "ou_";
 const USER_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
 
+function stripProviderPrefix(raw: string): string {
+  return raw.replace(/^(feishu|lark):/i, "").trim();
+}
+
 export function detectIdType(id: string): FeishuIdType | null {
   const trimmed = id.trim();
   if (trimmed.startsWith(CHAT_ID_PREFIX)) {
@@ -24,18 +28,28 @@ export function normalizeFeishuTarget(raw: string): string | null {
     return null;
   }
 
-  const lowered = trimmed.toLowerCase();
+  const withoutProvider = stripProviderPrefix(trimmed);
+  const lowered = withoutProvider.toLowerCase();
   if (lowered.startsWith("chat:")) {
-    return trimmed.slice("chat:".length).trim() || null;
+    return withoutProvider.slice("chat:".length).trim() || null;
+  }
+  if (lowered.startsWith("group:")) {
+    return withoutProvider.slice("group:".length).trim() || null;
+  }
+  if (lowered.startsWith("channel:")) {
+    return withoutProvider.slice("channel:".length).trim() || null;
   }
   if (lowered.startsWith("user:")) {
-    return trimmed.slice("user:".length).trim() || null;
+    return withoutProvider.slice("user:".length).trim() || null;
+  }
+  if (lowered.startsWith("dm:")) {
+    return withoutProvider.slice("dm:".length).trim() || null;
   }
   if (lowered.startsWith("open_id:")) {
-    return trimmed.slice("open_id:".length).trim() || null;
+    return withoutProvider.slice("open_id:".length).trim() || null;
   }
 
-  return trimmed;
+  return withoutProvider;
 }
 
 export function formatFeishuTarget(id: string, type?: FeishuIdType): string {
@@ -51,6 +65,17 @@ export function formatFeishuTarget(id: string, type?: FeishuIdType): string {
 
 export function resolveReceiveIdType(id: string): "chat_id" | "open_id" | "user_id" {
   const trimmed = id.trim();
+  const lowered = trimmed.toLowerCase();
+  if (lowered.startsWith("chat:") || lowered.startsWith("group:")) {
+    return "chat_id";
+  }
+  if (lowered.startsWith("open_id:")) {
+    return "open_id";
+  }
+  if (lowered.startsWith("user:") || lowered.startsWith("dm:")) {
+    const normalized = trimmed.replace(/^(user|dm):/i, "").trim();
+    return normalized.startsWith(OPEN_ID_PREFIX) ? "open_id" : "user_id";
+  }
   if (trimmed.startsWith(CHAT_ID_PREFIX)) {
     return "chat_id";
   }
@@ -61,11 +86,11 @@ export function resolveReceiveIdType(id: string): "chat_id" | "open_id" | "user_
 }
 
 export function looksLikeFeishuId(raw: string): boolean {
-  const trimmed = raw.trim();
+  const trimmed = stripProviderPrefix(raw.trim());
   if (!trimmed) {
     return false;
   }
-  if (/^(chat|user|open_id):/i.test(trimmed)) {
+  if (/^(chat|group|channel|user|dm|open_id):/i.test(trimmed)) {
     return true;
   }
   if (trimmed.startsWith(CHAT_ID_PREFIX)) {

package/src/tool-account-routing.test.ts

@@ -0,0 +1,129 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { registerFeishuBitableTools } from "./bitable.js";
+import { registerFeishuDriveTools } from "./drive.js";
+import { registerFeishuPermTools } from "./perm.js";
+import { createToolFactoryHarness } from "./tool-factory-test-harness.js";
+import { registerFeishuWikiTools } from "./wiki.js";
+
+const createFeishuClientMock = vi.fn((account: { appId?: string } | undefined) => ({
+  __appId: account?.appId,
+}));
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: (account: { appId?: string } | undefined) => createFeishuClientMock(account),
+}));
+
+function createConfig(params: {
+  toolsA?: {
+    wiki?: boolean;
+    drive?: boolean;
+    perm?: boolean;
+  };
+  toolsB?: {
+    wiki?: boolean;
+    drive?: boolean;
+    perm?: boolean;
+  };
+  defaultAccount?: string;
+}): OpenClawPluginApi["config"] {
+  return {
+    channels: {
+      feishu: {
+        enabled: true,
+        defaultAccount: params.defaultAccount,
+        accounts: {
+          a: {
+            appId: "app-a",
+            appSecret: "sec-a",
+            tools: params.toolsA,
+          },
+          b: {
+            appId: "app-b",
+            appSecret: "sec-b",
+            tools: params.toolsB,
+          },
+        },
+      },
+    },
+  } as OpenClawPluginApi["config"];
+}
+
+describe("feishu tool account routing", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test("wiki tool registers when first account disables it and routes to agentAccountId", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { wiki: false },
+        toolsB: { wiki: true },
+      }),
+    );
+    registerFeishuWikiTools(api);
+
+    const tool = resolveTool("feishu_wiki", { agentAccountId: "b" });
+    await tool.execute("call", { action: "search" });
+
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
+
+  test("wiki tool prefers configured defaultAccount over inherited default account context", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        defaultAccount: "b",
+        toolsA: { wiki: true },
+        toolsB: { wiki: true },
+      }),
+    );
+    registerFeishuWikiTools(api);
+
+    const tool = resolveTool("feishu_wiki", { agentAccountId: "a" });
+    await tool.execute("call", { action: "search" });
+
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
+
+  test("drive tool registers when first account disables it and routes to agentAccountId", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { drive: false },
+        toolsB: { drive: true },
+      }),
+    );
+    registerFeishuDriveTools(api);
+
+    const tool = resolveTool("feishu_drive", { agentAccountId: "b" });
+    await tool.execute("call", { action: "unknown_action" });
+
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
+
+  test("perm tool registers when only second account enables it and routes to agentAccountId", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(
+      createConfig({
+        toolsA: { perm: false },
+        toolsB: { perm: true },
+      }),
+    );
+    registerFeishuPermTools(api);
+
+    const tool = resolveTool("feishu_perm", { agentAccountId: "b" });
+    await tool.execute("call", { action: "unknown_action" });
+
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
+
+  test("bitable tool routes to agentAccountId and allows explicit accountId override", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(createConfig({}));
+    registerFeishuBitableTools(api);
+
+    const tool = resolveTool("feishu_bitable_get_meta", { agentAccountId: "b" });
+    await tool.execute("call-ctx", { url: "invalid-url" });
+    await tool.execute("call-override", { url: "invalid-url", accountId: "a" });
+
+    expect(createFeishuClientMock.mock.calls[0]?.[0]?.appId).toBe("app-b");
+    expect(createFeishuClientMock.mock.calls[1]?.[0]?.appId).toBe("app-a");
+  });
+});

package/src/tool-account.ts

@@ -0,0 +1,70 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { resolveFeishuAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+import { resolveToolsConfig } from "./tools-config.js";
+import type { FeishuToolsConfig, ResolvedFeishuAccount } from "./types.js";
+
+type AccountAwareParams = { accountId?: string };
+
+function normalizeOptionalAccountId(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function readConfiguredDefaultAccountId(config: OpenClawPluginApi["config"]): string | undefined {
+  const value = (config?.channels?.feishu as { defaultAccount?: unknown } | undefined)
+    ?.defaultAccount;
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  return normalizeOptionalAccountId(value);
+}
+
+export function resolveFeishuToolAccount(params: {
+  api: Pick<OpenClawPluginApi, "config">;
+  executeParams?: AccountAwareParams;
+  defaultAccountId?: string;
+}): ResolvedFeishuAccount {
+  if (!params.api.config) {
+    throw new Error("Feishu config unavailable");
+  }
+  return resolveFeishuAccount({
+    cfg: params.api.config,
+    accountId:
+      normalizeOptionalAccountId(params.executeParams?.accountId) ??
+      readConfiguredDefaultAccountId(params.api.config) ??
+      normalizeOptionalAccountId(params.defaultAccountId),
+  });
+}
+
+export function createFeishuToolClient(params: {
+  api: Pick<OpenClawPluginApi, "config">;
+  executeParams?: AccountAwareParams;
+  defaultAccountId?: string;
+}): Lark.Client {
+  return createFeishuClient(resolveFeishuToolAccount(params));
+}
+
+export function resolveAnyEnabledFeishuToolsConfig(
+  accounts: ResolvedFeishuAccount[],
+): Required<FeishuToolsConfig> {
+  const merged: Required<FeishuToolsConfig> = {
+    doc: false,
+    chat: false,
+    wiki: false,
+    drive: false,
+    perm: false,
+    scopes: false,
+  };
+  for (const account of accounts) {
+    const cfg = resolveToolsConfig(account.config.tools);
+    merged.doc = merged.doc || cfg.doc;
+    merged.chat = merged.chat || cfg.chat;
+    merged.wiki = merged.wiki || cfg.wiki;
+    merged.drive = merged.drive || cfg.drive;
+    merged.perm = merged.perm || cfg.perm;
+    merged.scopes = merged.scopes || cfg.scopes;
+  }
+  return merged;
+}

package/src/tool-factory-test-harness.ts

@@ -0,0 +1,76 @@
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+type ToolContextLike = {
+  agentAccountId?: string;
+};
+
+type ToolFactoryLike = (ctx: ToolContextLike) => AnyAgentTool | AnyAgentTool[] | null | undefined;
+
+export type ToolLike = {
+  name: string;
+  execute: (toolCallId: string, params: unknown) => Promise<unknown> | unknown;
+};
+
+type RegisteredTool = {
+  tool: AnyAgentTool | ToolFactoryLike;
+  opts?: { name?: string };
+};
+
+function toToolList(value: AnyAgentTool | AnyAgentTool[] | null | undefined): AnyAgentTool[] {
+  if (!value) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function asToolLike(tool: AnyAgentTool, fallbackName?: string): ToolLike {
+  const candidate = tool as Partial<ToolLike>;
+  const name = candidate.name ?? fallbackName;
+  const execute = candidate.execute;
+  if (!name || typeof execute !== "function") {
+    throw new Error(`Resolved tool is missing required fields (name=${String(name)})`);
+  }
+  return {
+    name,
+    execute: (toolCallId, params) => execute(toolCallId, params),
+  };
+}
+
+export function createToolFactoryHarness(cfg: OpenClawPluginApi["config"]) {
+  const registered: RegisteredTool[] = [];
+
+  const api: Pick<OpenClawPluginApi, "config" | "logger" | "registerTool"> = {
+    config: cfg,
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+    registerTool: (tool, opts) => {
+      registered.push({ tool, opts });
+    },
+  };
+
+  const resolveTool = (name: string, ctx: ToolContextLike = {}): ToolLike => {
+    for (const entry of registered) {
+      if (entry.opts?.name === name && typeof entry.tool !== "function") {
+        return asToolLike(entry.tool, name);
+      }
+
+      if (typeof entry.tool === "function") {
+        const builtTools = toToolList(entry.tool(ctx));
+        const hit = builtTools.find((tool) => (tool as { name?: string }).name === name);
+        if (hit) {
+          return asToolLike(hit, name);
+        }
+      } else if ((entry.tool as { name?: string }).name === name) {
+        return asToolLike(entry.tool, name);
+      }
+    }
+    throw new Error(`Tool not registered: ${name}`);
+  };
+
+  return {
+    api: api as OpenClawPluginApi,
+    resolveTool,
+  };
+}