feishu-user-plugin 1.3.10 → 1.3.12

package/src/auth/uat.js

@@ -9,9 +9,16 @@
 //   - decodeTokenExpiry(token) — JWT exp parsing
 //   - getValidUAT(client) — returns current UAT, refreshes if expiring
 //   - refreshUAT(client) — full refresh dance with file lock + persist
-//   - withUAT(client, fn) — wrapper that retries fn once on auth-error codes
+//   - withUAT(client, fn) — wrapper that retries fn once on auth codes + on
+//     transient throws (classifyError action='retry'); v1.3.12 widening
 //   - uatREST(client, method, path, opts) — generic UAT REST helper
-//   - asUserOrApp(client, opts) — UAT-first, bot-fallback wrapper
+//   - asUserOrApp(client, opts) — legacy UAT-first / bot-fallback signature.
+//     v1.3.12: the body is now a thin shape adapter around
+//     withIdentityFallback (src/auth/identity-state.js). The public contract
+//     — return data with _viaUser ∈ {true,false} + optional _fallbackWarning,
+//     throw Error with .uatSummary + .appError on dual failure — is
+//     preserved so 15+ existing callsites in calendar/docs/bitable/wiki/okr/
+//     tasks/drive/im keep compiling.
 //   - persistUAT(client) — writes through auth/credentials
 //   - adoptPersistedUATIfNewer(client) — peer-rotation adoption
 //   - acquireRefreshLock / releaseRefreshLock — cross-process advisory lock
@@ -144,8 +151,24 @@ function persistUAT(client) {
 }
 
 async function withUAT(client, fn) {
+  const { classifyError } = require('../error-codes');
   let uat = await getValidUAT(client);
-  const data = await fn(uat);
+
+  // First attempt. If fn() throws an upstream flake (network reset, response
+  // body truncated mid-JSON, gateway 5xx), classifyError says action='retry'
+  // and we re-run once with the same UAT — the token is still valid, the
+  // call just lost. Auth-related codes are the existing refresh path below.
+  let data;
+  try {
+    data = await fn(uat);
+  } catch (err) {
+    const cls = classifyError(err);
+    if (cls.action === 'retry') {
+      return fn(uat);
+    }
+    throw err;
+  }
+
   if (data.code === 99991668 || data.code === 99991663 || data.code === 99991677) {
     if (data.code === 99991668 && typeof data.msg === 'string' && /not support/i.test(data.msg)) {
       return data;
@@ -182,40 +205,31 @@ async function uatREST(client, method, urlPath, { body, query } = {}) {
 }
 
 async function asUserOrApp(client, { uatPath, method = 'GET', body, query, sdkFn, label }) {
-  let uatSummary = null;
-  if (client.hasUAT) {
-    try {
-      const data = await uatREST(client, method, uatPath, { body, query });
-      if (data.code === 0) {
-        data._viaUser = true;
-        return data;
-      }
-      uatSummary = `as user: code=${data.code} msg=${data.msg}`;
-      console.error(`[feishu-user-plugin] ${label} ${uatSummary}, retrying as app`);
-    } catch (err) {
-      uatSummary = `as user: ${err.message}`;
-      console.error(`[feishu-user-plugin] ${label} as user threw (${err.message}), retrying as app`);
-    }
-  }
+  // v1.3.12: internal implementation routes through withIdentityFallback in
+  // src/auth/identity-state.js. The public shape — return data with _viaUser
+  // and optional _fallbackWarning, throw Error with .uatSummary + .appError
+  // when both sides fail — is preserved for 15+ existing callsites.
+  const { withIdentityFallback } = require('./identity-state');
   try {
-    const appData = await client._safeSDKCall(sdkFn, label);
-    if (appData && typeof appData === 'object') {
-      appData._viaUser = false;
-      if (uatSummary) {
-        appData._fallbackWarning = `⚠️  UAT 不可用 (${uatSummary}),本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。恢复方法:运行 \`npx feishu-user-plugin oauth\` 后重启 Claude Code / Codex。`;
-      } else if (!client.hasUAT) {
-        appData._fallbackWarning = `⚠️  未配置 UAT,本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。想让资源归你所有,先跑 \`npx feishu-user-plugin oauth\` 然后重启 Claude Code / Codex。`;
-      }
-    }
-    return appData;
-  } catch (appErr) {
-    if (uatSummary) {
-      const err = new Error(`${label} failed on both identities. ${uatSummary}. as app: ${appErr.message}`);
-      err.uatSummary = uatSummary;
-      err.appError = appErr;
-      throw err;
+    const result = await withIdentityFallback({
+      client,
+      uatFn: () => uatREST(client, method, uatPath, { body, query }),
+      botFn: () => client._safeSDKCall(sdkFn, label),
+      label,
+    });
+    // Surface state machine breadcrumbs in stderr so long-running servers can
+    // be diagnosed without grepping the LLM transcript. (Pre-v1.3.12 already
+    // logged on fallback; we keep parity but only when fallback actually
+    // happened, not on every BOT_ONLY call.)
+    if (result.via === 'bot' && result.viaReason) {
+      console.error(`[feishu-user-plugin] ${label} fell back to bot (${result.identity}): ${result.viaReason}`);
     }
-    throw appErr;
+    return result.data;
+  } catch (e) {
+    // Legacy callers expect err.appError — keep the alias alongside the new
+    // err.botError that withIdentityFallback sets.
+    if (e && e.botError && !e.appError) e.appError = e.botError;
+    throw e;
   }
 }
 

package/src/cli.js

@@ -33,6 +33,9 @@ switch (cmd) {
     }
     break;
   }
+  case 'tool':
+    runTool();
+    break;
   case 'migrate':
     migrate();
     break;
@@ -60,6 +63,10 @@ Commands:
   migrate     One-time consolidation: copy creds from harness configs into
               ~/.feishu-user-plugin/credentials.json (single source of truth).
               Dry-run by default. Add --confirm to actually write.
+  tool        Invoke any MCP tool from the shell (v1.3.12):
+              \`tool list\`                — list all tool names
+              \`tool help <name>\`         — print schema for <name>
+              \`tool <name> '<json-args>'\` — invoke <name>, print response
   help        Show this help
 
 Setup options:
@@ -106,6 +113,86 @@ Auto-renewal (optional):
 `);
 }
 
+// `tool` subcommand — invoke any MCP tool from the shell (v1.3.12).
+//
+// Usage:
+//   npx feishu-user-plugin tool list
+//   npx feishu-user-plugin tool help <name>
+//   npx feishu-user-plugin tool <name> '<json-args>'
+//
+// Reuses src/server.js's HANDLERS + buildCtx, so behaviour is identical to
+// calling the tool from an MCP client. Output: tool's content[0].text
+// (which is JSON for most tools — pipe through `jq` if you like).
+async function runTool() {
+  const { TOOLS, HANDLERS, buildCtx } = require('./server');
+  const sub = process.argv[3];
+
+  if (!sub || sub === '--help' || sub === '-h') {
+    console.log(`Usage:
+  npx feishu-user-plugin tool list
+      List all ${TOOLS.length} registered tool names.
+  npx feishu-user-plugin tool help <name>
+      Print the inputSchema for <name>.
+  npx feishu-user-plugin tool <name> '<json-args>'
+      Invoke <name> with the given JSON args, print response text to stdout.
+
+Examples:
+  npx feishu-user-plugin tool list
+  npx feishu-user-plugin tool help send_as_user
+  npx feishu-user-plugin tool get_login_status '{}'
+  npx feishu-user-plugin tool search_messages '{"query":"周报","page_size":5}'
+`);
+    process.exit(sub ? 0 : 2);
+  }
+
+  if (sub === 'list') {
+    for (const t of TOOLS) {
+      console.log(t.name);
+    }
+    return;
+  }
+
+  if (sub === 'help') {
+    const name = process.argv[4];
+    if (!name) { console.error('Usage: tool help <name>'); process.exit(2); }
+    const t = TOOLS.find((x) => x.name === name);
+    if (!t) { console.error(`Unknown tool: ${name}. Try \`tool list\`.`); process.exit(2); }
+    console.log(`# ${t.name}\n`);
+    console.log(t.description || '(no description)');
+    console.log('\n## inputSchema\n');
+    console.log(JSON.stringify(t.inputSchema || {}, null, 2));
+    return;
+  }
+
+  // Dispatch path: sub is the tool name, argv[4] is the JSON args.
+  const name = sub;
+  const handler = HANDLERS[name];
+  if (!handler) { console.error(`Unknown tool: ${name}. Try \`tool list\`.`); process.exit(2); }
+
+  const jsonArgs = process.argv[4] || '{}';
+  let args;
+  try { args = JSON.parse(jsonArgs); }
+  catch (e) {
+    console.error(`tool ${name}: failed to parse JSON args (${e.message}). Pass a single quoted JSON string, e.g. '{"key":"value"}'.`);
+    process.exit(2);
+  }
+
+  try {
+    const ctx = buildCtx();
+    const result = await handler(args, ctx);
+    const text = result?.content?.[0]?.text;
+    if (typeof text === 'string') {
+      console.log(text);
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+    if (result?.isError) process.exit(1);
+  } catch (e) {
+    console.error(`tool ${name}: ${e.message}`);
+    process.exit(1);
+  }
+}
+
 function migrate() {
   const { migrate: runMigrate } = require('./auth/credentials');
   const confirm = process.argv.includes('--confirm');

package/src/clients/official/base.js

@@ -1,5 +1,5 @@
 const lark = require('@larksuiteoapi/node-sdk');
-const { fetchWithTimeout } = require('../../utils');
+const { fetchWithTimeout, LRUCache } = require('../../utils');
 const { stderrLogger } = require('../../logger');
 const uatLifecycle = require('../../auth/uat');
 
@@ -11,7 +11,13 @@ class LarkOfficialClient {
     this._uat = null;
     this._uatRefresh = null;
     this._uatExpires = 0;
-    this._userNameCache = new Map(); // open_id → display name
+    // v1.3.12: bounded caches with TTL. Pre-v1.3.12 these were plain Maps that
+    // grew without bound and never expired, so a week-old server would carry
+    // stale display names. 500 entries / 10min covers the common chat-volume
+    // working set without keeping cold entries forever.
+    this._userNameCache = new LRUCache({ max: 500, ttlMs: 600_000 }); // open_id → display name
+    this._appNameCache = new LRUCache({ max: 100, ttlMs: 600_000 });  // app_id (cli_xxx) → app name
+    this._selfTenantKey = null;      // populated lazily on first message read
   }
 
   // --- UAT (User Access Token) Management ---
@@ -109,20 +115,58 @@ class LarkOfficialClient {
   }
 
   async _populateSenderNames(items, userClient) {
-    // Collect unique sender IDs that aren't cached
-    const unknownIds = new Set();
+    // Step 0: harvest mention name data — Feishu IM API ships mentions[].name
+    // alongside each message body, so we get (id, name) pairs for any user
+    // who got @-mentioned without spending a contact API call.
     for (const item of items) {
-      if (item.senderId && !this._userNameCache.has(item.senderId)) {
-        unknownIds.add(item.senderId);
+      if (Array.isArray(item.mentions)) {
+        for (const m of item.mentions) {
+          if (m.id && m.name && !this._userNameCache.has(m.id)) {
+            this._userNameCache.set(m.id, m.name);
+          }
+        }
       }
     }
-    // Parallel resolve via official contact API (instead of sequential N calls)
-    if (unknownIds.size > 0) {
-      await Promise.allSettled([...unknownIds].map(id => this.getUserById(id)));
+
+    // Step 1: lazy-resolve our own tenant_key so we can flag isExternal senders.
+    if (this._selfTenantKey === null) {
+      await this._resolveSelfTenantKey().catch(() => {});
+    }
+
+    // Step 2: collect unique unknown user / app ids
+    const unknownUserIds = new Set();
+    const unknownAppIds = new Set();
+    for (const item of items) {
+      if (!item.senderId) continue;
+      if (item.senderType === 'app') {
+        if (!this._appNameCache.has(item.senderId)) unknownAppIds.add(item.senderId);
+      } else if (!this._userNameCache.has(item.senderId)) {
+        unknownUserIds.add(item.senderId);
+      }
     }
-    // Fallback: resolve remaining unknowns via cookie-based user identity client
+
+    // Step 3: parallel resolve users via contact API.
+    // v1.3.12: read result.status so failed lookups don't disappear silently.
+    // The 2026-05 incident had ~100% lookup failure for weeks (UAT revoked +
+    // tenant scope gap) and senderName=null without any breadcrumb in stderr.
+    if (unknownUserIds.size > 0) {
+      const userIds = [...unknownUserIds];
+      const results = await Promise.allSettled(userIds.map(id => this.getUserById(id)));
+      const failed = [];
+      for (let i = 0; i < results.length; i++) {
+        if (results[i].status === 'rejected') {
+          failed.push({ id: userIds[i], reason: results[i].reason?.message || String(results[i].reason) });
+        }
+      }
+      if (failed.length) {
+        const sample = failed.slice(0, 3).map(f => `${f.id}(${f.reason})`).join(', ');
+        const tail = failed.length > 3 ? ` (+${failed.length - 3} more)` : '';
+        console.error(`[feishu-user-plugin] sender name lookup failed for ${failed.length}/${userIds.length} ids: ${sample}${tail}`);
+      }
+    }
+    // Cookie fallback for any user still unknown
     if (userClient) {
-      for (const id of unknownIds) {
+      for (const id of unknownUserIds) {
         if (!this._userNameCache.has(id)) {
           try {
             const name = await userClient.getUserName(id);
@@ -131,20 +175,101 @@ class LarkOfficialClient {
         }
       }
     }
-    // Populate senderName field
+    // Parallel resolve apps (best-effort; usually only self-app appears).
+    // v1.3.12: same Promise.allSettled status-reading fix as the user path.
+    if (unknownAppIds.size > 0) {
+      const appIds = [...unknownAppIds];
+      const results = await Promise.allSettled(appIds.map(id => this.getAppName(id)));
+      const failed = [];
+      for (let i = 0; i < results.length; i++) {
+        if (results[i].status === 'rejected') {
+          failed.push({ id: appIds[i], reason: results[i].reason?.message || String(results[i].reason) });
+        }
+      }
+      if (failed.length) {
+        const sample = failed.slice(0, 3).map(f => `${f.id}(${f.reason})`).join(', ');
+        const tail = failed.length > 3 ? ` (+${failed.length - 3} more)` : '';
+        console.error(`[feishu-user-plugin] app name lookup failed for ${failed.length}/${appIds.length} ids: ${sample}${tail}`);
+      }
+    }
+
+    // v1.3.12 negative cache: any id we tried to resolve but couldn't gets
+    // a null sentinel under the same LRU+TTL. The 10-min TTL on the cache
+    // gives renamed / newly-joined users a re-resolution window without
+    // dispatching N redundant API calls per read_messages on hot chats.
+    // has(id)==true / get(id)==null lets _computeDisplayLabel fall back to
+    // "(open_id)" exactly the same way as before.
+    for (const id of unknownUserIds) {
+      if (!this._userNameCache.has(id)) this._userNameCache.set(id, null);
+    }
+    for (const id of unknownAppIds) {
+      if (!this._appNameCache.has(id)) this._appNameCache.set(id, null);
+    }
+
+    // Step 4: populate senderName, isExternal, displayLabel
     for (const item of items) {
-      if (item.senderId) {
-        item.senderName = this._userNameCache.get(item.senderId) || null;
+      item.senderName = item.senderId ? (this._userNameCache.get(item.senderId) || null) : null;
+      if (this._selfTenantKey && item.senderTenantKey && item.senderTenantKey !== this._selfTenantKey) {
+        item.isExternal = true;
       }
+      item.displayLabel = this._computeDisplayLabel(item);
     }
   }
 
+  _computeDisplayLabel(item) {
+    const prefix = item.isRecalled ? '[已撤回] ' : '';
+    if (!item.senderId) return prefix + '[系统]';
+    if (item.senderType === 'anonymous') return prefix + '[匿名]';
+    if (item.senderType === 'app') {
+      const appName = this._appNameCache.get(item.senderId);
+      return prefix + `[Bot] ${appName || `(${item.senderId})`}`;
+    }
+    return prefix + (item.senderName || `(${item.senderId})`);
+  }
+
+  async getAppName(appId) {
+    if (this._appNameCache.has(appId)) return this._appNameCache.get(appId);
+    try {
+      const token = await this._getAppToken();
+      const res = await fetchWithTimeout(
+        `https://open.feishu.cn/open-apis/application/v6/applications/${encodeURIComponent(appId)}?lang=zh_cn`,
+        { headers: { 'Authorization': `Bearer ${token}` }, timeoutMs: 10000 },
+      );
+      const data = await res.json();
+      const name = data?.data?.app?.app_name;
+      if (name) {
+        this._appNameCache.set(appId, name);
+        return name;
+      }
+    } catch {
+      // best-effort; null means "couldn't resolve, fall back to id"
+    }
+    return null;
+  }
+
+  async _resolveSelfTenantKey() {
+    if (this._selfTenantKey) return this._selfTenantKey;
+    const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ app_id: this.appId, app_secret: this.appSecret }),
+      timeoutMs: 10000,
+    });
+    const data = await res.json();
+    if (data?.tenant_key) this._selfTenantKey = data.tenant_key;
+    return this._selfTenantKey;
+  }
+
   // --- Helpers ---
 
   _formatMessage(m) {
     if (!m) return null;
     let body = m.body?.content || '';
     try { body = JSON.parse(body); } catch {}
+    // Feishu signals recall by replacing body content with the literal string
+    // "This message was recalled" (not a JSON object). Surface as boolean so
+    // the LLM doesn't have to pattern-match the string.
+    const isRecalled = (typeof body === 'string' && /recalled/i.test(body));
     const out = {
       messageId: m.message_id,
       chatId: m.chat_id,
@@ -155,6 +280,12 @@ class LarkOfficialClient {
       createTime: this._normalizeTimestamp(m.create_time),
       updateTime: this._normalizeTimestamp(m.update_time),
     };
+    // Raw sender metadata — LLM may need id_type (to pick the right
+    // user_id_type for contact API) or tenant_key (to know cross-tenant).
+    if (m.sender?.id_type) out.senderIdType = m.sender.id_type;
+    if (m.sender?.tenant_key) out.senderTenantKey = m.sender.tenant_key;
+    if (isRecalled) out.isRecalled = true;
+    if (m.parent_id) out.isThreadReply = true;
     if (Array.isArray(m.mentions) && m.mentions.length > 0) out.mentions = m.mentions;
     if (m.upper_message_id) out.upperMessageId = m.upper_message_id;
     if (m.root_id) out.rootId = m.root_id;

package/src/clients/official/calendar.js

@@ -68,7 +68,9 @@ module.exports = {
   },
 
   // --- Calendar write (v1.3.7) ---
-  // Requires `calendar:calendar.event:write` scope on app + UAT.
+  // Requires the 4 verb-specific scopes on app + UAT:
+  //   calendar:calendar.event:create / update / delete / reply
+  // Feishu has no umbrella `:write` scope — using it 422-rejects OAuth.
 
   async createCalendarEvent(calendarId, eventData) {
     if (!calendarId) throw new Error('createCalendarEvent: calendarId is required');

package/src/clients/official/im.js

@@ -329,6 +329,22 @@ module.exports = {
       return f;
     });
     await this._populateSenderNames(children, userClient);
+    // Best-effort: surface the origin chat NAME for each child so the LLM doesn't
+    // misread the children as native messages of the current chat. A single
+    // merge_forward usually has 1 origin chat → 1 API call. Failures are silent
+    // (bot may not be in the origin chat) and the field is simply absent.
+    const originChatIds = [...new Set(children.map(c => c.originChatId).filter(Boolean))];
+    const chatNameMap = new Map();
+    await Promise.allSettled(originChatIds.map(async (cid) => {
+      try {
+        const info = await this.getChatInfo(cid);
+        if (info?.name) chatNameMap.set(cid, info.name);
+      } catch {}
+    }));
+    for (const c of children) {
+      const name = c.originChatId && chatNameMap.get(c.originChatId);
+      if (name) c.forwardedFromChatName = name;
+    }
     return children;
   },
 
@@ -366,7 +382,10 @@ module.exports = {
   //
   // Throws a single, wrapped error if BOTH paths fail or if UAT is absent and
   // the bot failed; the message points the user at `npx feishu-user-plugin oauth`.
-  async readMessagesWithFallback(chatId, options, userClient, { skipBot = false, via = 'bot' } = {}) {
+  async readMessagesWithFallback(chatId, options, userClient, { skipBot = false, skipUat = false, via = 'bot' } = {}) {
+    if (skipBot && skipUat) {
+      throw new Error('readMessagesWithFallback: cannot set both skipBot and skipUat — at least one identity path must be allowed');
+    }
     const tryUAT = async (viaLabel, reason) => {
       if (!this.hasUAT) {
         const hint = 'To read external / private groups, configure UAT via: npx feishu-user-plugin oauth';
@@ -381,7 +400,16 @@ module.exports = {
     };
 
     if (skipBot) {
-      return tryUAT(via || 'contacts', 'contacts_resolved_external');
+      // Two reasons we skipBot:
+      //   Path B (im-read.js): via='contacts' — chat was found only via
+      //   cookie search_contacts, bot definitely can't see it. Reason
+      //   field surfaces this to the LLM as "contacts_resolved_external".
+      //   v1.3.12 via_user=true: caller explicitly opted for UAT. No
+      //   failure happened; no reason needed.
+      if (via === 'contacts') {
+        return tryUAT('contacts', 'contacts_resolved_external');
+      }
+      return tryUAT(via && via !== 'bot' ? via : 'user');
     }
 
     // Attempt 1 — bot identity.
@@ -406,9 +434,55 @@ module.exports = {
         }
       }
 
+      // v1.3.12: when caller passes via_user=false (skipUat=true), surface
+      // the bot error instead of silently falling through to UAT. The user
+      // explicitly opted out of cross-identity fallback.
+      if (skipUat) {
+        throw new Error(`Bot path failed and via_user=false specified: ${botErr.message}`);
+      }
       // Fall through to UAT — if UAT is missing, tryUAT throws the user-friendly
       // "run npx feishu-user-plugin oauth" error instead of the raw Feishu payload.
       return tryUAT('user', klass.reason);
     }
   },
+
+  // --- Message search (v1.3.12, B.5) ---
+  //
+  // Wraps POST /open-apis/search/v2/message. UAT-only (Feishu doesn't expose
+  // bot path; probed 2026-05-15 — bot returns 99991668 "user access token not
+  // support"). Requires the `search:message` OAuth scope; without it the API
+  // returns 99991679 (permission_violations.subject="search:message"). Caller
+  // should re-run `npx feishu-user-plugin oauth` after adding the scope.
+  //
+  // Returns the raw shape from Feishu: { items: [{ message_id, ... }], page_token, has_more }.
+  // Items are message-id pointers — call read_messages / read_p2p_messages
+  // with the parent chat_id to fetch full bodies if needed.
+  async searchMessages({ query, fromIds, chatIds, messageTypes, atUserIds, fromTypes, pageSize = 20, pageToken } = {}) {
+    if (!query || typeof query !== 'string') {
+      throw new Error('searchMessages: query (search keyword string) is required');
+    }
+    if (!this.hasUAT) {
+      throw new Error('search_messages requires UAT (Feishu does not expose a bot-path search). Run: npx feishu-user-plugin oauth');
+    }
+    const body = { query };
+    if (pageSize) body.page_size = pageSize;
+    if (pageToken) body.page_token = pageToken;
+    if (Array.isArray(fromIds) && fromIds.length) body.from_ids = fromIds;
+    if (Array.isArray(chatIds) && chatIds.length) body.chat_ids = chatIds;
+    if (Array.isArray(messageTypes) && messageTypes.length) body.message_type_list = messageTypes;
+    if (Array.isArray(atUserIds) && atUserIds.length) body.at_chatter_ids = atUserIds;
+    if (Array.isArray(fromTypes) && fromTypes.length) body.from_types = fromTypes;
+    const data = await this._uatREST('POST', '/open-apis/search/v2/message', { body });
+    if (data.code === 99991679) {
+      throw new Error(`search_messages: UAT lacks the search:message scope. Re-run \`npx feishu-user-plugin oauth\` after the v1.3.12 SCOPES update.`);
+    }
+    if (data.code !== 0) {
+      throw new Error(`search_messages failed (code=${data.code}): ${data.msg}`);
+    }
+    return {
+      items: data.data?.items || [],
+      pageToken: data.data?.page_token || null,
+      hasMore: !!data.data?.has_more,
+    };
+  },
 };

package/src/clients/official/okr.js

@@ -57,7 +57,8 @@ module.exports = {
   },
 
   // --- OKR progress record write (v1.3.7) ---
-  // Requires `okr:okr.content:write` (or wider okr:okr) on the OAuth.
+  // Requires `okr:okr.content:writeonly` (or wider okr:okr) on the OAuth.
+  // Note: Feishu uses `:writeonly` (one word), not `:write`.
 
   async createOkrProgressRecord({ targetId, targetType, content, sourceTitle, sourceUrl, sourceUrlPc, sourceUrlMobile, progressRate, userIdType = 'open_id' }) {
     if (!targetId) throw new Error('createOkrProgressRecord: target_id is required (the key_result_id or objective_id)');

package/src/error-codes.js

@@ -26,6 +26,28 @@ const FAILURE_MAP = {
   // Chat does not exist (from the bot's POV — may still be accessible to user).
   19001:  { action: 'uat', reason: 'bot_chat_not_found' },
 
+  // UAT revoked — refresh_token explicitly invalid_grant (user revoked OAuth
+  // or 30-day window elapsed). The live trigger for this code lives in
+  // identity-state.js::_classifyUatFailure (UAT REST throws / returns 20064);
+  // this entry exists for *symmetry* — should a bot-side surface ever return
+  // 20064 (it shouldn't, bot uses app_access_token not refresh_token), the
+  // fallback caller would route to UAT once and surface revocation.
+  20064: { action: 'uat', reason: 'uat_revoked' },
+  // Cross-tenant bot block — bot lives in tenant A, target resource is in
+  // tenant B. Will never be granted. Distinct from 240001 (which is the
+  // older code form for the same shape); both surface in production.
+  91403: { action: 'uat', reason: 'bot_cross_tenant' },
+
+  // Upload pipeline transient errors — the Feishu upload gateway is
+  // intermittently flaky; one retry after a moment usually clears.
+  // 1254000 / 1254001 are generic upload failures, 1254301 is multipart
+  // size mismatch (rare race when the body is being computed concurrently),
+  // 1254400 is "upload service busy" the gateway returns under load.
+  1254000: { action: 'retry', reason: 'upload_transient' },
+  1254001: { action: 'retry', reason: 'upload_transient' },
+  1254301: { action: 'retry', reason: 'upload_transient' },
+  1254400: { action: 'retry', reason: 'upload_transient' },
+
   // Rate limited — Feishu throttles, try once more after a brief pause.
   42101:  { action: 'retry', reason: 'bot_rate_limited' },
   // Frequency control variants occasionally observed.
@@ -41,8 +63,21 @@ const TRANSIENT_PATTERNS = [
   /ETIMEDOUT/i,
   /fetch timeout after/i, // from utils.fetchWithTimeout
   /socket hang up/i,
+  /Unexpected end of JSON input/i,
+  /Unexpected token .* in JSON/i,
 ];
 
+// Recognise res.json() parse failures so withUAT widens retry to them too.
+// The Feishu gateway occasionally returns a truncated body that crashes
+// JSON.parse — classifying the SyntaxError as transient lets the wrapper
+// recover with a single retry instead of bubbling a cryptic parse error.
+function _isJsonParseError(err) {
+  if (!err) return false;
+  if (err.name === 'SyntaxError') return true;
+  const msg = err.message || '';
+  return /Unexpected end of JSON input/i.test(msg) || /Unexpected token .* in JSON/i.test(msg);
+}
+
 /**
  * Classify an error thrown by a bot-API path.
  * Input is either the Feishu code number (preferred) or the Error object —
@@ -65,6 +100,11 @@ function classifyError(errOrCode) {
   if (code != null && FAILURE_MAP[code]) {
     return { ...FAILURE_MAP[code], code };
   }
+  // res.json() parse failures get a dedicated reason so logs disambiguate
+  // them from generic network flakes (different remediation in monitoring).
+  if (errOrCode && typeof errOrCode === 'object' && _isJsonParseError(errOrCode)) {
+    return { action: 'retry', reason: 'response_parse_error', code };
+  }
   for (const re of TRANSIENT_PATTERNS) {
     if (re.test(msg)) return { action: 'retry', reason: 'bot_network_error', code };
   }