@gakr-gakr/feishu 0.1.0

package/src/typing.ts

@@ -0,0 +1,214 @@
+import type { ClawdbotConfig, RuntimeEnv } from "../runtime-api.js";
+import { resolveFeishuRuntimeAccount } from "./accounts.js";
+import { createFeishuClient } from "./client.js";
+import { getFeishuRuntime } from "./runtime.js";
+
+// Feishu emoji types for typing indicator
+// See: https://open.feishu.cn/document/server-docs/im-v1/message-reaction/emojis-introduce
+// Full list: https://github.com/go-lark/lark/blob/main/emoji.go
+const TYPING_EMOJI = "Typing"; // Typing indicator emoji
+
+/**
+ * Feishu API error codes that indicate the caller should back off.
+ * These must propagate to the typing circuit breaker so the keepalive loop
+ * can trip and stop retrying.
+ *
+ * - 99991400: Rate limit (too many requests per second)
+ * - 99991403: Monthly API call quota exceeded
+ * - 429: Standard HTTP 429 returned as a Feishu SDK error code
+ *
+ * @see https://open.feishu.cn/document/server-docs/api-call-guide/generic-error-code
+ */
+const FEISHU_BACKOFF_CODES = new Set([99991400, 99991403, 429]);
+
+/**
+ * Custom error class for Feishu backoff conditions detected from non-throwing
+ * SDK responses. Carries a numeric `.code` so that `isFeishuBackoffError()`
+ * recognises it when the error is caught downstream.
+ */
+export class FeishuBackoffError extends Error {
+  code: number;
+  constructor(code: number) {
+    super(`Feishu API backoff: code ${code}`);
+    this.name = "FeishuBackoffError";
+    this.code = code;
+  }
+}
+
+export type TypingIndicatorState = {
+  messageId: string;
+  reactionId: string | null;
+};
+
+type FeishuMessageReactionCreateResponse = Awaited<
+  ReturnType<ReturnType<typeof createFeishuClient>["im"]["messageReaction"]["create"]>
+>;
+
+/**
+ * Check whether an error represents a rate-limit or quota-exceeded condition
+ * from the Feishu API that should stop the typing keepalive loop.
+ *
+ * Handles two shapes:
+ * 1. AxiosError with `response.status` and `response.data.code`
+ * 2. Feishu SDK error with a top-level `code` property
+ */
+export function isFeishuBackoffError(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) {
+    return false;
+  }
+
+  // AxiosError shape: err.response.status / err.response.data.code
+  const response = (err as { response?: { status?: number; data?: { code?: number } } }).response;
+  if (response) {
+    if (response.status === 429) {
+      return true;
+    }
+    if (typeof response.data?.code === "number" && FEISHU_BACKOFF_CODES.has(response.data.code)) {
+      return true;
+    }
+  }
+
+  // Feishu SDK error shape: err.code
+  const code = (err as { code?: number }).code;
+  if (typeof code === "number" && FEISHU_BACKOFF_CODES.has(code)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check whether a Feishu SDK response object contains a backoff error code.
+ *
+ * The Feishu SDK sometimes returns a normal response (no throw) with an
+ * API-level error code in the response body. This must be detected so the
+ * circuit breaker can trip. See codex review on #28157.
+ */
+export function getBackoffCodeFromResponse(response: unknown): number | undefined {
+  if (typeof response !== "object" || response === null) {
+    return undefined;
+  }
+  const code = (response as { code?: number }).code;
+  if (typeof code === "number" && FEISHU_BACKOFF_CODES.has(code)) {
+    return code;
+  }
+  return undefined;
+}
+
+/**
+ * Add a typing indicator (reaction) to a message.
+ *
+ * Rate-limit and quota errors are re-thrown so the circuit breaker in
+ * `createTypingCallbacks` (typing-start-guard) can trip and stop the
+ * keepalive loop. See #28062.
+ *
+ * Also checks for backoff codes in non-throwing SDK responses (#28157).
+ */
+export async function addTypingIndicator(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  accountId?: string;
+  runtime?: RuntimeEnv;
+}): Promise<TypingIndicatorState> {
+  const { cfg, messageId, accountId, runtime } = params;
+  const account = resolveFeishuRuntimeAccount({ cfg, accountId });
+  if (!account.configured) {
+    return { messageId, reactionId: null };
+  }
+
+  const client = createFeishuClient(account);
+
+  try {
+    const response = await client.im.messageReaction.create({
+      path: { message_id: messageId },
+      data: {
+        reaction_type: { emoji_type: TYPING_EMOJI },
+      },
+    });
+
+    // Feishu SDK may return a normal response with an API-level error code
+    // instead of throwing. Detect backoff codes and throw to trip the breaker.
+    const backoffCode = getBackoffCodeFromResponse(response);
+    if (backoffCode !== undefined) {
+      if (getFeishuRuntime().logging.shouldLogVerbose()) {
+        runtime?.log?.(
+          `[feishu] typing indicator response contains backoff code ${backoffCode}, stopping keepalive`,
+        );
+      }
+      throw new FeishuBackoffError(backoffCode);
+    }
+
+    const typedResponse: FeishuMessageReactionCreateResponse = response;
+    const reactionId = typedResponse.data?.reaction_id ?? null;
+    return { messageId, reactionId };
+  } catch (err) {
+    if (isFeishuBackoffError(err)) {
+      if (getFeishuRuntime().logging.shouldLogVerbose()) {
+        runtime?.log?.("[feishu] typing indicator hit rate-limit/quota, stopping keepalive");
+      }
+      throw err;
+    }
+    // Silently fail for other non-critical errors (e.g. message deleted, permission issues)
+    if (getFeishuRuntime().logging.shouldLogVerbose()) {
+      runtime?.log?.(`[feishu] failed to add typing indicator: ${String(err)}`);
+    }
+    return { messageId, reactionId: null };
+  }
+}
+
+/**
+ * Remove a typing indicator (reaction) from a message.
+ *
+ * Rate-limit and quota errors are re-thrown for the same reason as above.
+ */
+export async function removeTypingIndicator(params: {
+  cfg: ClawdbotConfig;
+  state: TypingIndicatorState;
+  accountId?: string;
+  runtime?: RuntimeEnv;
+}): Promise<void> {
+  const { cfg, state, accountId, runtime } = params;
+  if (!state.reactionId) {
+    return;
+  }
+
+  const account = resolveFeishuRuntimeAccount({ cfg, accountId });
+  if (!account.configured) {
+    return;
+  }
+
+  const client = createFeishuClient(account);
+
+  try {
+    const result = await client.im.messageReaction.delete({
+      path: {
+        message_id: state.messageId,
+        reaction_id: state.reactionId,
+      },
+    });
+
+    // Check for backoff codes in non-throwing SDK responses
+    const backoffCode = getBackoffCodeFromResponse(result);
+    if (backoffCode !== undefined) {
+      if (getFeishuRuntime().logging.shouldLogVerbose()) {
+        runtime?.log?.(
+          `[feishu] typing indicator removal response contains backoff code ${backoffCode}, stopping keepalive`,
+        );
+      }
+      throw new FeishuBackoffError(backoffCode);
+    }
+  } catch (err) {
+    if (isFeishuBackoffError(err)) {
+      if (getFeishuRuntime().logging.shouldLogVerbose()) {
+        runtime?.log?.(
+          "[feishu] typing indicator removal hit rate-limit/quota, stopping keepalive",
+        );
+      }
+      throw err;
+    }
+    // Silently fail for other non-critical errors
+    if (getFeishuRuntime().logging.shouldLogVerbose()) {
+      runtime?.log?.(`[feishu] failed to remove typing indicator: ${String(err)}`);
+    }
+  }
+}

package/src/wiki-schema.ts

@@ -0,0 +1,69 @@
+import { Type, type Static } from "typebox";
+
+const WIKI_SPACE_ID_DESCRIPTION =
+  "Knowledge space ID. Treat as an opaque string and keep it quoted; never pass numeric-looking IDs as numbers.";
+
+export const FeishuWikiSchema = Type.Union([
+  Type.Object({
+    action: Type.Literal("spaces"),
+  }),
+  Type.Object({
+    action: Type.Literal("nodes"),
+    space_id: Type.String({ description: WIKI_SPACE_ID_DESCRIPTION }),
+    parent_node_token: Type.Optional(
+      Type.String({ description: "Parent node token (optional, omit for root)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("get"),
+    token: Type.String({ description: "Wiki node token (from URL /wiki/XXX)" }),
+  }),
+  Type.Object({
+    action: Type.Literal("search"),
+    query: Type.String({ description: "Search query" }),
+    space_id: Type.Optional(
+      Type.String({
+        description:
+          "Limit search to this knowledge space. Treat as an opaque string and keep it quoted; never pass numeric-looking IDs as numbers.",
+      }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("create"),
+    space_id: Type.String({ description: WIKI_SPACE_ID_DESCRIPTION }),
+    title: Type.String({ description: "Node title" }),
+    obj_type: Type.Optional(
+      Type.Union([Type.Literal("docx"), Type.Literal("sheet"), Type.Literal("bitable")], {
+        description: "Object type (default: docx)",
+      }),
+    ),
+    parent_node_token: Type.Optional(
+      Type.String({ description: "Parent node token (optional, omit for root)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("move"),
+    space_id: Type.String({
+      description:
+        "Source knowledge space ID. Treat as an opaque string and keep it quoted; never pass numeric-looking IDs as numbers.",
+    }),
+    node_token: Type.String({ description: "Node token to move" }),
+    target_space_id: Type.Optional(
+      Type.String({
+        description:
+          "Target knowledge space ID (optional, same space if omitted). Treat as an opaque string and keep it quoted; never pass numeric-looking IDs as numbers.",
+      }),
+    ),
+    target_parent_token: Type.Optional(
+      Type.String({ description: "Target parent node token (optional, root if omitted)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("rename"),
+    space_id: Type.String({ description: WIKI_SPACE_ID_DESCRIPTION }),
+    node_token: Type.String({ description: "Node token to rename" }),
+    title: Type.String({ description: "New title" }),
+  }),
+]);
+
+export type FeishuWikiParams = Static<typeof FeishuWikiSchema>;

package/src/wiki.ts

@@ -0,0 +1,270 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import type { AutoBotPluginApi } from "../runtime-api.js";
+import { listEnabledFeishuAccounts } from "./accounts.js";
+import { createFeishuToolClient, resolveAnyEnabledFeishuToolsConfig } from "./tool-account.js";
+import {
+  jsonToolResult,
+  toolExecutionErrorResult,
+  unknownToolActionResult,
+} from "./tool-result.js";
+import { FeishuWikiSchema, type FeishuWikiParams } from "./wiki-schema.js";
+
+type ObjType = "doc" | "sheet" | "mindnote" | "bitable" | "file" | "docx" | "slides";
+
+// ============ Actions ============
+
+const WIKI_ACCESS_HINT =
+  "To grant wiki access: Open wiki space → Settings → Members → Add the bot. " +
+  "See: https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa#a40ad4ca";
+
+function requireWikiSpaceId(value: unknown, fieldName: string): string {
+  if (typeof value !== "string") {
+    throw new Error(
+      `${fieldName} must be a string. Feishu wiki space IDs are opaque identifiers; pass them quoted to avoid JavaScript number precision loss.`,
+    );
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error(`${fieldName} must not be empty.`);
+  }
+
+  return trimmed;
+}
+
+function optionalWikiSpaceId(value: unknown, fieldName: string): string | undefined {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  return requireWikiSpaceId(value, fieldName);
+}
+
+async function listSpaces(client: Lark.Client) {
+  const res = await client.wiki.space.list({});
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  const spaces =
+    res.data?.items?.map((s) => ({
+      space_id: s.space_id,
+      name: s.name,
+      description: s.description,
+      visibility: s.visibility,
+    })) ?? [];
+
+  return {
+    spaces,
+    ...(spaces.length === 0 && { hint: WIKI_ACCESS_HINT }),
+  };
+}
+
+async function listNodes(client: Lark.Client, spaceId: string, parentNodeToken?: string) {
+  const res = await client.wiki.spaceNode.list({
+    path: { space_id: spaceId },
+    params: { parent_node_token: parentNodeToken },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    nodes:
+      res.data?.items?.map((n) => ({
+        node_token: n.node_token,
+        obj_token: n.obj_token,
+        obj_type: n.obj_type,
+        title: n.title,
+        has_child: n.has_child,
+      })) ?? [],
+  };
+}
+
+async function getNode(client: Lark.Client, token: string) {
+  const res = await client.wiki.space.getNode({
+    params: { token },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  const node = res.data?.node;
+  return {
+    node_token: node?.node_token,
+    space_id: node?.space_id,
+    obj_token: node?.obj_token,
+    obj_type: node?.obj_type,
+    title: node?.title,
+    parent_node_token: node?.parent_node_token,
+    has_child: node?.has_child,
+    creator: node?.creator,
+    create_time: node?.node_create_time,
+  };
+}
+
+async function createNode(
+  client: Lark.Client,
+  spaceId: string,
+  title: string,
+  objType?: string,
+  parentNodeToken?: string,
+) {
+  const res = await client.wiki.spaceNode.create({
+    path: { space_id: spaceId },
+    data: {
+      obj_type: (objType as ObjType) || "docx",
+      node_type: "origin" as const,
+      title,
+      parent_node_token: parentNodeToken,
+    },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  const node = res.data?.node;
+  return {
+    node_token: node?.node_token,
+    obj_token: node?.obj_token,
+    obj_type: node?.obj_type,
+    title: node?.title,
+  };
+}
+
+async function moveNode(
+  client: Lark.Client,
+  spaceId: string,
+  nodeToken: string,
+  targetSpaceId?: string,
+  targetParentToken?: string,
+) {
+  const res = await client.wiki.spaceNode.move({
+    path: { space_id: spaceId, node_token: nodeToken },
+    data: {
+      target_space_id: targetSpaceId || spaceId,
+      target_parent_token: targetParentToken,
+    },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    success: true,
+    node_token: res.data?.node?.node_token,
+  };
+}
+
+async function renameNode(client: Lark.Client, spaceId: string, nodeToken: string, title: string) {
+  const res = await client.wiki.spaceNode.updateTitle({
+    path: { space_id: spaceId, node_token: nodeToken },
+    data: { title },
+  });
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    success: true,
+    node_token: nodeToken,
+    title,
+  };
+}
+
+// ============ Tool Registration ============
+
+export function registerFeishuWikiTools(api: AutoBotPluginApi) {
+  if (!api.config) {
+    return;
+  }
+
+  const accounts = listEnabledFeishuAccounts(api.config);
+  if (accounts.length === 0) {
+    return;
+  }
+
+  const toolsCfg = resolveAnyEnabledFeishuToolsConfig(accounts);
+  if (!toolsCfg.wiki) {
+    return;
+  }
+
+  type FeishuWikiExecuteParams = FeishuWikiParams & { accountId?: string };
+
+  api.registerTool(
+    (ctx) => {
+      const defaultAccountId = ctx.agentAccountId;
+      return {
+        name: "feishu_wiki",
+        label: "Feishu Wiki",
+        description:
+          "Feishu knowledge base operations. Actions: spaces, nodes, get, create, move, rename",
+        parameters: FeishuWikiSchema,
+        async execute(_toolCallId, params) {
+          const p = params as FeishuWikiExecuteParams;
+          try {
+            const createClient = () =>
+              createFeishuToolClient({
+                api,
+                executeParams: p,
+                defaultAccountId,
+              });
+            switch (p.action) {
+              case "spaces":
+                return jsonToolResult(await listSpaces(createClient()));
+              case "nodes": {
+                const spaceId = requireWikiSpaceId(p.space_id, "space_id");
+                return jsonToolResult(
+                  await listNodes(createClient(), spaceId, p.parent_node_token),
+                );
+              }
+              case "get":
+                return jsonToolResult(await getNode(createClient(), p.token));
+              case "search":
+                optionalWikiSpaceId(p.space_id, "space_id");
+                createClient();
+                return jsonToolResult({
+                  error:
+                    "Search is not available. Use feishu_wiki with action: 'nodes' to browse or action: 'get' to lookup by token.",
+                });
+              case "create": {
+                const spaceId = requireWikiSpaceId(p.space_id, "space_id");
+                return jsonToolResult(
+                  await createNode(
+                    createClient(),
+                    spaceId,
+                    p.title,
+                    p.obj_type,
+                    p.parent_node_token,
+                  ),
+                );
+              }
+              case "move": {
+                const spaceId = requireWikiSpaceId(p.space_id, "space_id");
+                return jsonToolResult(
+                  await moveNode(
+                    createClient(),
+                    spaceId,
+                    p.node_token,
+                    optionalWikiSpaceId(p.target_space_id, "target_space_id"),
+                    p.target_parent_token,
+                  ),
+                );
+              }
+              case "rename": {
+                const spaceId = requireWikiSpaceId(p.space_id, "space_id");
+                return jsonToolResult(
+                  await renameNode(createClient(), spaceId, p.node_token, p.title),
+                );
+              }
+              default:
+                return unknownToolActionResult((p as { action?: unknown }).action);
+            }
+          } catch (err) {
+            return toolExecutionErrorResult(err);
+          }
+        },
+      };
+    },
+    { name: "feishu_wiki" },
+  );
+}

package/subagent-hooks-api.ts

@@ -0,0 +1,31 @@
+import type { AutoBotPluginApi } from "autobot/plugin-sdk/channel-entry-contract";
+
+type FeishuSubagentHooksModule = typeof import("./src/subagent-hooks.js");
+
+let feishuSubagentHooksPromise: Promise<FeishuSubagentHooksModule> | null = null;
+
+function loadFeishuSubagentHooksModule() {
+  feishuSubagentHooksPromise ??= import("./src/subagent-hooks.js");
+  return feishuSubagentHooksPromise;
+}
+
+export function registerFeishuSubagentHooks(api: AutoBotPluginApi): void {
+  api.on("subagent_spawning", async (event, ctx) => {
+    const { handleFeishuSubagentSpawning } = await loadFeishuSubagentHooksModule();
+    return await handleFeishuSubagentSpawning(event, ctx);
+  });
+  api.on("subagent_delivery_target", async (event) => {
+    const { handleFeishuSubagentDeliveryTarget } = await loadFeishuSubagentHooksModule();
+    return handleFeishuSubagentDeliveryTarget(event);
+  });
+  api.on("subagent_ended", async (event) => {
+    const { handleFeishuSubagentEnded } = await loadFeishuSubagentHooksModule();
+    handleFeishuSubagentEnded(event);
+  });
+}
+
+export {
+  handleFeishuSubagentDeliveryTarget,
+  handleFeishuSubagentEnded,
+  handleFeishuSubagentSpawning,
+} from "./src/subagent-hooks.js";

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}