@coldiq/mcp 0.3.17 → 0.3.19

package/dist/tools/find-emails.d.ts

@@ -23,11 +23,13 @@ export declare const findEmailsSchema: {
     }>, "many">;
     use_providers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 };
-export declare function findEmailsHandler(input: Record<string, unknown>): Promise<{
+type ToolResult = {
     content: [{
-        type: "text";
+        type: 'text';
         text: string;
     }];
     isError?: boolean;
-}>;
+};
+export declare function findEmailsHandler(input: Record<string, unknown>): Promise<ToolResult>;
+export {};
 //# sourceMappingURL=find-emails.d.ts.map

package/dist/tools/find-emails.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-emails.d.ts","sourceRoot":"","sources":["../../src/tools/find-emails.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,cAAc,gBAAgB,CAAA;AAE3C,eAAO,MAAM,qBAAqB,QAOqE,CAAA;AAEvG,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;CAe5B,CAAA;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;GAIrE"}
+{"version":3,"file":"find-emails.d.ts","sourceRoot":"","sources":["../../src/tools/find-emails.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,cAAc,gBAAgB,CAAA;AAE3C,eAAO,MAAM,qBAAqB,QAOqE,CAAA;AAEvG,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;CAe5B,CAAA;AASD,KAAK,UAAU,GAAG;IAAE,OAAO,EAAE,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAMlF,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CA0C3F"}

package/dist/tools/find-emails.js

@@ -23,9 +23,48 @@ export const findEmailsSchema = {
         .describe('People to find emails for (max 50)'),
     use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically run the best waterfall — recommended for most use cases. Available providers: ${FIND_EMAILS_PROVIDERS.join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 };
+// Split large batches into sequential sub-batches so each HTTP call stays well
+// under the server's bulk wall-clock budget (and thus Cloudflare's ~100s edge
+// cutoff). A single 50-contact call could run long enough to be reset ("Network
+// error", WF2); two ~25-contact calls each return quickly. Matches the server's
+// bulk concurrency cap so each chunk is a single server wave.
+const FIND_EMAILS_CHUNK_SIZE = 25;
+function toolResult(payload, isError) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload) }], isError };
+}
 export async function findEmailsHandler(input) {
-    // Bulk verb returns results positionally with no id echo — re-attach each
-    // person's `id` so callers can still match results back.
-    return callVerb('/email/find', input, { bulkField: 'people', reattachIdField: 'id' });
+    const people = Array.isArray(input.people) ? input.people : [];
+    // Small batch (the common case) — one call, unchanged. Bulk verb returns results
+    // positionally with no id echo, so re-attach each person's `id` to match back.
+    if (people.length <= FIND_EMAILS_CHUNK_SIZE) {
+        return callVerb('/email/find', input, { bulkField: 'people', reattachIdField: 'id' });
+    }
+    // Large batch — chunk sequentially and merge the per-contact results in order.
+    const merged = [];
+    for (let i = 0; i < people.length; i += FIND_EMAILS_CHUNK_SIZE) {
+        const chunk = people.slice(i, i + FIND_EMAILS_CHUNK_SIZE);
+        const res = (await callVerb('/email/find', { ...input, people: chunk }, { bulkField: 'people', reattachIdField: 'id' }));
+        let data;
+        try {
+            data = JSON.parse(res.content[0].text);
+        }
+        catch {
+            data = undefined;
+        }
+        const results = data?.results;
+        if (!Array.isArray(results)) {
+            // Whole-chunk failure (bad request, auth, …) — surface it alongside whatever
+            // we already gathered. Spread errorBody first so the accumulated `results`
+            // always win, even if the error body carries its own (non-array) results key.
+            const errorBody = data && typeof data === 'object' ? data : { error: 'find_emails request failed' };
+            return toolResult({ ...errorBody, results: merged }, true);
+        }
+        merged.push(...results);
+        // A transport/billing error on a chunk (e.g. 402 out of credits) is terminal —
+        // stop rather than burning the remaining chunks.
+        if (res.isError)
+            return toolResult({ results: merged }, true);
+    }
+    return toolResult({ results: merged }, false);
 }
 //# sourceMappingURL=find-emails.js.map

package/dist/tools/find-emails.js.map

@@ -1 +1 @@
-{"version":3,"file":"find-emails.js","sourceRoot":"","sources":["../../src/tools/find-emails.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AAErE,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAA;AAE3C,MAAM,CAAC,MAAM,qBAAqB,GAChC,6DAA6D;IAC7D,mEAAmE;IACnE,0EAA0E;IAC1E,uDAAuD;IACvD,0FAA0F;IAC1F,kHAAkH;IAClH,qGAAqG,CAAA;AAEvG,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM,EAAE,CAAC;SACN,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wEAAwE,CAAC;QACjG,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;QACxD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;QACtD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QAC5E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+EAA+E,CAAC;KAC9H,CAAC,CACH;SACA,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,CAAC,oCAAoC,CAAC;IACjD,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oKAAoK,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,qEAAqE,CAAC;CAClU,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAA8B;IACpE,0EAA0E;IAC1E,yDAAyD;IACzD,OAAO,QAAQ,CAAC,aAAa,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAA;AACvF,CAAC"}
+{"version":3,"file":"find-emails.js","sourceRoot":"","sources":["../../src/tools/find-emails.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-session-usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-session-usage.d.ts","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAEtD,eAAO,MAAM,0BAA0B,QAMuB,CAAA;AAE9D,eAAO,MAAM,qBAAqB,IAAK,CAAA;AAEvC,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GAG3E"}
+{"version":3,"file":"get-session-usage.d.ts","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB,sBAAsB,CAAA;AAEtD,eAAO,MAAM,0BAA0B,QAOY,CAAA;AAEnD,eAAO,MAAM,qBAAqB,IAAK,CAAA;AAMvC,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GA8B3E"}

package/dist/tools/get-session-usage.js

@@ -1,14 +1,45 @@
 import { getSessionUsage } from '../session-usage.js';
+import { callApi } from '../client.js';
 export const getSessionUsageName = 'get_session_usage';
-export const getSessionUsageDescription = 'Report the ColdIQ credits spent so far in THIS conversation (the current MCP session). ' +
-    'Returns the total credits charged, the number of billed calls, a per-endpoint breakdown of where ' +
-    'credits went (highest spend first), and the account balance reported after the most recent billed call. ' +
-    'Use this to answer "how many credits has this chat used" or "what did I spend credits on here". ' +
-    'Note: it counts only calls made during the current session and resets if the conversation restarts; ' +
-    'for the authoritative live balance use get_credit_balance.';
+export const getSessionUsageDescription = 'Report the ColdIQ credits spent so far in this MCP process: total credits charged, billed-call count, ' +
+    'and a per-endpoint breakdown (highest spend first), plus the live authoritative balance for reconciliation. ' +
+    'The session tally is BEST-EFFORT — it sums what each call reported at request time and therefore: (a) cannot ' +
+    'see out-of-band async settlement (webhook refunds/charges that land after the call returns), (b) excludes ' +
+    'transport failures that never reached the server, and (c) persists for the life of the MCP process, so a ' +
+    'reused process can include earlier conversations. Treat session_spend as indicative; use authoritative_balance ' +
+    '(or get_credit_balance) as the source of truth.';
 export const getSessionUsageSchema = {};
+const SESSION_USAGE_NOTE = 'session_spend is a best-effort, header-derived tally for this MCP process; it excludes out-of-band async ' +
+    'settlement and resets only when the process restarts. Reconcile against authoritative_balance (live).';
 export async function getSessionUsageHandler(_input) {
     const usage = getSessionUsage();
-    return { content: [{ type: 'text', text: JSON.stringify({ data: usage }) }] };
+    // Reconcile against the authoritative balance. /me/credits is not billed, so this
+    // call never pollutes the tally. Best-effort: a failure just omits the field.
+    let authoritativeBalance;
+    try {
+        const res = await callApi('GET', '/me/credits');
+        if (res.ok && res.data && typeof res.data === 'object') {
+            const bal = res.data.data?.balance;
+            if (typeof bal === 'number')
+                authoritativeBalance = bal;
+        }
+    }
+    catch {
+        // ignore — reconciliation is best-effort
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    data: {
+                        ...usage,
+                        ...(authoritativeBalance !== undefined ? { authoritative_balance: authoritativeBalance } : {}),
+                        note: SESSION_USAGE_NOTE,
+                    },
+                }),
+            },
+        ],
+    };
 }
 //# sourceMappingURL=get-session-usage.js.map

package/dist/tools/get-session-usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-session-usage.js","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAErD,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAEtD,MAAM,CAAC,MAAM,0BAA0B,GACrC,yFAAyF;IACzF,mGAAmG;IACnG,0GAA0G;IAC1G,kGAAkG;IAClG,sGAAsG;IACtG,4DAA4D,CAAA;AAE9D,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAEvC,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAA+B;IAC1E,MAAM,KAAK,GAAG,eAAe,EAAE,CAAA;IAC/B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAA;AACxF,CAAC"}
+{"version":3,"file":"get-session-usage.js","sourceRoot":"","sources":["../../src/tools/get-session-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAA;AAEtD,MAAM,CAAC,MAAM,0BAA0B,GACrC,wGAAwG;IACxG,8GAA8G;IAC9G,+GAA+G;IAC/G,4GAA4G;IAC5G,2GAA2G;IAC3G,iHAAiH;IACjH,iDAAiD,CAAA;AAEnD,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAEvC,MAAM,kBAAkB,GACtB,2GAA2G;IAC3G,uGAAuG,CAAA;AAEzG,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAA+B;IAC1E,MAAM,KAAK,GAAG,eAAe,EAAE,CAAA;IAE/B,kFAAkF;IAClF,8EAA8E;IAC9E,IAAI,oBAAwC,CAAA;IAC5C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;QAC/C,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,IAAI,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,MAAM,GAAG,GAAI,GAAG,CAAC,IAAyC,CAAC,IAAI,EAAE,OAAO,CAAA;YACxE,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,oBAAoB,GAAG,GAAG,CAAA;QACzD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,yCAAyC;IAC3C,CAAC;IAED,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,IAAI,EAAE;wBACJ,GAAG,KAAK;wBACR,GAAG,CAAC,oBAAoB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC9F,IAAI,EAAE,kBAAkB;qBACzB;iBACF,CAAC;aACH;SACF;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldiq/mcp",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/src/tools/find-emails.ts

@@ -30,8 +30,59 @@ export const findEmailsSchema = {
   use_providers: z.array(z.string()).optional().describe(`Optional ordered list of providers to use. Leave empty to let ColdIQ automatically run the best waterfall — recommended for most use cases. Available providers: ${FIND_EMAILS_PROVIDERS.join(', ')}. Provider names are matched fuzzily, so minor typos are tolerated.`),
 }
 
-export async function findEmailsHandler(input: Record<string, unknown>) {
-  // Bulk verb returns results positionally with no id echo — re-attach each
-  // person's `id` so callers can still match results back.
-  return callVerb('/email/find', input, { bulkField: 'people', reattachIdField: 'id' })
+// Split large batches into sequential sub-batches so each HTTP call stays well
+// under the server's bulk wall-clock budget (and thus Cloudflare's ~100s edge
+// cutoff). A single 50-contact call could run long enough to be reset ("Network
+// error", WF2); two ~25-contact calls each return quickly. Matches the server's
+// bulk concurrency cap so each chunk is a single server wave.
+const FIND_EMAILS_CHUNK_SIZE = 25
+
+type ToolResult = { content: [{ type: 'text'; text: string }]; isError?: boolean }
+
+function toolResult(payload: unknown, isError: boolean): ToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(payload) }], isError }
+}
+
+export async function findEmailsHandler(input: Record<string, unknown>): Promise<ToolResult> {
+  const people = Array.isArray(input.people) ? (input.people as unknown[]) : []
+
+  // Small batch (the common case) — one call, unchanged. Bulk verb returns results
+  // positionally with no id echo, so re-attach each person's `id` to match back.
+  if (people.length <= FIND_EMAILS_CHUNK_SIZE) {
+    return callVerb('/email/find', input, { bulkField: 'people', reattachIdField: 'id' }) as Promise<ToolResult>
+  }
+
+  // Large batch — chunk sequentially and merge the per-contact results in order.
+  const merged: unknown[] = []
+  for (let i = 0; i < people.length; i += FIND_EMAILS_CHUNK_SIZE) {
+    const chunk = people.slice(i, i + FIND_EMAILS_CHUNK_SIZE)
+    const res = (await callVerb(
+      '/email/find',
+      { ...input, people: chunk },
+      { bulkField: 'people', reattachIdField: 'id' },
+    )) as ToolResult
+
+    let data: unknown
+    try {
+      data = JSON.parse(res.content[0].text)
+    } catch {
+      data = undefined
+    }
+    const results = (data as { results?: unknown[] } | undefined)?.results
+
+    if (!Array.isArray(results)) {
+      // Whole-chunk failure (bad request, auth, …) — surface it alongside whatever
+      // we already gathered. Spread errorBody first so the accumulated `results`
+      // always win, even if the error body carries its own (non-array) results key.
+      const errorBody = data && typeof data === 'object' ? (data as object) : { error: 'find_emails request failed' }
+      return toolResult({ ...errorBody, results: merged }, true)
+    }
+    merged.push(...results)
+
+    // A transport/billing error on a chunk (e.g. 402 out of credits) is terminal —
+    // stop rather than burning the remaining chunks.
+    if (res.isError) return toolResult({ results: merged }, true)
+  }
+
+  return toolResult({ results: merged }, false)
 }

package/src/tools/get-session-usage.ts

@@ -1,18 +1,51 @@
 import { getSessionUsage } from '../session-usage.js'
+import { callApi } from '../client.js'
 
 export const getSessionUsageName = 'get_session_usage'
 
 export const getSessionUsageDescription =
-  'Report the ColdIQ credits spent so far in THIS conversation (the current MCP session). ' +
-  'Returns the total credits charged, the number of billed calls, a per-endpoint breakdown of where ' +
-  'credits went (highest spend first), and the account balance reported after the most recent billed call. ' +
-  'Use this to answer "how many credits has this chat used" or "what did I spend credits on here". ' +
-  'Note: it counts only calls made during the current session and resets if the conversation restarts; ' +
-  'for the authoritative live balance use get_credit_balance.'
+  'Report the ColdIQ credits spent so far in this MCP process: total credits charged, billed-call count, ' +
+  'and a per-endpoint breakdown (highest spend first), plus the live authoritative balance for reconciliation. ' +
+  'The session tally is BEST-EFFORT — it sums what each call reported at request time and therefore: (a) cannot ' +
+  'see out-of-band async settlement (webhook refunds/charges that land after the call returns), (b) excludes ' +
+  'transport failures that never reached the server, and (c) persists for the life of the MCP process, so a ' +
+  'reused process can include earlier conversations. Treat session_spend as indicative; use authoritative_balance ' +
+  '(or get_credit_balance) as the source of truth.'
 
 export const getSessionUsageSchema = {}
 
+const SESSION_USAGE_NOTE =
+  'session_spend is a best-effort, header-derived tally for this MCP process; it excludes out-of-band async ' +
+  'settlement and resets only when the process restarts. Reconcile against authoritative_balance (live).'
+
 export async function getSessionUsageHandler(_input: Record<string, unknown>) {
   const usage = getSessionUsage()
-  return { content: [{ type: 'text' as const, text: JSON.stringify({ data: usage }) }] }
+
+  // Reconcile against the authoritative balance. /me/credits is not billed, so this
+  // call never pollutes the tally. Best-effort: a failure just omits the field.
+  let authoritativeBalance: number | undefined
+  try {
+    const res = await callApi('GET', '/me/credits')
+    if (res.ok && res.data && typeof res.data === 'object') {
+      const bal = (res.data as { data?: { balance?: unknown } }).data?.balance
+      if (typeof bal === 'number') authoritativeBalance = bal
+    }
+  } catch {
+    // ignore — reconciliation is best-effort
+  }
+
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({
+          data: {
+            ...usage,
+            ...(authoritativeBalance !== undefined ? { authoritative_balance: authoritativeBalance } : {}),
+            note: SESSION_USAGE_NOTE,
+          },
+        }),
+      },
+    ],
+  }
 }

package/tests/session-usage.test.ts

@@ -6,6 +6,7 @@ import {
   resetSessionUsage,
 } from '../src/session-usage.js'
 import { initClient, callApi } from '../src/client.js'
+import { getSessionUsageHandler } from '../src/tools/get-session-usage.js'
 
 describe('session-usage accumulator', () => {
   beforeEach(() => {
@@ -128,3 +129,34 @@ describe('callApi records credit charges into session usage', () => {
     expect(getSessionUsage().billedCalls).toBe(0)
   })
 })
+
+// --- B2: get_session_usage reconciles against the authoritative balance ------
+describe('get_session_usage handler reconciliation (B2)', () => {
+  const originalFetch = globalThis.fetch
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+    resetSessionUsage(0)
+  })
+  afterEach(() => { globalThis.fetch = originalFetch })
+
+  it('attaches the live authoritative_balance and a best-effort note', async () => {
+    recordCharge('/email/find', 2, 500) // header-derived tally (may drift from real balance)
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ data: { balance: 480.5, usedThisMonth: 20 } }), { status: 200 }),
+    ) as typeof fetch
+
+    const res = await getSessionUsageHandler({})
+    const payload = JSON.parse(res.content[0].text).data
+    expect(payload.totalCreditsCharged).toBe(2)
+    expect(payload.authoritative_balance).toBe(480.5) // reconciliation source of truth
+    expect(payload.note).toMatch(/best-effort/i)
+  })
+
+  it('still returns the tally + note when the balance lookup fails (best-effort)', async () => {
+    globalThis.fetch = vi.fn(async () => new Response('nope', { status: 502 })) as typeof fetch
+    const res = await getSessionUsageHandler({})
+    const payload = JSON.parse(res.content[0].text).data
+    expect(payload.authoritative_balance).toBeUndefined()
+    expect(payload.note).toBeTruthy()
+  })
+})

package/tests/tools/find-emails.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// Mock the verb client so we test the handler's chunk/merge logic directly,
+// without building real envelopes or touching the network.
+const callVerbMock = vi.fn()
+vi.mock('../../src/verb-client.js', () => ({
+  callVerb: (...args: unknown[]) => callVerbMock(...args),
+}))
+
+import { findEmailsHandler } from '../../src/tools/find-emails.js'
+
+type Person = { id: string; domain?: string }
+const peopleOf = (n: number): Person[] => Array.from({ length: n }, (_, i) => ({ id: `p${i}`, domain: 'coldiq.com' }))
+
+// Build the ToolResult callVerb would return: one result per person in the chunk.
+function chunkResult(input: Record<string, unknown>, opts?: { isError?: boolean }) {
+  const people = (input.people as Person[]) ?? []
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify({ results: people.map((p) => ({ id: p.id, email: `${p.id}@x.com` })) }) }],
+    isError: opts?.isError ?? false,
+  }
+}
+
+beforeEach(() => {
+  callVerbMock.mockReset()
+  callVerbMock.mockImplementation((_path: string, input: Record<string, unknown>) => Promise.resolve(chunkResult(input)))
+})
+
+describe('find_emails auto-chunking', () => {
+  it('≤25 people → a single passthrough call', async () => {
+    await findEmailsHandler({ people: peopleOf(25) })
+    expect(callVerbMock).toHaveBeenCalledTimes(1)
+    expect((callVerbMock.mock.calls[0][1] as { people: Person[] }).people).toHaveLength(25)
+  })
+
+  it('>25 people → sequential chunks of ≤25, merged in order', async () => {
+    const res = await findEmailsHandler({ people: peopleOf(60) })
+
+    // 60 → 25 + 25 + 10
+    expect(callVerbMock).toHaveBeenCalledTimes(3)
+    expect((callVerbMock.mock.calls[0][1] as { people: Person[] }).people).toHaveLength(25)
+    expect((callVerbMock.mock.calls[1][1] as { people: Person[] }).people).toHaveLength(25)
+    expect((callVerbMock.mock.calls[2][1] as { people: Person[] }).people).toHaveLength(10)
+
+    const data = JSON.parse(res.content[0].text)
+    expect(data.results).toHaveLength(60)
+    // Order preserved across chunks.
+    expect(data.results.map((r: { id: string }) => r.id)).toEqual(peopleOf(60).map((p) => p.id))
+    expect(res.isError).toBe(false)
+  })
+
+  it('forwards use_providers to every chunk', async () => {
+    await findEmailsHandler({ people: peopleOf(30), use_providers: ['limadata-work-email'] })
+    expect(callVerbMock).toHaveBeenCalledTimes(2)
+    for (const call of callVerbMock.mock.calls) {
+      expect((call[1] as { use_providers: string[] }).use_providers).toEqual(['limadata-work-email'])
+    }
+  })
+
+  it('stops early and surfaces the error when a chunk fails terminally (e.g. 402)', async () => {
+    callVerbMock
+      .mockImplementationOnce((_p: string, input: Record<string, unknown>) => Promise.resolve(chunkResult(input)))
+      .mockImplementationOnce((_p: string, input: Record<string, unknown>) => Promise.resolve(chunkResult(input, { isError: true })))
+    const res = await findEmailsHandler({ people: peopleOf(60) })
+
+    // 1st chunk ok, 2nd is a terminal error → stop (3rd chunk never sent).
+    expect(callVerbMock).toHaveBeenCalledTimes(2)
+    expect(res.isError).toBe(true)
+    const data = JSON.parse(res.content[0].text)
+    expect(data.results).toHaveLength(50) // partial results preserved
+  })
+})