feishu-user-plugin 1.3.15 → 1.3.17

package/src/test-doc-block-media.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// Unit tests for the image/file block 3-step write flows (2026-06-07 systemic
+// audit): create placeholder → upload media → PATCH replace. Before the fix a
+// step-2/3 failure threw a raw error that did not name the placeholder block —
+// the empty block stayed in the document as an orphan with no repair path, and
+// transient Feishu flakes (rate limit / 5xx / code=2200) were never retried
+// (unlike createDocTable's cell fill).
+'use strict';
+
+const assert = require('assert');
+const docs = require('./clients/official/docs');
+
+let pass = 0, fail = 0;
+async function ok(name, fn) {
+  try { await fn(); console.log(`  OK  ${name}`); pass++; }
+  catch (e) { console.log(`  FAIL ${name}: ${e.message}`); fail++; }
+}
+
+const TRANSIENT = () => new Error('updateDocBlock failed (HTTP 503, code=99991400): rate limited');
+const PERMANENT = () => new Error('updateDocBlock failed (HTTP 403, code=1770032): forBidden');
+
+// Stub for createDocBlockWithImage. Dispatches _asUserOrApp on label:
+//   *.placeholder → returns the created placeholder block
+//   *.replaceImage / *.replaceFile → behavior driven by patchFails
+function imageStub({ patchFails, uploadFails } = {}) {
+  const calls = { patches: 0, uploads: 0 };
+  const self = {
+    async _asUserOrApp({ label }) {
+      if (label.endsWith('.placeholder')) {
+        return { data: { children: [{ block_id: 'ph1', block_type: 27 }] }, _viaUser: true, _fallbackWarning: null };
+      }
+      calls.patches++;
+      if (patchFails) {
+        const err = patchFails(calls.patches);
+        if (err) throw err;
+      }
+      return { data: {}, _viaUser: true };
+    },
+    async uploadMedia() {
+      calls.uploads++;
+      if (uploadFails) {
+        const err = uploadFails(calls.uploads);
+        if (err) throw err;
+      }
+      return { fileToken: 'img_tok_1', viaUser: true };
+    },
+  };
+  return { self, calls };
+}
+
+// Stub for createDocBlockWithFile — the create response returns the inner FILE
+// block directly (block_type 23) so the view-walk is skipped.
+function fileStub({ patchFails } = {}) {
+  const calls = { patches: 0 };
+  const self = {
+    async _asUserOrApp({ label }) {
+      if (label.endsWith('.placeholder')) {
+        return { data: { children: [{ block_id: 'fb1', block_type: 23 }] }, _viaUser: true, _fallbackWarning: null };
+      }
+      calls.patches++;
+      if (patchFails) {
+        const err = patchFails(calls.patches);
+        if (err) throw err;
+      }
+      return { data: {}, _viaUser: true };
+    },
+    async uploadMedia() { return { fileToken: 'box_tok_1', viaUser: true }; },
+  };
+  return { self, calls };
+}
+
+async function run() {
+  console.log('=== test-doc-block-media ===');
+
+  await ok('image: retries a transient PATCH failure and succeeds', async () => {
+    const { self, calls } = imageStub({ patchFails: (n) => (n === 1 ? TRANSIENT() : null) });
+    const r = await docs.createDocBlockWithImage.call(self, 'd', 'd', { imagePath: '/tmp/x.png', retryDelaysMs: [1, 1] });
+    assert.strictEqual(r.blockId, 'ph1');
+    assert.strictEqual(calls.patches, 2, 'transient PATCH retried');
+  });
+
+  await ok('image: permanent PATCH failure throws a structured error naming the orphan placeholder', async () => {
+    const { self } = imageStub({ patchFails: () => PERMANENT() });
+    let err = null;
+    try {
+      await docs.createDocBlockWithImage.call(self, 'd', 'd', { imagePath: '/tmp/x.png', retryDelaysMs: [1, 1] });
+    } catch (e) { err = e; }
+    assert.ok(err, 'must throw on permanent failure');
+    assert.strictEqual(err.blockId, 'ph1', 'error must carry the placeholder blockId');
+    assert.ok(/ph1/.test(err.message), 'message must name the placeholder for cleanup/repair');
+    assert.ok(/img_tok_1/.test(err.message), 'message should carry the uploaded token so the caller can re-attach without re-uploading');
+    assert.ok(/image_token=/.test(err.message), 'repair hint must use the concrete token param name (not an ambiguous placeholder)');
+    assert.ok(/document_id=d\b/.test(err.message), 'repair hint must include the document_id required by manage_doc_block');
+  });
+
+  await ok('image: upload failure also names the placeholder (orphan exists before upload)', async () => {
+    const { self } = imageStub({ uploadFails: () => PERMANENT() });
+    let err = null;
+    try {
+      await docs.createDocBlockWithImage.call(self, 'd', 'd', { imagePath: '/tmp/x.png', retryDelaysMs: [1, 1] });
+    } catch (e) { err = e; }
+    assert.ok(err);
+    assert.strictEqual(err.blockId, 'ph1');
+    assert.ok(/ph1/.test(err.message));
+  });
+
+  await ok('image: transient upload failure is retried', async () => {
+    const { self, calls } = imageStub({ uploadFails: (n) => (n === 1 ? TRANSIENT() : null) });
+    const r = await docs.createDocBlockWithImage.call(self, 'd', 'd', { imagePath: '/tmp/x.png', retryDelaysMs: [1, 1] });
+    assert.strictEqual(r.blockId, 'ph1');
+    assert.strictEqual(calls.uploads, 2, 'transient upload retried');
+  });
+
+  await ok('file: permanent PATCH failure throws a structured error naming the orphan block', async () => {
+    const { self } = fileStub({ patchFails: () => PERMANENT() });
+    let err = null;
+    try {
+      await docs.createDocBlockWithFile.call(self, 'd', 'd', { fileToken: 'box_pre_uploaded', retryDelaysMs: [1, 1] });
+    } catch (e) { err = e; }
+    assert.ok(err);
+    assert.strictEqual(err.blockId, 'fb1', 'error must carry the file block id');
+    assert.ok(/fb1/.test(err.message));
+  });
+
+  await ok('file: transient PATCH failure is retried and succeeds', async () => {
+    const { self, calls } = fileStub({ patchFails: (n) => (n === 1 ? TRANSIENT() : null) });
+    const r = await docs.createDocBlockWithFile.call(self, 'd', 'd', { fileToken: 'box_pre_uploaded', retryDelaysMs: [1, 1] });
+    assert.strictEqual(r.blockId, 'fb1');
+    assert.strictEqual(calls.patches, 2);
+  });
+
+  console.log(`\n=== test-doc-block-media: ${pass} passed, ${fail} failed ===`);
+  if (fail > 0) process.exit(1);
+}
+
+if (require.main === module) {
+  run().catch((e) => { console.error('test-doc-block-media harness error:', e); process.exit(1); });
+}
+
+module.exports = { run };

package/src/test-doc-blocks-pagination.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// Unit tests for getDocBlocks pagination (v1.3.17) + the tool-layer plumbing
+// in src/tools/docs.js (get_doc_blocks page_token/max_blocks passthrough,
+// manage_doc_block failedCells warning lift, read_doc_markdown truncation note).
+//
+// Field report (2026-06-07): a ~300KB doc synced via manage_doc_block exceeded
+// 500 blocks; get_doc_blocks and read_doc_markdown both silently stopped at the
+// same mid-document position — the client fetched ONE page of 500 and ignored
+// has_more/page_token, with no truncation flag for the caller.
+'use strict';
+
+const assert = require('assert');
+const docs = require('./clients/official/docs');
+const { handlers } = require('./tools/docs');
+
+let pass = 0, fail = 0;
+async function ok(name, fn) {
+  try { await fn(); console.log(`  OK  ${name}`); pass++; }
+  catch (e) { console.log(`  FAIL ${name}: ${e.message}`); fail++; }
+}
+
+// pageMap: requested page_token ('' for first call) → { items, has_more, next }
+function pagedStub(pageMap) {
+  const calls = [];
+  const self = {
+    async _asUserOrApp({ query }) {
+      const key = (query && query.page_token) || '';
+      calls.push(key);
+      const p = pageMap[key];
+      if (!p) throw new Error(`unexpected page_token: "${key}"`);
+      const data = { items: p.items, has_more: !!p.has_more };
+      if (p.next !== undefined) data.page_token = p.next;
+      return { data, _viaUser: true };
+    },
+  };
+  return { self, calls };
+}
+
+const blk = (id) => ({ block_id: id, block_type: 2 });
+
+async function run() {
+  console.log('=== test-doc-blocks-pagination ===');
+
+  await ok('follows page_token to fetch ALL blocks past the 500/page cap', async () => {
+    const { self, calls } = pagedStub({
+      '':   { items: [blk('b1'), blk('b2')], has_more: true, next: 'p2' },
+      'p2': { items: [blk('b3')], has_more: false },
+    });
+    const r = await docs.getDocBlocks.call(self, 'docX');
+    assert.strictEqual(r.items.length, 3, 'all pages concatenated');
+    assert.strictEqual(r.total, 3);
+    assert.strictEqual(r.hasMore, false);
+    assert.strictEqual(r.nextPageToken, undefined);
+    assert.deepStrictEqual(calls, ['', 'p2'], 'second request carries the page_token');
+    assert.strictEqual(r.viaUser, true);
+  });
+
+  await ok('max_blocks stops early and reports hasMore + nextPageToken + truncated', async () => {
+    const { self, calls } = pagedStub({
+      '':   { items: [blk('b1'), blk('b2')], has_more: true, next: 'p2' },
+      'p2': { items: [blk('b3')], has_more: false },
+    });
+    const r = await docs.getDocBlocks.call(self, 'docX', { maxBlocks: 2 });
+    assert.strictEqual(r.items.length, 2);
+    assert.strictEqual(r.hasMore, true);
+    assert.strictEqual(r.truncated, true);
+    assert.strictEqual(r.nextPageToken, 'p2');
+    assert.strictEqual(calls.length, 1, 'no extra page fetched past max_blocks');
+  });
+
+  await ok('treats malformed max_blocks (0 / negative / string) as "no cap" — full fetch, no truncation', async () => {
+    for (const bad of [0, -5, 'abc', NaN]) {
+      const { self } = pagedStub({
+        '':   { items: [blk('b1'), blk('b2')], has_more: true, next: 'p2' },
+        'p2': { items: [blk('b3')], has_more: false },
+      });
+      const r = await docs.getDocBlocks.call(self, 'docX', { maxBlocks: bad });
+      assert.strictEqual(r.items.length, 3, `maxBlocks=${bad} must not cap the fetch`);
+      assert.strictEqual(r.hasMore, false, `maxBlocks=${bad} must not flag truncation`);
+    }
+  });
+
+  await ok('resumes from a caller-provided pageToken', async () => {
+    const { self, calls } = pagedStub({
+      'p2': { items: [blk('b3')], has_more: false },
+    });
+    const r = await docs.getDocBlocks.call(self, 'docX', { pageToken: 'p2' });
+    assert.deepStrictEqual(calls, ['p2']);
+    assert.strictEqual(r.items.length, 1);
+    assert.strictEqual(r.hasMore, false);
+  });
+
+  await ok('continues past a permission-filtered empty page (empty + ADVANCING token is not a stall)', async () => {
+    // Feishu documents that paginated endpoints may return an empty page with
+    // has_more:true (permission filtering) and the caller should keep paging.
+    // An empty page must NOT end the loop when the cursor is still advancing.
+    const { self, calls } = pagedStub({
+      '':   { items: [blk('b1')], has_more: true, next: 'p2' },
+      'p2': { items: [], has_more: true, next: 'p3' }, // filtered-empty, real data behind it
+      'p3': { items: [blk('b2')], has_more: false },
+    });
+    const r = await docs.getDocBlocks.call(self, 'docX');
+    assert.strictEqual(r.items.length, 2, 'must fetch the data behind the empty page');
+    assert.strictEqual(r.hasMore, false);
+    assert.deepStrictEqual(calls, ['', 'p2', 'p3']);
+  });
+
+  await ok('terminates on a stalled cursor (empty page, has_more, same token) and withholds it', async () => {
+    const { self, calls } = pagedStub({
+      '':   { items: [blk('b1')], has_more: true, next: 'p1' },
+      'p1': { items: [], has_more: true, next: 'p1' }, // server stall — would loop forever
+    });
+    const r = await docs.getDocBlocks.call(self, 'docX');
+    assert.ok(calls.length <= 3, `must terminate, made ${calls.length} calls`);
+    assert.strictEqual(r.items.length, 1);
+    assert.strictEqual(r.hasMore, true, 'incompleteness is reported, not hidden');
+    assert.strictEqual(r.nextPageToken, undefined, 'stalled cursor is withheld (PR #116 parity)');
+  });
+
+  await ok('get_doc_blocks handler passes page_token/max_blocks through to the client', async () => {
+    let got;
+    const ctx = {
+      resolveDocId: async (x) => x,
+      getOfficialClient: () => ({
+        getDocBlocks: async (id, opts) => { got = { id, opts }; return { items: [], total: 0, hasMore: false }; },
+      }),
+    };
+    await handlers.get_doc_blocks({ document_id: 'd', page_token: 'pX', max_blocks: 100 }, ctx);
+    assert.strictEqual(got.id, 'd');
+    assert.strictEqual(got.opts.pageToken, 'pX');
+    assert.strictEqual(got.opts.maxBlocks, 100);
+  });
+
+  await ok('manage_doc_block lifts a top warning when the table fill partially failed', async () => {
+    const ctx = {
+      resolveDocId: async (x) => x,
+      getOfficialClient: () => ({
+        createDocTable: async () => ({
+          tableBlockId: 'tbl1', cells: [['c0', 'c1']], rows: 1, columns: 2, filled: 1,
+          failedCells: [{ row: 0, col: 1, cellId: 'c1', textBlockId: 't-c1', reason: 'code=2200 …' }],
+          viaUser: true, fallbackWarning: null,
+        }),
+      }),
+    };
+    const res = await handlers.manage_doc_block({
+      action: 'create', document_id: 'd', parent_block_id: 'd',
+      table: { rows: 1, columns: 2, cells: [['A', 'B']] },
+    }, ctx);
+    const txt = res.content[0].text;
+    assert.ok(txt.startsWith('⚠'), `warning lifted to top: ${txt.slice(0, 80)}`);
+    assert.ok(/1\/2/.test(txt), 'warning names the failed/attempted ratio');
+    assert.ok(/failedCells/.test(txt), 'warning points at failedCells[]');
+    assert.ok(/"failedCells"/.test(txt), 'JSON body still carries failedCells');
+  });
+
+  await ok('read_doc_markdown appends a truncation note when blocks are incomplete', async () => {
+    try { require.resolve('feishu-docx'); } catch (_) {
+      console.log('       (feishu-docx not installed — skipping render assertion)');
+      return;
+    }
+    const fixturePath = require('path').join(__dirname, 'test-fixtures', 'doc-blocks', 'sample-1.json');
+    if (!require('fs').existsSync(fixturePath)) {
+      console.log('       (no fixture — skipping render assertion)');
+      return;
+    }
+    const blocks = JSON.parse(require('fs').readFileSync(fixturePath, 'utf8'));
+    const ctx = {
+      resolveDocId: async (x) => x,
+      getOfficialClient: () => ({
+        getDocBlocks: async () => ({ items: blocks, total: 2, hasMore: true }),
+      }),
+    };
+    const res = await handlers.read_doc_markdown({ document_id: 'd' }, ctx);
+    const md = res.content[0].text;
+    assert.ok(/truncated/i.test(md), `markdown output must flag incompleteness: ${md.slice(-120)}`);
+  });
+
+  console.log(`\n=== test-doc-blocks-pagination: ${pass} passed, ${fail} failed ===`);
+  if (fail > 0) process.exit(1);
+}
+
+if (require.main === module) {
+  run().catch((e) => { console.error('test-doc-blocks-pagination harness error:', e); process.exit(1); });
+}
+
+module.exports = { run };

package/src/test-doc-table.js

@@ -27,8 +27,11 @@ async function ok(name, fn) {
 //                      false: empty cell (CREATE)
 //   resolvableCells  — cell ids that getBlockChildren(table) will return (defaults
 //                      to cellIds); set shorter to exercise fail-loud
-function stub({ cellIds, cellsInCreate = true, cellHasText = true, resolvableCells } = {}) {
-  const calls = { createBody: null, updates: [], creates: [], childFetches: [] };
+//   updateFails      — optional (blockId, attemptNo) => Error|null; attemptNo is
+//                      1-based per block. Lets tests inject transient/persistent
+//                      cell-fill failures (the 2026-06-07 mode-F field report).
+function stub({ cellIds, cellsInCreate = true, cellHasText = true, resolvableCells, updateFails } = {}) {
+  const calls = { createBody: null, updates: [], creates: [], childFetches: [], updateAttempts: {} };
   const self = {
     async _asUserOrApp({ body }) {
       calls.createBody = body;
@@ -45,12 +48,30 @@ function stub({ cellIds, cellsInCreate = true, cellHasText = true, resolvableCel
       // a cell → its auto text block (or none)
       return { items: cellHasText ? [{ block_id: 't-' + blockId, block_type: 2 }] : [] };
     },
-    async updateDocBlock(documentId, blockId, body) { calls.updates.push({ blockId, body }); return { block: {} }; },
+    async updateDocBlock(documentId, blockId, body) {
+      calls.updateAttempts[blockId] = (calls.updateAttempts[blockId] || 0) + 1;
+      if (updateFails) {
+        const err = updateFails(blockId, calls.updateAttempts[blockId]);
+        if (err) throw err;
+      }
+      calls.updates.push({ blockId, body });
+      return { block: {} };
+    },
     async createDocBlock(documentId, parent, children) { calls.creates.push({ parent, children }); return { blocks: [] }; },
   };
   return { self, calls };
 }
 
+// Production both-identities failure messages, verbatim shape from
+// identity-state.js::withIdentityFallback — classifyError extracts the FIRST
+// `code=` occurrence (the UAT-side code).
+const TRANSIENT_BOTH = () => new Error(
+  'updateDocBlock failed on both identities. as user: code=2200 msg=check incr user_access_token scope fail. as app: updateDocBlock failed (HTTP 403, code=1770032): forBidden',
+);
+const PERMANENT_BOTH = () => new Error(
+  'updateDocBlock failed on both identities. as user: code=99991668 msg=access denied. as app: updateDocBlock failed (HTTP 403, code=1770032): forBidden',
+);
+
 async function run() {
   console.log('=== test-doc-table ===');
 
@@ -103,6 +124,74 @@ async function run() {
     assert.strictEqual(calls.updates.length, 2);
   });
 
+  // --- v1.3.17: cell-fill resilience (mode-F partial failure field report) ---
+
+  await ok('retries transient cell-fill failures and still fills every cell', async () => {
+    // c01's update fails twice with the production code=2200 transient, then clears.
+    const { self, calls } = stub({
+      cellIds: ['c00', 'c01', 'c10', 'c11'],
+      updateFails: (blockId, attempt) => (blockId === 't-c01' && attempt <= 2 ? TRANSIENT_BOTH() : null),
+    });
+    const r = await docs.createDocTable.call(self, 'd', 'd', {
+      rows: 2, columns: 2, cells: [['A', 'B'], ['C', 'D']], retryDelaysMs: [1, 1],
+    });
+    assert.strictEqual(r.filled, 4, 'all 4 cells filled after retries');
+    assert.ok(!r.failedCells || r.failedCells.length === 0, 'no failedCells when retries succeed');
+    assert.strictEqual(calls.updateAttempts['t-c01'], 3, 'failing cell attempted 3 times (1 + 2 retries)');
+  });
+
+  await ok('reports failedCells {row,col,cellId,textBlockId,reason} and keeps filling on persistent failure', async () => {
+    const { self, calls } = stub({
+      cellIds: ['c00', 'c01', 'c10', 'c11'],
+      updateFails: (blockId) => (blockId === 't-c01' ? PERMANENT_BOTH() : null),
+    });
+    const r = await docs.createDocTable.call(self, 'd', 'd', {
+      rows: 2, columns: 2, cells: [['A', 'B'], ['C', 'D']], retryDelaysMs: [1, 1],
+    });
+    assert.strictEqual(r.tableBlockId, 'tbl1', 'partial result keeps tableBlockId');
+    assert.strictEqual(r.filled, 3, 'other cells still filled');
+    assert.strictEqual(r.failedCells.length, 1);
+    const f = r.failedCells[0];
+    assert.strictEqual(f.row, 0);
+    assert.strictEqual(f.col, 1);
+    assert.strictEqual(f.cellId, 'c01');
+    assert.strictEqual(f.textBlockId, 't-c01');
+    assert.ok(/code=99991668/.test(f.reason), `reason carries the underlying error: ${f.reason}`);
+    assert.strictEqual(calls.updateAttempts['t-c01'], 1, 'permanent errors are NOT retried');
+  });
+
+  await ok('records the failed cell after exhausting transient retries and continues', async () => {
+    const { self, calls } = stub({
+      cellIds: ['c0', 'c1'],
+      updateFails: (blockId) => (blockId === 't-c0' ? TRANSIENT_BOTH() : null),
+    });
+    const r = await docs.createDocTable.call(self, 'd', 'd', {
+      rows: 1, columns: 2, cells: [['X', 'Y']], retryDelaysMs: [1, 1],
+    });
+    assert.strictEqual(r.filled, 1);
+    assert.strictEqual(r.failedCells.length, 1);
+    assert.strictEqual(calls.updateAttempts['t-c0'], 3, 'transient retried to exhaustion (1 + 2 retries)');
+    assert.strictEqual(calls.updateAttempts['t-c1'], 1, 'later cell still attempted');
+  });
+
+  await ok('aborts after 3 consecutive cell failures and marks the remainder skipped', async () => {
+    const { self, calls } = stub({
+      cellIds: ['c0', 'c1', 'c2', 'c3', 'c4', 'c5'],
+      updateFails: () => PERMANENT_BOTH(),
+    });
+    const r = await docs.createDocTable.call(self, 'd', 'd', {
+      rows: 2, columns: 3, cells: [['a', 'b', 'c'], ['d', 'e', 'f']], retryDelaysMs: [1, 1],
+    });
+    assert.strictEqual(r.filled, 0);
+    assert.strictEqual(r.failedCells.length, 6, 'every provided cell accounted for');
+    const attempted = r.failedCells.filter(f => !f.skipped);
+    const skipped = r.failedCells.filter(f => f.skipped);
+    assert.strictEqual(attempted.length, 3, 'stops attempting after 3 consecutive failures');
+    assert.strictEqual(skipped.length, 3, 'remaining cells reported as skipped');
+    assert.ok(skipped.every(f => f.cellId), 'skipped entries still carry cellId for manual repair');
+    assert.strictEqual(Object.keys(calls.updateAttempts).length, 3, 'no API calls for skipped cells');
+  });
+
   await ok('rejects rows/columns < 1', async () => {
     const { self } = stub({ cellIds: [] });
     for (const bad of [{ rows: 0, columns: 2 }, { rows: 2, columns: 0 }, { rows: -1, columns: 1 }]) {

package/src/test-error-codes.js

@@ -47,6 +47,16 @@ function run() {
     assert.equal(c.reason, 'upload_transient', `${code} reason`);
   }
 
+  // --- 2200 docx scope-check flake (v1.3.17) ---
+  // Field report 2026-06-07: a mode-F table fill saw 15 identical updateDocBlock
+  // calls succeed, then "code=2200 check incr user_access_token scope fail" —
+  // same token, so the scope was fine; the check itself is intermittently flaky
+  // under rapid-fire docx writes. Classified transient so cell-fill retries it.
+  const c2200 = classifyError(2200);
+  assert.equal(c2200.action, 'retry', '2200 should be transient (retry)');
+  const bothIdentities = new Error('updateDocBlock failed on both identities. as user: code=2200 msg=check incr user_access_token scope fail. as app: updateDocBlock failed (HTTP 403, code=1770032): forBidden');
+  assert.equal(classifyError(bothIdentities).action, 'retry', 'combined both-identities message extracts the UAT-side 2200');
+
   // --- res.json() parse failures should retry once ---
   // Real-world: feishu's gateway occasionally returns truncated bodies that
   // make response.json() throw SyntaxError; one retry usually clears it.

package/src/test-pagination-cursor-chain.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// Unit tests for the cursor-chain fixes (2026-06-07 systemic audit, follow-up
+// to PR #118): clients that return hasMore but drop the resume cursor, tool
+// schemas/handlers that never expose page_token, and partial-failure arrays
+// silently swallowed.
+//
+// Covers:
+//   1. read_messages / read_p2p_messages — page_token passthrough (client ready)
+//   2. list_wiki_nodes — client must return pageToken; handler must pass it
+//   3. manage_bitable_record(search) — same chain as 2
+//   4. listWikiSpaces — internal pagination to completion (was silent 50-cap)
+//   5. manage_members(add) — surface not_existed_id_list / pending_approval_id_list
+'use strict';
+
+const assert = require('assert');
+const wikiClient = require('./clients/official/wiki');
+const bitableClient = require('./clients/official/bitable');
+const groupsClient = require('./clients/official/groups');
+const imReadHandlers = require('./tools/im-read').handlers;
+const wikiHandlers = require('./tools/wiki').handlers;
+const bitableHandlers = require('./tools/bitable').handlers;
+const groupsHandlers = require('./tools/groups').handlers;
+
+let pass = 0, fail = 0;
+async function ok(name, fn) {
+  try { await fn(); console.log(`  OK  ${name}`); pass++; }
+  catch (e) { console.log(`  FAIL ${name}: ${e.message}`); fail++; }
+}
+
+async function run() {
+  console.log('=== test-pagination-cursor-chain ===');
+
+  // --- 1. read_messages / read_p2p_messages ---
+
+  await ok('read_messages handler passes page_token through to readMessagesWithFallback', async () => {
+    let got;
+    const official = {
+      hasUAT: true,
+      readMessagesWithFallback: async (chatId, opts) => { got = { chatId, opts }; return { items: [] }; },
+    };
+    const ctx = { getOfficialClient: () => official, getUserClient: async () => { throw new Error('no cookie'); } };
+    await imReadHandlers.read_messages({ chat_id: 'oc_test', page_token: 'PT1' }, ctx);
+    assert.strictEqual(got.chatId, 'oc_test');
+    assert.strictEqual(got.opts.pageToken, 'PT1', 'page_token must reach the client as pageToken');
+  });
+
+  await ok('read_p2p_messages handler passes page_token through to readMessagesAsUser', async () => {
+    let got;
+    const official = {
+      readMessagesAsUser: async (chatId, opts) => { got = { chatId, opts }; return { items: [] }; },
+    };
+    const ctx = { getOfficialClient: () => official, getUserClient: async () => { throw new Error('no cookie'); } };
+    await imReadHandlers.read_p2p_messages({ chat_id: '7123456', page_token: 'PT2' }, ctx);
+    assert.strictEqual(got.opts.pageToken, 'PT2');
+  });
+
+  // --- 2. list_wiki_nodes ---
+
+  await ok('listWikiNodes client returns the resume pageToken alongside hasMore', async () => {
+    const self = {
+      async _asUserOrApp() {
+        return { data: { items: [{ node_token: 'n1' }], has_more: true, page_token: 'WNEXT' }, _viaUser: true };
+      },
+    };
+    const r = await wikiClient.listWikiNodes.call(self, 'sp1', {});
+    assert.strictEqual(r.hasMore, true);
+    assert.strictEqual(r.pageToken, 'WNEXT', 'hasMore without a cursor is a dead end');
+  });
+
+  await ok('list_wiki_nodes handler passes page_token through', async () => {
+    let got;
+    const ctx = {
+      getOfficialClient: () => ({
+        listWikiNodes: async (spaceId, opts) => { got = { spaceId, opts }; return { items: [], hasMore: false }; },
+      }),
+    };
+    await wikiHandlers.list_wiki_nodes({ space_id: 'sp1', page_token: 'PT3' }, ctx);
+    assert.strictEqual(got.opts.pageToken, 'PT3');
+  });
+
+  // --- 3. manage_bitable_record(search) ---
+
+  await ok('searchBitableRecords client returns the resume pageToken alongside hasMore', async () => {
+    const self = {
+      async _asUserOrApp() {
+        return { data: { items: [{ record_id: 'r1' }], total: 2000, has_more: true, page_token: 'BNEXT' }, _viaUser: true };
+      },
+      // legacy path uses _safeSDKCall? keep both shims so the test follows the impl
+      async _safeSDKCall(fn) { return fn(); },
+    };
+    const r = await bitableClient.searchBitableRecords.call(self, 'app1', 'tbl1', {});
+    assert.strictEqual(r.hasMore, true);
+    assert.strictEqual(r.pageToken, 'BNEXT', 'hasMore + total without a cursor strands the caller at page 1');
+  });
+
+  await ok('manage_bitable_record(search) handler passes page_token through', async () => {
+    let got;
+    const ctx = {
+      resolveDocId: async (x) => x,
+      getOfficialClient: () => ({
+        searchBitableRecords: async (appToken, tableId, opts) => { got = { appToken, tableId, opts }; return { items: [], hasMore: false }; },
+      }),
+    };
+    await bitableHandlers.manage_bitable_record({ action: 'search', app_token: 'app1', table_id: 'tbl1', page_token: 'PT4' }, ctx);
+    assert.strictEqual(got.opts.pageToken, 'PT4');
+  });
+
+  // --- 4. listWikiSpaces full pagination ---
+
+  await ok('listWikiSpaces follows page_token to fetch ALL spaces past the 50/page cap', async () => {
+    const calls = [];
+    const self = {
+      async _asUserOrApp({ query }) {
+        const key = (query && query.page_token) || '';
+        calls.push(key);
+        if (key === '') return { data: { items: Array.from({ length: 50 }, (_, i) => ({ space_id: 's' + i })), has_more: true, page_token: 'SP2' }, _viaUser: true };
+        if (key === 'SP2') return { data: { items: [{ space_id: 's50' }], has_more: false }, _viaUser: true };
+        throw new Error('unexpected page_token: ' + key);
+      },
+    };
+    const r = await wikiClient.listWikiSpaces.call(self);
+    assert.strictEqual(r.items.length, 51, 'all pages concatenated');
+    assert.deepStrictEqual(calls, ['', 'SP2']);
+    assert.ok(!r.hasMore, 'complete fetch must not flag hasMore');
+  });
+
+  await ok('listWikiSpaces continues past a permission-filtered empty page (empty + advancing token)', async () => {
+    const calls = [];
+    const self = {
+      async _asUserOrApp({ query }) {
+        const key = (query && query.page_token) || '';
+        calls.push(key);
+        if (key === '') return { data: { items: [{ space_id: 's1' }], has_more: true, page_token: 'SP2' }, _viaUser: true };
+        if (key === 'SP2') return { data: { items: [], has_more: true, page_token: 'SP3' }, _viaUser: true }; // filtered-empty
+        if (key === 'SP3') return { data: { items: [{ space_id: 's2' }], has_more: false }, _viaUser: true };
+        throw new Error('unexpected page_token: ' + key);
+      },
+    };
+    const r = await wikiClient.listWikiSpaces.call(self);
+    assert.strictEqual(r.items.length, 2, 'must page through the filtered-empty page to reach s2');
+    assert.deepStrictEqual(calls, ['', 'SP2', 'SP3']);
+    assert.ok(!r.hasMore, 'complete fetch must not flag hasMore');
+  });
+
+  await ok('listWikiSpaces terminates on a stalled cursor and reports hasMore', async () => {
+    let n = 0;
+    const self = {
+      async _asUserOrApp() {
+        n++;
+        return { data: { items: n === 1 ? [{ space_id: 's1' }] : [], has_more: true, page_token: 'LOOP' }, _viaUser: true };
+      },
+    };
+    const r = await wikiClient.listWikiSpaces.call(self);
+    assert.ok(n <= 3, `must terminate, made ${n} calls`);
+    assert.strictEqual(r.items.length, 1);
+    assert.strictEqual(r.hasMore, true, 'incompleteness must be visible');
+  });
+
+  // --- 5. manage_members(add) partial-failure arrays ---
+
+  await ok('addChatMembers surfaces not_existed_id_list and pending_approval_id_list', async () => {
+    const self = {
+      async _safeSDKCall(fn) {
+        return { data: { invalid_id_list: ['bad1'], not_existed_id_list: ['ghost1'], pending_approval_id_list: ['wait1', 'wait2'] } };
+      },
+    };
+    const r = await groupsClient.addChatMembers.call(self, 'oc_g', ['bad1', 'ghost1', 'wait1', 'wait2', 'ok1']);
+    assert.deepStrictEqual(r.invalidIds, ['bad1']);
+    assert.deepStrictEqual(r.notExistedIds, ['ghost1'], 'not_existed ids must not be swallowed');
+    assert.deepStrictEqual(r.pendingApprovalIds, ['wait1', 'wait2'], 'pending-approval ids must not be swallowed');
+  });
+
+  await ok('manage_members(add) response names the partial failures, not a silent success', async () => {
+    const ctx = {
+      getOfficialClient: () => ({
+        addChatMembers: async () => ({ invalidIds: [], notExistedIds: ['ghost1'], pendingApprovalIds: ['wait1'] }),
+      }),
+    };
+    const res = await groupsHandlers.manage_members({ chat_id: 'oc_g', member_ids: ['ghost1', 'wait1', 'ok1'], action: 'add' }, ctx);
+    const txt = res.content[0].text;
+    assert.ok(/ghost1/.test(txt), 'not-existed id visible in response');
+    assert.ok(/wait1/.test(txt), 'pending id visible in response');
+    assert.ok(txt.startsWith('⚠'), `partial failure must be lifted as a top warning, not buried in JSON: ${txt.slice(0, 120)}`);
+  });
+
+  console.log(`\n=== test-pagination-cursor-chain: ${pass} passed, ${fail} failed ===`);
+  if (fail > 0) process.exit(1);
+}
+
+if (require.main === module) {
+  run().catch((e) => { console.error('test-pagination-cursor-chain harness error:', e); process.exit(1); });
+}
+
+module.exports = { run };