@gakr-gakr/feishu 0.1.0

package/src/thread-bindings.ts

@@ -0,0 +1,331 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import {
+  resolveThreadBindingIdleTimeoutMsForChannel,
+  resolveThreadBindingMaxAgeMsForChannel,
+  registerSessionBindingAdapter,
+  resolveThreadBindingConversationIdFromBindingId,
+  unregisterSessionBindingAdapter,
+  type BindingTargetKind,
+  type SessionBindingAdapter,
+  type SessionBindingRecord,
+} from "autobot/plugin-sdk/conversation-runtime";
+import { normalizeAccountId, resolveAgentIdFromSessionKey } from "autobot/plugin-sdk/routing";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+
+type FeishuBindingTargetKind = "subagent" | "acp";
+
+type FeishuThreadBindingRecord = {
+  accountId: string;
+  conversationId: string;
+  parentConversationId?: string;
+  deliveryTo?: string;
+  deliveryThreadId?: string;
+  targetKind: FeishuBindingTargetKind;
+  targetSessionKey: string;
+  agentId?: string;
+  label?: string;
+  boundBy?: string;
+  boundAt: number;
+  lastActivityAt: number;
+};
+
+type FeishuThreadBindingManager = {
+  accountId: string;
+  getByConversationId: (conversationId: string) => FeishuThreadBindingRecord | undefined;
+  listBySessionKey: (targetSessionKey: string) => FeishuThreadBindingRecord[];
+  bindConversation: (params: {
+    conversationId: string;
+    parentConversationId?: string;
+    targetKind: BindingTargetKind;
+    targetSessionKey: string;
+    metadata?: Record<string, unknown>;
+  }) => FeishuThreadBindingRecord | null;
+  touchConversation: (conversationId: string, at?: number) => FeishuThreadBindingRecord | null;
+  unbindConversation: (conversationId: string) => FeishuThreadBindingRecord | null;
+  unbindBySessionKey: (targetSessionKey: string) => FeishuThreadBindingRecord[];
+  stop: () => void;
+};
+
+type FeishuThreadBindingsState = {
+  managersByAccountId: Map<string, FeishuThreadBindingManager>;
+  bindingsByAccountConversation: Map<string, FeishuThreadBindingRecord>;
+};
+
+const FEISHU_THREAD_BINDINGS_STATE_KEY = Symbol.for("autobot.feishuThreadBindingsState");
+let state: FeishuThreadBindingsState | undefined;
+
+function getState(): FeishuThreadBindingsState {
+  if (!state) {
+    const globalStore = globalThis as Record<PropertyKey, unknown>;
+    state = (globalStore[FEISHU_THREAD_BINDINGS_STATE_KEY] as
+      | FeishuThreadBindingsState
+      | undefined) ?? {
+      managersByAccountId: new Map(),
+      bindingsByAccountConversation: new Map(),
+    };
+    globalStore[FEISHU_THREAD_BINDINGS_STATE_KEY] = state;
+  }
+  return state;
+}
+
+function resolveBindingKey(params: { accountId: string; conversationId: string }): string {
+  return `${params.accountId}:${params.conversationId}`;
+}
+
+function toSessionBindingTargetKind(raw: FeishuBindingTargetKind): BindingTargetKind {
+  return raw === "subagent" ? "subagent" : "session";
+}
+
+function toFeishuTargetKind(raw: BindingTargetKind): FeishuBindingTargetKind {
+  return raw === "subagent" ? "subagent" : "acp";
+}
+
+function toSessionBindingRecord(
+  record: FeishuThreadBindingRecord,
+  defaults: { idleTimeoutMs: number; maxAgeMs: number },
+): SessionBindingRecord {
+  const idleExpiresAt =
+    defaults.idleTimeoutMs > 0 ? record.lastActivityAt + defaults.idleTimeoutMs : undefined;
+  const maxAgeExpiresAt = defaults.maxAgeMs > 0 ? record.boundAt + defaults.maxAgeMs : undefined;
+  const expiresAt =
+    idleExpiresAt != null && maxAgeExpiresAt != null
+      ? Math.min(idleExpiresAt, maxAgeExpiresAt)
+      : (idleExpiresAt ?? maxAgeExpiresAt);
+  return {
+    bindingId: resolveBindingKey({
+      accountId: record.accountId,
+      conversationId: record.conversationId,
+    }),
+    targetSessionKey: record.targetSessionKey,
+    targetKind: toSessionBindingTargetKind(record.targetKind),
+    conversation: {
+      channel: "feishu",
+      accountId: record.accountId,
+      conversationId: record.conversationId,
+      parentConversationId: record.parentConversationId,
+    },
+    status: "active",
+    boundAt: record.boundAt,
+    expiresAt,
+    metadata: {
+      agentId: record.agentId,
+      label: record.label,
+      boundBy: record.boundBy,
+      deliveryTo: record.deliveryTo,
+      deliveryThreadId: record.deliveryThreadId,
+      lastActivityAt: record.lastActivityAt,
+      idleTimeoutMs: defaults.idleTimeoutMs,
+      maxAgeMs: defaults.maxAgeMs,
+    },
+  };
+}
+
+export function createFeishuThreadBindingManager(params: {
+  accountId?: string;
+  cfg: AutoBotConfig;
+}): FeishuThreadBindingManager {
+  const accountId = normalizeAccountId(params.accountId);
+  const existing = getState().managersByAccountId.get(accountId);
+  if (existing) {
+    return existing;
+  }
+
+  const idleTimeoutMs = resolveThreadBindingIdleTimeoutMsForChannel({
+    cfg: params.cfg,
+    channel: "feishu",
+    accountId,
+  });
+  const maxAgeMs = resolveThreadBindingMaxAgeMsForChannel({
+    cfg: params.cfg,
+    channel: "feishu",
+    accountId,
+  });
+
+  const manager: FeishuThreadBindingManager = {
+    accountId,
+    getByConversationId: (conversationId) =>
+      getState().bindingsByAccountConversation.get(
+        resolveBindingKey({ accountId, conversationId }),
+      ),
+    listBySessionKey: (targetSessionKey) =>
+      [...getState().bindingsByAccountConversation.values()].filter(
+        (record) => record.accountId === accountId && record.targetSessionKey === targetSessionKey,
+      ),
+    bindConversation: ({
+      conversationId,
+      parentConversationId,
+      targetKind,
+      targetSessionKey,
+      metadata,
+    }) => {
+      const normalizedConversationId = conversationId.trim();
+      const normalizedTargetSessionKey = targetSessionKey.trim();
+      if (!normalizedConversationId || !normalizedTargetSessionKey) {
+        return null;
+      }
+      const existing = getState().bindingsByAccountConversation.get(
+        resolveBindingKey({ accountId, conversationId: normalizedConversationId }),
+      );
+      const now = Date.now();
+      const record: FeishuThreadBindingRecord = {
+        accountId,
+        conversationId: normalizedConversationId,
+        parentConversationId:
+          normalizeOptionalString(parentConversationId) ?? existing?.parentConversationId,
+        deliveryTo:
+          typeof metadata?.deliveryTo === "string" && metadata.deliveryTo.trim()
+            ? metadata.deliveryTo.trim()
+            : existing?.deliveryTo,
+        deliveryThreadId:
+          typeof metadata?.deliveryThreadId === "string" && metadata.deliveryThreadId.trim()
+            ? metadata.deliveryThreadId.trim()
+            : existing?.deliveryThreadId,
+        targetKind: toFeishuTargetKind(targetKind),
+        targetSessionKey: normalizedTargetSessionKey,
+        agentId:
+          typeof metadata?.agentId === "string" && metadata.agentId.trim()
+            ? metadata.agentId.trim()
+            : (existing?.agentId ?? resolveAgentIdFromSessionKey(normalizedTargetSessionKey)),
+        label:
+          typeof metadata?.label === "string" && metadata.label.trim()
+            ? metadata.label.trim()
+            : existing?.label,
+        boundBy:
+          typeof metadata?.boundBy === "string" && metadata.boundBy.trim()
+            ? metadata.boundBy.trim()
+            : existing?.boundBy,
+        boundAt: now,
+        lastActivityAt: now,
+      };
+      getState().bindingsByAccountConversation.set(
+        resolveBindingKey({ accountId, conversationId: normalizedConversationId }),
+        record,
+      );
+      return record;
+    },
+    touchConversation: (conversationId, at = Date.now()) => {
+      const key = resolveBindingKey({ accountId, conversationId });
+      const existingRecord = getState().bindingsByAccountConversation.get(key);
+      if (!existingRecord) {
+        return null;
+      }
+      const updated = { ...existingRecord, lastActivityAt: at };
+      getState().bindingsByAccountConversation.set(key, updated);
+      return updated;
+    },
+    unbindConversation: (conversationId) => {
+      const key = resolveBindingKey({ accountId, conversationId });
+      const existingRecord = getState().bindingsByAccountConversation.get(key);
+      if (!existingRecord) {
+        return null;
+      }
+      getState().bindingsByAccountConversation.delete(key);
+      return existingRecord;
+    },
+    unbindBySessionKey: (targetSessionKey) => {
+      const removed: FeishuThreadBindingRecord[] = [];
+      for (const record of getState().bindingsByAccountConversation.values()) {
+        if (record.accountId !== accountId || record.targetSessionKey !== targetSessionKey) {
+          continue;
+        }
+        getState().bindingsByAccountConversation.delete(
+          resolveBindingKey({ accountId, conversationId: record.conversationId }),
+        );
+        removed.push(record);
+      }
+      return removed;
+    },
+    stop: () => {
+      for (const key of getState().bindingsByAccountConversation.keys()) {
+        if (key.startsWith(`${accountId}:`)) {
+          getState().bindingsByAccountConversation.delete(key);
+        }
+      }
+      getState().managersByAccountId.delete(accountId);
+      unregisterSessionBindingAdapter({
+        channel: "feishu",
+        accountId,
+        adapter: sessionBindingAdapter,
+      });
+    },
+  };
+
+  const sessionBindingAdapter: SessionBindingAdapter = {
+    channel: "feishu",
+    accountId,
+    capabilities: {
+      placements: ["current"],
+    },
+    bind: async (input) => {
+      if (input.conversation.channel !== "feishu" || input.placement === "child") {
+        return null;
+      }
+      const bound = manager.bindConversation({
+        conversationId: input.conversation.conversationId,
+        parentConversationId: input.conversation.parentConversationId,
+        targetKind: input.targetKind,
+        targetSessionKey: input.targetSessionKey,
+        metadata: input.metadata,
+      });
+      return bound ? toSessionBindingRecord(bound, { idleTimeoutMs, maxAgeMs }) : null;
+    },
+    listBySession: (targetSessionKey) =>
+      manager
+        .listBySessionKey(targetSessionKey)
+        .map((entry) => toSessionBindingRecord(entry, { idleTimeoutMs, maxAgeMs })),
+    resolveByConversation: (ref) => {
+      if (ref.channel !== "feishu") {
+        return null;
+      }
+      const found = manager.getByConversationId(ref.conversationId);
+      return found ? toSessionBindingRecord(found, { idleTimeoutMs, maxAgeMs }) : null;
+    },
+    touch: (bindingId, at) => {
+      const conversationId = resolveThreadBindingConversationIdFromBindingId({
+        accountId,
+        bindingId,
+      });
+      if (conversationId) {
+        manager.touchConversation(conversationId, at);
+      }
+    },
+    unbind: async (input) => {
+      if (input.targetSessionKey?.trim()) {
+        return manager
+          .unbindBySessionKey(input.targetSessionKey.trim())
+          .map((entry) => toSessionBindingRecord(entry, { idleTimeoutMs, maxAgeMs }));
+      }
+      const conversationId = resolveThreadBindingConversationIdFromBindingId({
+        accountId,
+        bindingId: input.bindingId,
+      });
+      if (!conversationId) {
+        return [];
+      }
+      const removed = manager.unbindConversation(conversationId);
+      return removed ? [toSessionBindingRecord(removed, { idleTimeoutMs, maxAgeMs })] : [];
+    },
+  };
+
+  registerSessionBindingAdapter(sessionBindingAdapter);
+
+  getState().managersByAccountId.set(accountId, manager);
+  return manager;
+}
+
+export function getFeishuThreadBindingManager(
+  accountId?: string,
+): FeishuThreadBindingManager | null {
+  return getState().managersByAccountId.get(normalizeAccountId(accountId)) ?? null;
+}
+
+export const testing = {
+  resetFeishuThreadBindingsForTests() {
+    for (const manager of getState().managersByAccountId.values()) {
+      manager.stop();
+    }
+    getState().managersByAccountId.clear();
+    getState().bindingsByAccountConversation.clear();
+  },
+};
+export { testing as __testing };

package/src/tool-account.ts

@@ -0,0 +1,93 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import type { AutoBotPluginApi } from "../runtime-api.js";
+import {
+  listFeishuAccountIds,
+  resolveFeishuAccount,
+  resolveFeishuRuntimeAccount,
+} 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 resolveImplicitToolAccountId(params: {
+  api: Pick<AutoBotPluginApi, "config">;
+  executeParams?: AccountAwareParams;
+  defaultAccountId?: string;
+}): string | undefined {
+  const explicitAccountId = normalizeOptionalString(params.executeParams?.accountId);
+  if (explicitAccountId) {
+    return explicitAccountId;
+  }
+
+  const contextualAccountId = normalizeOptionalString(params.defaultAccountId);
+  if (
+    contextualAccountId &&
+    listFeishuAccountIds(params.api.config).includes(contextualAccountId)
+  ) {
+    const contextualAccount = resolveFeishuAccount({
+      cfg: params.api.config,
+      accountId: contextualAccountId,
+    });
+    if (contextualAccount.enabled) {
+      return contextualAccountId;
+    }
+  }
+
+  const configuredDefaultAccountId = normalizeOptionalString(
+    (params.api.config?.channels?.feishu as { defaultAccount?: unknown } | undefined)
+      ?.defaultAccount,
+  );
+  if (configuredDefaultAccountId) {
+    return configuredDefaultAccountId;
+  }
+
+  return undefined;
+}
+
+export function resolveFeishuToolAccount(params: {
+  api: Pick<AutoBotPluginApi, "config">;
+  executeParams?: AccountAwareParams;
+  defaultAccountId?: string;
+}): ResolvedFeishuAccount {
+  if (!params.api.config) {
+    throw new Error("Feishu config unavailable");
+  }
+  return resolveFeishuRuntimeAccount({
+    cfg: params.api.config,
+    accountId: resolveImplicitToolAccountId(params),
+  });
+}
+
+export function createFeishuToolClient(params: {
+  api: Pick<AutoBotPluginApi, "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,79 @@
+import type { AutoBotPluginApi } from "../runtime-api.js";
+
+type ToolContextLike = {
+  agentAccountId?: string;
+};
+
+export type ToolLike = {
+  name: string;
+  execute: (
+    toolCallId: string,
+    params: unknown,
+  ) => Promise<{ details: Record<string, unknown> }> | { details: Record<string, unknown> };
+};
+
+type RegisteredTool = {
+  tool: unknown;
+  opts?: { name?: string };
+};
+
+function toToolList(value: unknown): unknown[] {
+  if (!value) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+function asToolLike(tool: unknown, 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: AutoBotPluginApi["config"]) {
+  const registered: RegisteredTool[] = [];
+
+  const api: Pick<AutoBotPluginApi, "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 AutoBotPluginApi,
+    resolveTool,
+  };
+}

package/src/tool-result.ts

@@ -0,0 +1,16 @@
+import { formatErrorMessage } from "autobot/plugin-sdk/error-runtime";
+
+export function jsonToolResult(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+export function unknownToolActionResult(action: unknown) {
+  return jsonToolResult({ error: `Unknown action: ${String(action)}` });
+}
+
+export function toolExecutionErrorResult(error: unknown) {
+  return jsonToolResult({ error: formatErrorMessage(error) });
+}

package/src/tools-config.ts

@@ -0,0 +1,22 @@
+import type { FeishuToolsConfig } from "./types.js";
+
+/**
+ * Default tool configuration.
+ * - doc, chat, wiki, drive, scopes: enabled by default
+ * - perm: disabled by default (sensitive operation)
+ */
+const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
+  doc: true,
+  chat: true,
+  wiki: true,
+  drive: true,
+  perm: false,
+  scopes: true,
+};
+
+/**
+ * Resolve tools config with defaults.
+ */
+export function resolveToolsConfig(cfg?: FeishuToolsConfig): Required<FeishuToolsConfig> {
+  return { ...DEFAULT_TOOLS_CONFIG, ...cfg };
+}

package/src/types.ts

@@ -0,0 +1,106 @@
+import type { MessageReceipt } from "autobot/plugin-sdk/channel-message";
+import type { BaseProbeResult } from "autobot/plugin-sdk/core";
+import type { FeishuConfigSchema, FeishuAccountConfigSchema, z } from "./config-schema.js";
+import type { MentionTarget } from "./mention-target.types.js";
+
+export type FeishuConfig = z.infer<typeof FeishuConfigSchema>;
+export type FeishuAccountConfig = z.infer<typeof FeishuAccountConfigSchema>;
+
+export type FeishuDomain = "feishu" | "lark" | (string & {});
+
+export type FeishuDefaultAccountSelectionSource =
+  | "explicit-default"
+  | "mapped-default"
+  | "fallback";
+type FeishuAccountSelectionSource = "explicit" | FeishuDefaultAccountSelectionSource;
+
+export type ResolvedFeishuAccount = {
+  accountId: string;
+  selectionSource: FeishuAccountSelectionSource;
+  enabled: boolean;
+  configured: boolean;
+  name?: string;
+  appId?: string;
+  appSecret?: string;
+  encryptKey?: string;
+  verificationToken?: string;
+  domain: FeishuDomain;
+  /** Merged config (top-level defaults + account-specific overrides) */
+  config: FeishuConfig;
+};
+
+export type FeishuIdType = "open_id" | "user_id" | "union_id" | "chat_id";
+
+export type FeishuMessageContext = {
+  chatId: string;
+  messageId: string;
+  replyTargetMessageId?: string;
+  suppressReplyTarget?: boolean;
+  senderId: string;
+  senderOpenId: string;
+  senderName?: string;
+  chatType: FeishuChatType;
+  mentionedBot: boolean;
+  hasAnyMention?: boolean;
+  rootId?: string;
+  parentId?: string;
+  threadId?: string;
+  content: string;
+  contentType: string;
+  /** Mention forward targets (excluding the bot itself) */
+  mentionTargets?: MentionTarget[];
+};
+
+export type FeishuSendResult = {
+  messageId: string;
+  chatId: string;
+  receipt: MessageReceipt;
+};
+
+export type FeishuChatType = "p2p" | "group" | "topic_group" | "private";
+
+export function isFeishuGroupChatType(chatType: FeishuChatType | undefined): boolean {
+  return chatType === "group" || chatType === "topic_group";
+}
+
+export type FeishuMessageInfo = {
+  messageId: string;
+  chatId: string;
+  chatType?: FeishuChatType;
+  senderId?: string;
+  senderOpenId?: string;
+  senderType?: string;
+  content: string;
+  contentType: string;
+  createTime?: number;
+  /** Feishu thread ID (omt_xxx) — present when the message belongs to a topic thread. */
+  threadId?: string;
+};
+
+export interface FeishuProbeResult extends BaseProbeResult {
+  appId?: string;
+  botName?: string;
+  botOpenId?: string;
+}
+
+export type FeishuMediaInfo = {
+  path: string;
+  contentType?: string;
+  placeholder: string;
+};
+
+export type FeishuToolsConfig = {
+  doc?: boolean;
+  chat?: boolean;
+  wiki?: boolean;
+  drive?: boolean;
+  perm?: boolean;
+  scopes?: boolean;
+};
+
+export type DynamicAgentCreationConfig = {
+  enabled?: boolean;
+  workspaceTemplate?: string;
+  agentDirTemplate?: string;
+  maxAgents?: number;
+};