@kodelyth/feishu 2026.5.42 → 2026.6.1

package/src/typing.ts

@@ -1,214 +0,0 @@
-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

@@ -1,69 +0,0 @@
-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

@@ -1,270 +0,0 @@
-import type * as Lark from "@larksuiteoapi/node-sdk";
-import type { KlawPluginApi } 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: KlawPluginApi) {
-  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

@@ -1,31 +0,0 @@
-import type { KlawPluginApi } from "klaw/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: KlawPluginApi): 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

@@ -1,16 +0,0 @@
-{
-  "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"
-  ]
-}