@actagent/feishu 2026.6.2

package/src/doc-schema.ts

@@ -0,0 +1,183 @@
+// Feishu helper module supports doc schema behavior.
+import { Type, type Static } from "typebox";
+
+const tableCreationProperties = {
+  doc_token: Type.String({ description: "Document token" }),
+  parent_block_id: Type.Optional(
+    Type.String({ description: "Parent block ID (default: document root)" }),
+  ),
+  row_size: Type.Integer({ description: "Table row count", minimum: 1 }),
+  column_size: Type.Integer({ description: "Table column count", minimum: 1 }),
+  column_width: Type.Optional(
+    Type.Array(Type.Number({ minimum: 1 }), {
+      description: "Column widths in px (length should match column_size)",
+    }),
+  ),
+};
+
+export const FeishuDocSchema = Type.Union([
+  Type.Object({
+    action: Type.Literal("read"),
+    doc_token: Type.String({ description: "Document token (extract from URL /docx/XXX)" }),
+  }),
+  Type.Object({
+    action: Type.Literal("write"),
+    doc_token: Type.String({ description: "Document token" }),
+    content: Type.String({
+      description: "Markdown content to write (replaces entire document content)",
+    }),
+  }),
+  Type.Object({
+    action: Type.Literal("append"),
+    doc_token: Type.String({ description: "Document token" }),
+    content: Type.String({ description: "Markdown content to append to end of document" }),
+  }),
+  Type.Object({
+    action: Type.Literal("insert"),
+    doc_token: Type.String({ description: "Document token" }),
+    content: Type.String({ description: "Markdown content to insert" }),
+    after_block_id: Type.String({
+      description: "Insert content after this block ID. Use list_blocks to find block IDs.",
+    }),
+  }),
+  Type.Object({
+    action: Type.Literal("create"),
+    title: Type.String({ description: "Document title" }),
+    folder_token: Type.Optional(Type.String({ description: "Target folder token (optional)" })),
+    grant_to_requester: Type.Optional(
+      Type.Boolean({
+        description:
+          "Grant edit permission to the trusted requesting Feishu user from runtime context (default: true).",
+      }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("list_blocks"),
+    doc_token: Type.String({ description: "Document token" }),
+  }),
+  Type.Object({
+    action: Type.Literal("get_block"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Block ID (from list_blocks)" }),
+  }),
+  Type.Object({
+    action: Type.Literal("update_block"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Block ID (from list_blocks)" }),
+    content: Type.String({ description: "New text content" }),
+  }),
+  Type.Object({
+    action: Type.Literal("delete_block"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Block ID" }),
+  }),
+  // Table creation (explicit structure)
+  Type.Object({
+    action: Type.Literal("create_table"),
+    ...tableCreationProperties,
+  }),
+  Type.Object({
+    action: Type.Literal("write_table_cells"),
+    doc_token: Type.String({ description: "Document token" }),
+    table_block_id: Type.String({ description: "Table block ID" }),
+    values: Type.Array(Type.Array(Type.String()), {
+      description: "2D matrix values[row][col] to write into table cells",
+      minItems: 1,
+    }),
+  }),
+  Type.Object({
+    action: Type.Literal("create_table_with_values"),
+    ...tableCreationProperties,
+    values: Type.Array(Type.Array(Type.String()), {
+      description: "2D matrix values[row][col] to write into table cells",
+      minItems: 1,
+    }),
+  }),
+  // Table row/column manipulation
+  Type.Object({
+    action: Type.Literal("insert_table_row"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Table block ID" }),
+    row_index: Type.Optional(
+      Type.Number({ description: "Row index to insert at (-1 for end, default: -1)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("insert_table_column"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Table block ID" }),
+    column_index: Type.Optional(
+      Type.Number({ description: "Column index to insert at (-1 for end, default: -1)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("delete_table_rows"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Table block ID" }),
+    row_start: Type.Number({ description: "Start row index (0-based)" }),
+    row_count: Type.Optional(Type.Number({ description: "Number of rows to delete (default: 1)" })),
+  }),
+  Type.Object({
+    action: Type.Literal("delete_table_columns"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Table block ID" }),
+    column_start: Type.Number({ description: "Start column index (0-based)" }),
+    column_count: Type.Optional(
+      Type.Number({ description: "Number of columns to delete (default: 1)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("merge_table_cells"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Table block ID" }),
+    row_start: Type.Number({ description: "Start row index" }),
+    row_end: Type.Number({ description: "End row index (exclusive)" }),
+    column_start: Type.Number({ description: "Start column index" }),
+    column_end: Type.Number({ description: "End column index (exclusive)" }),
+  }),
+  // Image / file upload
+  Type.Object({
+    action: Type.Literal("upload_image"),
+    doc_token: Type.String({ description: "Document token" }),
+    url: Type.Optional(Type.String({ description: "Remote image URL (http/https)" })),
+    file_path: Type.Optional(Type.String({ description: "Local image file path" })),
+    image: Type.Optional(
+      Type.String({
+        description:
+          "Image as data URI (data:image/png;base64,...) or plain base64 string. Use instead of url/file_path for DALL-E outputs, canvas screenshots, etc.",
+      }),
+    ),
+    parent_block_id: Type.Optional(
+      Type.String({ description: "Parent block ID (default: document root)" }),
+    ),
+    filename: Type.Optional(Type.String({ description: "Optional filename override" })),
+    index: Type.Optional(
+      Type.Integer({
+        minimum: 0,
+        description: "Insert position (0-based index among siblings). Omit to append.",
+      }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("upload_file"),
+    doc_token: Type.String({ description: "Document token" }),
+    url: Type.Optional(Type.String({ description: "Remote file URL (http/https)" })),
+    file_path: Type.Optional(Type.String({ description: "Local file path" })),
+    parent_block_id: Type.Optional(
+      Type.String({ description: "Parent block ID (default: document root)" }),
+    ),
+    filename: Type.Optional(Type.String({ description: "Optional filename override" })),
+  }),
+  // Text color / style
+  Type.Object({
+    action: Type.Literal("color_text"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Text block ID to update" }),
+    content: Type.String({
+      description:
+        'Text with color markup. Tags: [red], [green], [blue], [orange], [yellow], [purple], [grey], [bold], [bg:yellow]. Example: "Revenue [green]+15%[/green] YoY"',
+    }),
+  }),
+]);
+
+export type FeishuDocParams = Static<typeof FeishuDocSchema>;

package/src/doctor.test.ts

@@ -0,0 +1,382 @@
+// Feishu tests cover doctor plugin behavior.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { loadSessionStore } from "actagent/plugin-sdk/session-store-runtime";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { ACTAgentConfig } from "../runtime-api.js";
+import { isFeishuSessionStoreKey, runFeishuDoctorSequence } from "./doctor.js";
+
+type EnvSnapshot = {
+  HOME?: string;
+  ACTAGENT_HOME?: string;
+  ACTAGENT_STATE_DIR?: string;
+};
+
+function captureEnv(): EnvSnapshot {
+  return {
+    HOME: process.env.HOME,
+    ACTAGENT_HOME: process.env.ACTAGENT_HOME,
+    ACTAGENT_STATE_DIR: process.env.ACTAGENT_STATE_DIR,
+  };
+}
+
+function restoreEnv(snapshot: EnvSnapshot) {
+  for (const key of Object.keys(snapshot) as Array<keyof EnvSnapshot>) {
+    const value = snapshot[key];
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+}
+
+function feishuConfig(): ACTAgentConfig {
+  return {
+    channels: {
+      feishu: {
+        appId: "cli_xxx",
+        appSecret: "secret_xxx",
+      },
+    },
+  } as ACTAgentConfig;
+}
+
+function stateDir(): string {
+  const dir = process.env.ACTAGENT_STATE_DIR;
+  if (!dir) {
+    throw new Error("ACTAGENT_STATE_DIR is not set");
+  }
+  return dir;
+}
+
+function sessionsDir(agentId = "main"): string {
+  return path.join(stateDir(), "agents", agentId, "sessions");
+}
+
+function storePath(agentId = "main"): string {
+  return path.join(sessionsDir(agentId), "sessions.json");
+}
+
+function writeStore(entries: Record<string, unknown>, agentId = "main"): string {
+  const target = storePath(agentId);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, JSON.stringify(entries, null, 2));
+  return target;
+}
+
+function writeTranscript(sessionId: string, lines: unknown[], agentId = "main"): string {
+  const target = path.join(sessionsDir(agentId), `${sessionId}.jsonl`);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${lines.map((line) => JSON.stringify(line)).join("\n")}\n`);
+  return target;
+}
+
+function sessionHeader(sessionId: string) {
+  return {
+    type: "session",
+    id: sessionId,
+    version: 7,
+    timestamp: new Date(0).toISOString(),
+    cwd: "/tmp",
+  };
+}
+
+function userMessage(content: string) {
+  return {
+    type: "message",
+    id: `msg-${content || "blank"}-${Math.random().toString(36).slice(2)}`,
+    parentId: null,
+    timestamp: new Date(0).toISOString(),
+    message: { role: "user", content },
+  };
+}
+
+function listBackupDirs(): string[] {
+  const backupsDir = path.join(stateDir(), "backups");
+  return fs.existsSync(backupsDir)
+    ? fs.readdirSync(backupsDir).filter((name) => name.startsWith("feishu-state-repair-"))
+    : [];
+}
+
+describe("Feishu doctor state repair", () => {
+  let envSnapshot: EnvSnapshot;
+  let tempHome = "";
+
+  beforeEach(() => {
+    envSnapshot = captureEnv();
+    tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "actagent-feishu-doctor-"));
+    process.env.HOME = tempHome;
+    process.env.ACTAGENT_HOME = tempHome;
+    process.env.ACTAGENT_STATE_DIR = path.join(tempHome, ".actagent");
+    fs.mkdirSync(process.env.ACTAGENT_STATE_DIR, { recursive: true, mode: 0o700 });
+  });
+
+  afterEach(() => {
+    restoreEnv(envSnapshot);
+    fs.rmSync(tempHome, { recursive: true, force: true });
+  });
+
+  it("matches only Feishu channel session keys", () => {
+    expect(isFeishuSessionStoreKey("agent:main:feishu:direct:ou_user")).toBe(true);
+    expect(isFeishuSessionStoreKey("feishu:direct:ou_user")).toBe(true);
+    expect(isFeishuSessionStoreKey("agent:codex:acp:binding:feishu:default:abc123")).toBe(false);
+    expect(isFeishuSessionStoreKey("agent:main:discord:direct:user")).toBe(false);
+  });
+
+  it("stays quiet for healthy Feishu state and transcripts", async () => {
+    const feishuDedupDir = path.join(stateDir(), "feishu", "dedup");
+    fs.mkdirSync(feishuDedupDir, { recursive: true });
+    fs.writeFileSync(path.join(feishuDedupDir, "default.json"), JSON.stringify({ msg1: 1 }));
+
+    writeTranscript("sess-ok", [sessionHeader("sess-ok"), userMessage("hello")]);
+    writeStore({
+      "agent:main:feishu:direct:ou_user": {
+        sessionId: "sess-ok",
+        sessionFile: "sess-ok.jsonl",
+        updatedAt: Date.now(),
+      },
+    });
+
+    const result = await runFeishuDoctorSequence({
+      cfg: feishuConfig(),
+      env: process.env,
+      shouldRepair: false,
+    });
+
+    expect(result).toEqual({ changeNotes: [], warningNotes: [] });
+  });
+
+  it("keeps custom-store sessions with canonical absolute transcripts", async () => {
+    const transcriptPath = writeTranscript("sess-abs", [
+      sessionHeader("sess-abs"),
+      userMessage("hello"),
+    ]);
+    const customStorePath = path.join(stateDir(), "custom-sessions", "sessions.json");
+    fs.mkdirSync(path.dirname(customStorePath), { recursive: true });
+    fs.writeFileSync(
+      customStorePath,
+      JSON.stringify({
+        "agent:main:feishu:direct:ou_user": {
+          sessionId: "sess-abs",
+          sessionFile: transcriptPath,
+          updatedAt: Date.now(),
+        },
+      }),
+    );
+
+    const result = await runFeishuDoctorSequence({
+      cfg: {
+        ...feishuConfig(),
+        session: { store: customStorePath },
+      } as ACTAgentConfig,
+      env: process.env,
+      shouldRepair: false,
+    });
+
+    expect(result).toEqual({ changeNotes: [], warningNotes: [] });
+  });
+
+  it("keeps Feishu sessions with separated blank user messages", async () => {
+    writeTranscript("sess-separated-blanks", [
+      sessionHeader("sess-separated-blanks"),
+      userMessage(""),
+      userMessage("hello"),
+      userMessage(""),
+      userMessage("world"),
+      userMessage(""),
+    ]);
+    writeStore({
+      "agent:main:feishu:direct:ou_user": {
+        sessionId: "sess-separated-blanks",
+        sessionFile: "sess-separated-blanks.jsonl",
+        updatedAt: Date.now(),
+      },
+    });
+
+    const result = await runFeishuDoctorSequence({
+      cfg: feishuConfig(),
+      env: process.env,
+      shouldRepair: false,
+    });
+
+    expect(result).toEqual({ changeNotes: [], warningNotes: [] });
+  });
+
+  it("warns before repair when Feishu local state is corrupt", async () => {
+    const feishuDedupDir = path.join(stateDir(), "feishu", "dedup");
+    fs.mkdirSync(feishuDedupDir, { recursive: true });
+    fs.writeFileSync(path.join(feishuDedupDir, "default.json"), "{");
+
+    const result = await runFeishuDoctorSequence({
+      cfg: feishuConfig(),
+      env: process.env,
+      shouldRepair: false,
+    });
+
+    expect(result.changeNotes).toEqual([]);
+    expect(result.warningNotes.join("\n")).toContain("Feishu local channel state may need repair");
+    expect(result.warningNotes.join("\n")).toContain("preserving Feishu App ID/secret config");
+    expect(result.warningNotes.join("\n")).toContain("actagent doctor --fix");
+  });
+
+  it("rebuilds corrupt Feishu state without deleting healthy Feishu sessions", async () => {
+    const feishuDedupDir = path.join(stateDir(), "feishu", "dedup");
+    fs.mkdirSync(feishuDedupDir, { recursive: true });
+    fs.writeFileSync(path.join(feishuDedupDir, "default.json"), "{");
+
+    const transcriptPath = writeTranscript("sess-ok", [
+      sessionHeader("sess-ok"),
+      userMessage("hello"),
+    ]);
+    const targetStorePath = writeStore({
+      "agent:main:feishu:direct:ou_user": {
+        sessionId: "sess-ok",
+        sessionFile: "sess-ok.jsonl",
+        updatedAt: Date.now(),
+      },
+    });
+
+    const result = await runFeishuDoctorSequence({
+      cfg: feishuConfig(),
+      env: process.env,
+      shouldRepair: true,
+    });
+
+    expect(result.warningNotes).toEqual([]);
+    expect(result.changeNotes.join("\n")).toContain("Rebuilt Feishu runtime state: yes");
+    expect(result.changeNotes.join("\n")).toContain("Removed 0 Feishu-scoped session entries");
+
+    const store = loadSessionStore(targetStorePath, { skipCache: true });
+    expect(store["agent:main:feishu:direct:ou_user"]).toBeDefined();
+    expect(fs.existsSync(transcriptPath)).toBe(true);
+
+    expect(fs.existsSync(path.join(stateDir(), "feishu"))).toBe(true);
+    expect(fs.existsSync(path.join(stateDir(), "feishu", "dedup", "default.json"))).toBe(false);
+
+    const backups = listBackupDirs();
+    expect(backups).toHaveLength(1);
+    const backupDir = path.join(stateDir(), "backups", backups[0] ?? "");
+    expect(fs.existsSync(path.join(backupDir, "feishu", "dedup", "default.json"))).toBe(true);
+    expect(fs.existsSync(path.join(backupDir, "session-stores", "main", "sessions.json"))).toBe(
+      false,
+    );
+  });
+
+  it("archives only unhealthy Feishu direct sessions while preserving state, config, and other sessions", async () => {
+    const feishuDedupDir = path.join(stateDir(), "feishu", "dedup");
+    fs.mkdirSync(feishuDedupDir, { recursive: true });
+    fs.writeFileSync(path.join(feishuDedupDir, "default.json"), JSON.stringify({ msg1: 1 }));
+
+    const transcriptPath = writeTranscript("sess-bad", [
+      sessionHeader("sess-bad"),
+      userMessage(""),
+      userMessage(""),
+      userMessage(""),
+    ]);
+    const trajectoryPath = path.join(sessionsDir(), "sess-bad.trajectory.jsonl");
+    const trajectoryIndexPath = path.join(sessionsDir(), "sess-bad.trajectory-path.json");
+    fs.writeFileSync(trajectoryPath, "{}\n");
+    fs.writeFileSync(trajectoryIndexPath, "{}\n");
+    const acpTranscriptPath = writeTranscript("sess-acp-bad", [
+      sessionHeader("sess-acp-bad"),
+      userMessage(""),
+      userMessage(""),
+      userMessage(""),
+    ]);
+
+    const targetStorePath = writeStore({
+      "agent:main:feishu:direct:ou_user": {
+        sessionId: "sess-bad",
+        sessionFile: "sess-bad.jsonl",
+        updatedAt: Date.now(),
+      },
+      "agent:codex:acp:binding:feishu:default:abc123": {
+        sessionId: "sess-acp-bad",
+        sessionFile: "sess-acp-bad.jsonl",
+        updatedAt: Date.now(),
+        route: { channel: "feishu", target: { to: "ou_user", chatType: "direct" } },
+      },
+      "agent:main:discord:direct:user": {
+        sessionId: "sess-discord",
+        updatedAt: Date.now(),
+      },
+    });
+
+    const result = await runFeishuDoctorSequence({
+      cfg: feishuConfig(),
+      env: process.env,
+      shouldRepair: true,
+    });
+
+    expect(result.warningNotes).toEqual([]);
+    expect(result.changeNotes.join("\n")).toContain("Feishu local state repaired");
+    expect(result.changeNotes.join("\n")).toContain("Rebuilt Feishu runtime state: not needed");
+    expect(result.changeNotes.join("\n")).toContain("Preserved Feishu App ID/secret config");
+
+    expect(fs.existsSync(path.join(stateDir(), "feishu"))).toBe(true);
+    expect(fs.existsSync(path.join(stateDir(), "feishu", "dedup", "default.json"))).toBe(true);
+
+    const backups = listBackupDirs();
+    expect(backups).toHaveLength(1);
+    const backupDir = path.join(stateDir(), "backups", backups[0] ?? "");
+    expect(fs.existsSync(path.join(backupDir, "feishu", "dedup", "default.json"))).toBe(false);
+    expect(fs.existsSync(path.join(backupDir, "session-stores", "main", "sessions.json"))).toBe(
+      true,
+    );
+
+    const store = loadSessionStore(targetStorePath, { skipCache: true });
+    expect(store["agent:main:feishu:direct:ou_user"]).toBeUndefined();
+    expect(store["agent:codex:acp:binding:feishu:default:abc123"]).toBeDefined();
+    expect(store["agent:main:discord:direct:user"]).toBeDefined();
+
+    expect(fs.existsSync(transcriptPath)).toBe(false);
+    expect(fs.existsSync(acpTranscriptPath)).toBe(true);
+    expect(fs.existsSync(trajectoryPath)).toBe(false);
+    expect(fs.existsSync(trajectoryIndexPath)).toBe(false);
+    const archivedNames = fs.readdirSync(sessionsDir());
+    expect(archivedNames.some((name) => name.startsWith("sess-bad.jsonl.deleted."))).toBe(true);
+    expect(
+      archivedNames.some((name) => name.startsWith("sess-bad.trajectory.jsonl.deleted.")),
+    ).toBe(true);
+    expect(
+      archivedNames.some((name) => name.startsWith("sess-bad.trajectory-path.json.deleted.")),
+    ).toBe(true);
+  });
+
+  it("archives unhealthy default-scope sessions when metadata identifies Feishu", async () => {
+    const transcriptPath = writeTranscript("sess-default-feishu-bad", [
+      sessionHeader("sess-default-feishu-bad"),
+      userMessage(""),
+      userMessage(""),
+      userMessage(""),
+    ]);
+    const targetStorePath = writeStore({
+      "agent:main:main": {
+        sessionId: "sess-default-feishu-bad",
+        sessionFile: "sess-default-feishu-bad.jsonl",
+        updatedAt: Date.now(),
+        origin: { provider: "feishu", from: "feishu:ou_user" },
+        route: { channel: "feishu", target: { to: "ou_user", chatType: "direct" } },
+      },
+      "agent:main:main-non-feishu": {
+        sessionId: "sess-other",
+        updatedAt: Date.now(),
+        origin: { provider: "discord" },
+      },
+    });
+
+    const result = await runFeishuDoctorSequence({
+      cfg: feishuConfig(),
+      env: process.env,
+      shouldRepair: true,
+    });
+
+    expect(result.warningNotes).toEqual([]);
+    const store = loadSessionStore(targetStorePath, { skipCache: true });
+    expect(store["agent:main:main"]).toBeUndefined();
+    expect(store["agent:main:main-non-feishu"]).toBeDefined();
+    expect(fs.existsSync(transcriptPath)).toBe(false);
+  });
+});