@actagent/feishu 2026.6.2

package/README.md

@@ -0,0 +1,11 @@
+# ACTAgent Feishu/Lark
+
+Official ACTAgent channel plugin for Feishu and Lark workplace chats. Community maintained by @m1heng.
+
+Install from ACTAgent:
+
+```bash
+actagent plugin add @actagent/feishu
+```
+
+Configure the Feishu/Lark app credentials in ACTAgent, then connect the plugin to the chats where agents should receive and send messages.

package/actagent.plugin.json

@@ -0,0 +1,224 @@
+{
+  "id": "feishu",
+  "name": "Feishu/Lark",
+  "description": "ACTAgent Feishu/Lark channel plugin for chats and workplace tools (community maintained by @m1heng).",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["feishu"],
+  "contracts": {
+    "tools": [
+      "feishu_app_scopes",
+      "feishu_bitable_create_app",
+      "feishu_bitable_create_field",
+      "feishu_bitable_create_record",
+      "feishu_bitable_get_meta",
+      "feishu_bitable_get_record",
+      "feishu_bitable_list_fields",
+      "feishu_bitable_list_records",
+      "feishu_bitable_update_record",
+      "feishu_chat",
+      "feishu_doc",
+      "feishu_drive",
+      "feishu_perm",
+      "feishu_wiki"
+    ]
+  },
+  "toolMetadata": {
+    "feishu_app_scopes": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_bitable_create_app": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_bitable_create_field": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_bitable_create_record": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_bitable_get_meta": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_bitable_get_record": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_bitable_list_fields": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_bitable_list_records": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_bitable_update_record": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_chat": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_doc": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_drive": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_perm": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    },
+    "feishu_wiki": {
+      "configSignals": [
+        { "rootPath": "channels.feishu", "required": ["appId", "appSecret"] },
+        { "rootPath": "channels.feishu", "overlayMapPath": "accounts", "required": ["appId", "appSecret"] }
+      ]
+    }
+  },
+  "channelEnvVars": {
+    "feishu": [
+      "FEISHU_APP_ID",
+      "FEISHU_APP_SECRET",
+      "FEISHU_VERIFICATION_TOKEN",
+      "FEISHU_ENCRYPT_KEY"
+    ]
+  },
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "$defs": {
+      "secretRef": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "source": {
+            "type": "string",
+            "enum": ["env", "file", "exec"]
+          },
+          "provider": { "type": "string" },
+          "id": { "type": "string" }
+        },
+        "required": ["source", "provider", "id"]
+      },
+      "secretInput": {
+        "anyOf": [{ "type": "string", "minLength": 1 }, { "$ref": "#/$defs/secretRef" }]
+      },
+      "account": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "name": { "type": "string" },
+          "appId": { "type": "string" },
+          "appSecret": { "$ref": "#/$defs/secretInput" },
+          "encryptKey": { "$ref": "#/$defs/secretInput" },
+          "verificationToken": { "$ref": "#/$defs/secretInput" },
+          "domain": {
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": ["feishu", "lark"]
+              },
+              {
+                "type": "string",
+                "format": "uri"
+              }
+            ]
+          },
+          "connectionMode": {
+            "type": "string",
+            "enum": ["websocket", "webhook"]
+          },
+          "renderMode": {
+            "type": "string",
+            "enum": ["auto", "raw", "card"]
+          },
+          "streaming": { "type": "boolean" },
+          "blockStreaming": { "type": "boolean" },
+          "replyInThread": {
+            "type": "string",
+            "enum": ["disabled", "enabled"]
+          },
+          "typingIndicator": { "type": "boolean" }
+        }
+      }
+    },
+    "properties": {
+      "enabled": { "type": "boolean" },
+      "defaultAccount": { "type": "string" },
+      "appId": { "type": "string" },
+      "appSecret": { "$ref": "#/$defs/secretInput" },
+      "encryptKey": { "$ref": "#/$defs/secretInput" },
+      "verificationToken": { "$ref": "#/$defs/secretInput" },
+      "domain": {
+        "anyOf": [
+          {
+            "type": "string",
+            "enum": ["feishu", "lark"]
+          },
+          {
+            "type": "string",
+            "format": "uri"
+          }
+        ]
+      },
+      "connectionMode": {
+        "type": "string",
+        "enum": ["websocket", "webhook"]
+      },
+      "renderMode": {
+        "type": "string",
+        "enum": ["auto", "raw", "card"]
+      },
+      "streaming": { "type": "boolean" },
+      "blockStreaming": { "type": "boolean" },
+      "replyInThread": {
+        "type": "string",
+        "enum": ["disabled", "enabled"]
+      },
+      "typingIndicator": { "type": "boolean" },
+      "accounts": {
+        "type": "object",
+        "additionalProperties": {
+          "$ref": "#/$defs/account"
+        }
+      }
+    }
+  }
+}

package/api.ts

@@ -0,0 +1,33 @@
+// Feishu API module exposes the plugin public contract.
+export { feishuPlugin } from "./src/channel.js";
+export { registerFeishuDocTools } from "./src/docx.js";
+export { registerFeishuChatTools } from "./src/chat.js";
+export { registerFeishuWikiTools } from "./src/wiki.js";
+export { registerFeishuDriveTools } from "./src/drive.js";
+export { registerFeishuPermTools } from "./src/perm.js";
+export { registerFeishuBitableTools } from "./src/bitable.js";
+export {
+  handleFeishuSubagentDeliveryTarget,
+  handleFeishuSubagentEnded,
+  handleFeishuSubagentSpawning,
+} from "./src/subagent-hooks.js";
+export {
+  buildFeishuConversationId,
+  buildFeishuModelOverrideParentCandidates,
+  type FeishuGroupSessionScope,
+  parseFeishuConversationId,
+  parseFeishuDirectConversationId,
+  parseFeishuTargetId,
+} from "./src/conversation-id.js";
+export { feishuSetupAdapter, setFeishuNamedAccountEnabled } from "./src/setup-core.js";
+export { feishuSetupWizard, runFeishuLogin } from "./src/setup-surface.js";
+export {
+  testing as __testing,
+  testing,
+  createFeishuThreadBindingManager,
+  getFeishuThreadBindingManager,
+} from "./src/thread-bindings.js";
+export { testing as feishuThreadBindingTesting } from "./src/thread-bindings.js";
+export { createClackPrompter } from "actagent/plugin-sdk/setup-runtime";
+
+export const feishuSessionBindingAdapterChannels = ["feishu"] as const;

package/channel-entry.ts

@@ -0,0 +1,21 @@
+// Feishu plugin module implements channel entry behavior.
+import { defineBundledChannelEntry } from "actagent/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelEntry({
+  id: "feishu",
+  name: "Feishu",
+  description: "Feishu/Lark channel plugin",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./api.js",
+    exportName: "feishuPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+  runtime: {
+    specifier: "./runtime-api.js",
+    exportName: "setFeishuRuntime",
+  },
+});

package/channel-plugin-api.ts

@@ -0,0 +1,2 @@
+// Feishu API module exposes the plugin public contract.
+export { feishuPlugin } from "./src/channel.js";

package/contract-api.ts

@@ -0,0 +1,17 @@
+// Feishu API module exposes the plugin public contract.
+export { createFeishuThreadBindingManager } from "./src/thread-bindings.js";
+export { testing as feishuThreadBindingTesting } from "./src/thread-bindings.js";
+export {
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";
+export { collectFeishuSecurityAuditFindings } from "./src/security-audit.js";
+export { messageActionTargetAliases } from "./src/message-action-contract.js";
+export {
+  buildFeishuConversationId,
+  parseFeishuConversationId,
+  parseFeishuDirectConversationId,
+  parseFeishuTargetId,
+} from "./src/conversation-id.js";
+
+export const feishuSessionBindingAdapterChannels = ["feishu"] as const;

package/index.ts

@@ -0,0 +1,83 @@
+// Feishu plugin entrypoint registers its ACTAgent integration.
+import {
+  defineBundledChannelEntry,
+  loadBundledEntryExportSync,
+} from "actagent/plugin-sdk/channel-entry-contract";
+import type { ACTAgentPluginApi } from "actagent/plugin-sdk/channel-entry-contract";
+import { registerFeishuSubagentHooks } from "./subagent-hooks-api.js";
+
+function registerFeishuDocTools(api: ACTAgentPluginApi) {
+  const register = loadBundledEntryExportSync<(api: ACTAgentPluginApi) => void>(import.meta.url, {
+    specifier: "./api.js",
+    exportName: "registerFeishuDocTools",
+  });
+  register(api);
+}
+
+function registerFeishuChatTools(api: ACTAgentPluginApi) {
+  const register = loadBundledEntryExportSync<(api: ACTAgentPluginApi) => void>(import.meta.url, {
+    specifier: "./api.js",
+    exportName: "registerFeishuChatTools",
+  });
+  register(api);
+}
+
+function registerFeishuWikiTools(api: ACTAgentPluginApi) {
+  const register = loadBundledEntryExportSync<(api: ACTAgentPluginApi) => void>(import.meta.url, {
+    specifier: "./api.js",
+    exportName: "registerFeishuWikiTools",
+  });
+  register(api);
+}
+
+function registerFeishuDriveTools(api: ACTAgentPluginApi) {
+  const register = loadBundledEntryExportSync<(api: ACTAgentPluginApi) => void>(import.meta.url, {
+    specifier: "./api.js",
+    exportName: "registerFeishuDriveTools",
+  });
+  register(api);
+}
+
+function registerFeishuPermTools(api: ACTAgentPluginApi) {
+  const register = loadBundledEntryExportSync<(api: ACTAgentPluginApi) => void>(import.meta.url, {
+    specifier: "./api.js",
+    exportName: "registerFeishuPermTools",
+  });
+  register(api);
+}
+
+function registerFeishuBitableTools(api: ACTAgentPluginApi) {
+  const register = loadBundledEntryExportSync<(api: ACTAgentPluginApi) => void>(import.meta.url, {
+    specifier: "./api.js",
+    exportName: "registerFeishuBitableTools",
+  });
+  register(api);
+}
+
+export default defineBundledChannelEntry({
+  id: "feishu",
+  name: "Feishu",
+  description: "Feishu/Lark channel plugin",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "feishuPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+  runtime: {
+    specifier: "./runtime-api.js",
+    exportName: "setFeishuRuntime",
+  },
+  registerFull(api) {
+    registerFeishuSubagentHooks(api);
+    registerFeishuDocTools(api);
+    registerFeishuChatTools(api);
+    registerFeishuWikiTools(api);
+    registerFeishuDriveTools(api);
+    registerFeishuPermTools(api);
+    registerFeishuBitableTools(api);
+  },
+});

package/legacy-state-migrations-api.ts

@@ -0,0 +1,2 @@
+// Feishu API module exposes the plugin public contract.
+export { detectFeishuLegacyStateMigrations } from "./src/dedup-migrations.js";