@m1heng-clawd/feishu 0.1.14 → 0.1.16

package/src/task-tools/actions.ts

@@ -3,26 +3,33 @@ import os from "node:os";
 import path from "node:path";
 import type { TaskClient } from "./common.js";
 import {
+  TASK_COMMENT_UPDATE_FIELD_VALUES,
   TASKLIST_UPDATE_FIELD_VALUES,
   TASK_UPDATE_FIELD_VALUES,
   type AddTaskToTasklistParams,
   type AddTasklistMembersParams,
+  type CreateTaskCommentParams,
   type CreateTasklistParams,
-  CreateSubtaskParams,
-  CreateTaskParams,
-  DeleteTaskAttachmentParams,
-  GetTaskAttachmentParams,
-  GetTaskParams,
+  type CreateSubtaskParams,
+  type CreateTaskParams,
+  type DeleteTaskAttachmentParams,
+  type DeleteTaskCommentParams,
+  type GetTaskAttachmentParams,
+  type GetTaskCommentParams,
+  type GetTaskParams,
   type GetTasklistParams,
-  ListTaskAttachmentsParams,
+  type ListTaskAttachmentsParams,
+  type ListTaskCommentsParams,
   type ListTasklistsParams,
   type RemoveTaskFromTasklistParams,
   type RemoveTasklistMembersParams,
-  TaskUpdateTask,
+  type TaskCommentPatchComment,
+  type TaskUpdateTask,
   type TasklistPatchTasklist,
-  UploadTaskAttachmentParams,
+  type UploadTaskAttachmentParams,
+  type UpdateTaskCommentParams,
   type UpdateTasklistParams,
-  UpdateTaskParams,
+  type UpdateTaskParams,
 } from "./schemas.js";
 import {
   DEFAULT_TASK_ATTACHMENT_FILENAME,
@@ -36,6 +43,7 @@ import { getFeishuRuntime } from "../runtime.js";
 import { runTaskApiCall } from "./common.js";
 
 const SUPPORTED_PATCH_FIELDS = new Set<string>(TASK_UPDATE_FIELD_VALUES);
+const SUPPORTED_COMMENT_PATCH_FIELDS = new Set<string>(TASK_COMMENT_UPDATE_FIELD_VALUES);
 const SUPPORTED_TASKLIST_PATCH_FIELDS = new Set<string>(TASKLIST_UPDATE_FIELD_VALUES);
 
 function omitUndefined<T extends Record<string, unknown>>(obj: T): T {
@@ -50,10 +58,16 @@ function inferUpdateFields(task: TaskUpdateTask): string[] {
   );
 }
 
+function inferCommentUpdateFields(comment: TaskCommentPatchComment): string[] {
+  return Object.keys(comment).filter((field) =>
+    SUPPORTED_COMMENT_PATCH_FIELDS.has(field),
+  );
+}
+
 function ensureSupportedUpdateFields(
   updateFields: string[],
   supported: Set<string>,
-  resource: "task" | "tasklist",
+  resource: "task" | "comment" | "tasklist",
 ) {
   const invalid = updateFields.filter((field) => !supported.has(field));
   if (invalid.length > 0) {
@@ -102,6 +116,20 @@ function formatTasklist(tasklist: Record<string, unknown> | undefined) {
   };
 }
 
+function formatComment(comment: Record<string, unknown> | undefined) {
+  if (!comment) return undefined;
+  return {
+    id: comment.id,
+    content: comment.content,
+    creator: comment.creator,
+    reply_to_comment_id: comment.reply_to_comment_id,
+    created_at: comment.created_at,
+    updated_at: comment.updated_at,
+    resource_type: comment.resource_type,
+    resource_id: comment.resource_id,
+  };
+}
+
 function formatAttachment(attachment: Record<string, unknown> | undefined) {
   if (!attachment) return undefined;
   return {
@@ -307,6 +335,113 @@ export async function getTask(client: TaskClient, params: GetTaskParams) {
   };
 }
 
+export async function createTaskComment(client: TaskClient, params: CreateTaskCommentParams) {
+  const res = await runTaskApiCall("task.v2.comment.create", () =>
+    client.task.v2.comment.create({
+      data: omitUndefined({
+        content: params.content,
+        reply_to_comment_id: params.reply_to_comment_id,
+        resource_type: "task",
+        resource_id: params.task_guid,
+      }),
+      params: omitUndefined({
+        user_id_type: params.user_id_type,
+      }),
+    }),
+  );
+
+  return {
+    comment: formatComment((res.data?.comment ?? undefined) as Record<string, unknown> | undefined),
+  };
+}
+
+export async function listTaskComments(client: TaskClient, params: ListTaskCommentsParams) {
+  const res = await runTaskApiCall("task.v2.comment.list", () =>
+    client.task.v2.comment.list({
+      params: omitUndefined({
+        resource_type: "task",
+        resource_id: params.task_guid,
+        page_size: params.page_size,
+        page_token: params.page_token,
+        direction: params.direction,
+        user_id_type: params.user_id_type,
+      }),
+    }),
+  );
+
+  const items = (res.data?.items ?? []) as Record<string, unknown>[];
+
+  return {
+    items: items.map((item) => formatComment(item)),
+    page_token: res.data?.page_token,
+    has_more: res.data?.has_more,
+  };
+}
+
+export async function getTaskComment(client: TaskClient, params: GetTaskCommentParams) {
+  const res = await runTaskApiCall("task.v2.comment.get", () =>
+    client.task.v2.comment.get({
+      path: { comment_id: params.comment_id },
+      params: omitUndefined({
+        user_id_type: params.user_id_type,
+      }),
+    }),
+  );
+
+  return {
+    comment: formatComment((res.data?.comment ?? undefined) as Record<string, unknown> | undefined),
+  };
+}
+
+export async function updateTaskComment(client: TaskClient, params: UpdateTaskCommentParams) {
+  const comment = omitUndefined(params.comment as Record<string, unknown>) as TaskCommentPatchComment;
+  const updateFields = params.update_fields?.length
+    ? params.update_fields
+    : inferCommentUpdateFields(comment);
+
+  if (params.update_fields?.length) {
+    ensureSupportedUpdateFields(updateFields, SUPPORTED_COMMENT_PATCH_FIELDS, "comment");
+  }
+
+  if (Object.keys(comment).length === 0) {
+    throw new Error("comment update payload is empty");
+  }
+  if (updateFields.length === 0) {
+    throw new Error("no valid update_fields provided or inferred from comment payload");
+  }
+
+  const res = await runTaskApiCall("task.v2.comment.patch", () =>
+    client.task.v2.comment.patch({
+      path: { comment_id: params.comment_id },
+      data: {
+        comment,
+        update_fields: updateFields,
+      },
+      params: omitUndefined({
+        user_id_type: params.user_id_type,
+      }),
+    }),
+  );
+
+  return {
+    comment: formatComment((res.data?.comment ?? undefined) as Record<string, unknown> | undefined),
+    update_fields: updateFields,
+  };
+}
+
+export async function deleteTaskComment(client: TaskClient, params: DeleteTaskCommentParams) {
+  await runTaskApiCall("task.v2.comment.delete", () =>
+    client.task.v2.comment.delete({
+      path: { comment_id: params.comment_id },
+    }),
+  );
+
+  return {
+    success: true,
+    comment_id: params.comment_id,
+  };
+}
+
 export async function getTasklist(client: TaskClient, params: GetTasklistParams) {
   const res = await runTaskApiCall("task.v2.tasklist.get", () =>
     client.task.v2.tasklist.get({

package/src/task-tools/register.ts

@@ -6,19 +6,24 @@ import {
   addTaskToTasklist,
   addTasklistMembers,
   createSubtask,
+  createTaskComment,
   createTask,
   createTasklist,
   deleteTaskAttachment,
+  deleteTaskComment,
   deleteTask,
   deleteTasklist,
   getTaskAttachment,
+  getTaskComment,
   getTask,
   getTasklist,
+  listTaskComments,
   listTasklists,
   removeTaskFromTasklist,
   removeTasklistMembers,
   listTaskAttachments,
   uploadTaskAttachment,
+  updateTaskComment,
   updateTask,
   updateTasklist,
 } from "./actions.js";
@@ -36,26 +41,36 @@ import {
   type CreateTasklistParams,
   DeleteTaskAttachmentSchema,
   type DeleteTaskAttachmentParams,
+  DeleteTaskCommentSchema,
+  type DeleteTaskCommentParams,
   DeleteTaskSchema,
   type DeleteTaskParams,
   DeleteTasklistSchema,
   type DeleteTasklistParams,
   GetTaskAttachmentSchema,
   type GetTaskAttachmentParams,
+  GetTaskCommentSchema,
+  type GetTaskCommentParams,
   GetTaskSchema,
   type GetTaskParams,
   GetTasklistSchema,
   type GetTasklistParams,
   ListTaskAttachmentsSchema,
   type ListTaskAttachmentsParams,
+  ListTaskCommentsSchema,
+  type ListTaskCommentsParams,
   ListTasklistsSchema,
   type ListTasklistsParams,
   RemoveTaskFromTasklistSchema,
   type RemoveTaskFromTasklistParams,
   RemoveTasklistMembersSchema,
   type RemoveTasklistMembersParams,
+  CreateTaskCommentSchema,
+  type CreateTaskCommentParams,
   UploadTaskAttachmentSchema,
   type UploadTaskAttachmentParams,
+  UpdateTaskCommentSchema,
+  type UpdateTaskCommentParams,
   UpdateTaskSchema,
   UpdateTasklistSchema,
   type UpdateTaskParams,
@@ -259,5 +274,45 @@ export function registerFeishuTaskTools(api: OpenClawPluginApi) {
     run: async ({ client }, params) => updateTask(client, params),
   });
 
-  api.logger.debug?.("feishu_task: Registered task, tasklist, subtask, and attachment tools");
+  registerTaskTool<CreateTaskCommentParams>(api, {
+    name: "feishu_task_comment_create",
+    label: "Feishu Task Comment Create",
+    description: "Create a comment on a Feishu task (task v2)",
+    parameters: CreateTaskCommentSchema,
+    run: async ({ client }, params) => createTaskComment(client, params),
+  });
+
+  registerTaskTool<ListTaskCommentsParams>(api, {
+    name: "feishu_task_comment_list",
+    label: "Feishu Task Comment List",
+    description: "List comments for a Feishu task (task v2)",
+    parameters: ListTaskCommentsSchema,
+    run: async ({ client }, params) => listTaskComments(client, params),
+  });
+
+  registerTaskTool<GetTaskCommentParams>(api, {
+    name: "feishu_task_comment_get",
+    label: "Feishu Task Comment Get",
+    description: "Get a Feishu task comment by comment_id (task v2)",
+    parameters: GetTaskCommentSchema,
+    run: async ({ client }, params) => getTaskComment(client, params),
+  });
+
+  registerTaskTool<UpdateTaskCommentParams>(api, {
+    name: "feishu_task_comment_update",
+    label: "Feishu Task Comment Update",
+    description: "Update a Feishu task comment by comment_id (task v2 patch)",
+    parameters: UpdateTaskCommentSchema,
+    run: async ({ client }, params) => updateTaskComment(client, params),
+  });
+
+  registerTaskTool<DeleteTaskCommentParams>(api, {
+    name: "feishu_task_comment_delete",
+    label: "Feishu Task Comment Delete",
+    description: "Delete a Feishu task comment by comment_id (task v2)",
+    parameters: DeleteTaskCommentSchema,
+    run: async ({ client }, params) => deleteTaskComment(client, params),
+  });
+
+  api.logger.debug?.("feishu_task: Registered task, comment, tasklist, subtask, and attachment tools");
 }

package/src/task-tools/schemas.ts

@@ -1,6 +1,15 @@
 import { Type } from "@sinclair/typebox";
 import type { TaskClient } from "./common.js";
 
+// NOTE: Avoid Type.Union([Type.Literal(...)]) which compiles to anyOf.
+// Some providers reject anyOf in tool schemas; a flat string enum is safer.
+function stringEnum<T extends readonly string[]>(
+  values: T,
+  options: { description?: string; default?: T[number] } = {},
+) {
+  return Type.Unsafe<T[number]>({ type: "string", enum: [...values], ...options });
+}
+
 type TaskCreatePayload = NonNullable<Parameters<TaskClient["task"]["v2"]["task"]["create"]>[0]>;
 type TaskUpdatePayload = NonNullable<Parameters<TaskClient["task"]["v2"]["task"]["patch"]>[0]>;
 type TaskDeletePayload = NonNullable<Parameters<TaskClient["task"]["v2"]["task"]["delete"]>[0]>;
@@ -75,6 +84,7 @@ export const TASK_UPDATE_FIELD_VALUES = [
   "mode",
   "is_milestone",
 ] as const;
+export const TASK_COMMENT_UPDATE_FIELD_VALUES = ["content"] as const;
 export const TASKLIST_UPDATE_FIELD_VALUES = ["name", "owner", "archive_tasklist"] as const;
 
 export type CreateTaskParams = {
@@ -245,23 +255,19 @@ const TasklistRefSchema = Type.Object({
   section_guid: Type.Optional(Type.String({ description: "Section GUID in tasklist" })),
 });
 
-const TaskUpdateFieldSchema = Type.Union(
-  TASK_UPDATE_FIELD_VALUES.map((field) => Type.Literal(field)),
-);
+const TaskUpdateFieldSchema = stringEnum(TASK_UPDATE_FIELD_VALUES);
 
-const TasklistMemberRoleSchema = Type.Union(
-  [Type.Literal("owner"), Type.Literal("editor"), Type.Literal("viewer")],
-  { description: "Member role (owner/editor/viewer)" },
-);
+const TaskCommentUpdateFieldSchema = stringEnum(TASK_COMMENT_UPDATE_FIELD_VALUES);
 
-const TasklistUpdateFieldSchema = Type.Union(
-  TASKLIST_UPDATE_FIELD_VALUES.map((field) => Type.Literal(field)),
-);
+const TasklistMemberRoleSchema = stringEnum(["owner", "editor", "viewer"] as const, {
+  description: "Member role (owner/editor/viewer)",
+});
 
-const TasklistOriginOwnerRoleSchema = Type.Union(
-  [Type.Literal("editor"), Type.Literal("viewer"), Type.Literal("none")],
-  { description: "Role for original owner after owner transfer" },
-);
+const TasklistUpdateFieldSchema = stringEnum(TASKLIST_UPDATE_FIELD_VALUES);
+
+const TasklistOriginOwnerRoleSchema = stringEnum(["editor", "viewer", "none"] as const, {
+  description: "Role for original owner after owner transfer",
+});
 
 const TasklistMemberSchema = Type.Object({
   id: Type.String({ description: "Member ID (with type controlled by user_id_type)" }),
@@ -372,9 +378,7 @@ export const ListTaskCommentsSchema = Type.Object({
   ),
   page_token: Type.Optional(Type.String({ description: "Pagination token" })),
   direction: Type.Optional(
-    Type.Union([Type.Literal("asc"), Type.Literal("desc")], {
-      description: "Sort direction",
-    }),
+    stringEnum(["asc", "desc"] as const, { description: "Sort direction" }),
   ),
   user_id_type: Type.Optional(
     Type.String({ description: "User ID type for returned creators" }),
@@ -399,9 +403,10 @@ export const UpdateTaskCommentSchema = Type.Object({
   comment_id: Type.String({ description: "Comment ID to update" }),
   comment: TaskCommentUpdateContentSchema,
   update_fields: Type.Optional(
-    Type.Array(Type.String(), {
+    Type.Array(TaskCommentUpdateFieldSchema, {
       description: "Fields to update. If omitted, this tool infers from keys in comment (content)",
       minItems: 1,
+      uniqueItems: true,
     }),
   ),
   user_id_type: Type.Optional(

package/src/tools-common/tool-context.ts

@@ -4,6 +4,7 @@ export type FeishuToolContext = {
   channel: "feishu";
   accountId: string;
   sessionKey?: string;
+  senderOpenId?: string;
 };
 
 const toolContextStorage = new AsyncLocalStorage<FeishuToolContext>();

package/src/tools-config.ts

@@ -2,7 +2,7 @@ import type { FeishuToolsConfig } from "./types.js";
 
 /**
  * Default tool configuration.
- * - doc, wiki, drive, scopes, task: enabled by default
+ * - doc, wiki, drive, scopes, task, chat: enabled by default
  * - perm: disabled by default (sensitive operation)
  */
 export const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
@@ -12,11 +12,18 @@ export const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
   perm: false,
   scopes: true,
   task: true,
+  chat: true,
+  urgent: true,
 };
 
 /**
  * Resolve tools config with defaults.
+ * Only includes keys that are present in the input config or defaults.
  */
 export function resolveToolsConfig(cfg?: FeishuToolsConfig): Required<FeishuToolsConfig> {
-  return { ...DEFAULT_TOOLS_CONFIG, ...cfg };
+  const res = {} as Required<FeishuToolsConfig>;
+  for (const key in DEFAULT_TOOLS_CONFIG) {
+    res[key] = cfg?.[key] ?? DEFAULT_TOOLS_CONFIG[key];
+  }
+  return res;
 }

package/src/types.ts

@@ -30,13 +30,17 @@ export type FeishuMessageContext = {
   senderId: string;
   senderOpenId: string;
   senderName?: string;
-  chatType: "p2p" | "group";
+  chatType: "p2p" | "group" | "private";
   mentionedBot: boolean;
   hasAnyMention?: boolean;
   rootId?: string;
   parentId?: string;
   content: string;
   contentType: string;
+  /** Media placeholder token (e.g. <media:audio>) when inbound message is media. */
+  placeholder?: string;
+  /** Raw provider payload string (original event.message.content). */
+  rawPayload?: string;
   /** Mention forward targets (excluding the bot itself) */
   mentionTargets?: MentionTarget[];
   /** Extracted message body (after removing @ placeholders) */
@@ -69,6 +73,9 @@ export type FeishuToolsConfig = {
   perm?: boolean;
   scopes?: boolean;
   task?: boolean;
+  chat?: boolean;
+  /** Enable the feishu_urgent tool (buzz/urgent notifications). Enabled by default. */
+  urgent?: boolean;
 };
 
 export type DynamicAgentCreationConfig = {

package/src/typing.ts

@@ -7,13 +7,94 @@ import { resolveFeishuAccount } from "./accounts.js";
 // 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;
+  }
+}
+
+/**
+ * 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.
+ */
+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;
+}
+
 export type TypingIndicatorState = {
   messageId: string;
   reactionId: string | null;
 };
 
 /**
- * Add a typing indicator (reaction) to a message
+ * Add a typing indicator (reaction) to a message.
+ *
+ * Rate-limit and quota errors are re-thrown so the circuit breaker in
+ * `createTypingCallbacks` can trip and stop the keepalive loop.
  */
 export async function addTypingIndicator(params: {
   cfg: ClawdbotConfig;
@@ -36,17 +117,33 @@ export async function addTypingIndicator(params: {
       },
     });
 
+    // 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) {
+      console.log(
+        `[feishu] typing indicator response contains backoff code ${backoffCode}, stopping keepalive`,
+      );
+      throw new FeishuBackoffError(backoffCode);
+    }
+
     const reactionId = (response as any)?.data?.reaction_id ?? null;
     return { messageId, reactionId };
   } catch (err) {
-    // Silently fail - typing indicator is not critical
+    if (isFeishuBackoffError(err)) {
+      console.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)
     console.log(`[feishu] failed to add typing indicator: ${err}`);
     return { messageId, reactionId: null };
   }
 }
 
 /**
- * Remove a typing indicator (reaction) from a message
+ * 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;
@@ -62,14 +159,27 @@ export async function removeTypingIndicator(params: {
   const client = createFeishuClient(account);
 
   try {
-    await client.im.messageReaction.delete({
+    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) {
+      console.log(
+        `[feishu] typing indicator removal response contains backoff code ${backoffCode}, stopping keepalive`,
+      );
+      throw new FeishuBackoffError(backoffCode);
+    }
   } catch (err) {
-    // Silently fail - cleanup is not critical
+    if (isFeishuBackoffError(err)) {
+      console.log(`[feishu] typing indicator removal hit rate-limit/quota, stopping keepalive`);
+      throw err;
+    }
+    // Silently fail for other non-critical errors
     console.log(`[feishu] failed to remove typing indicator: ${err}`);
   }
 }