onbuzz 4.10.0 → 5.0.0

package/src/tools/__tests__/composioTool.findAction.test.js

@@ -40,7 +40,7 @@ jest.unstable_mockModule('../../services/embeddings/indexers/composioIndexer.js'
   composioActionToText: () => '',
 }));
 
-const { default: ComposioTool } = await import('../composioTool.js');
+const { default: ComposioTool, __resetAutoIndexForTests } = await import('../composioTool.js');
 const composioService = await import('../../services/composioService.js');
 
 // composioService.getClient() guards against silent key-rotation by
@@ -59,6 +59,7 @@ afterEach(() => {
   else process.env.COMPOSIO_API_KEY = savedComposioKey;
   composioService._resetForTests();
   if (currentFetchStub) { currentFetchStub.restore(); currentFetchStub = null; }
+  __resetAutoIndexForTests();
 });
 
 /**
@@ -217,7 +218,9 @@ describe('composioTool — find-action execution', () => {
     expect(r.mode).toBe('substring-fallback');
     expect(r.fallbackCause).toBe('index-empty');
     expect(r.warning).toMatch(/catalog index is empty/i);
-    expect(r.warning).toMatch(/backfill-actions-index/);
+    // The index now self-heals: the warning says it's building in the
+    // background (rather than telling the agent to run backfill manually).
+    expect(r.warning).toMatch(/building the semantic index/i);
     // Search is skipped when the index is empty — don't burn an
     // embedding call we know will be useless.
     expect(mockIndexerInstance.search).not.toHaveBeenCalled();
@@ -320,6 +323,29 @@ describe('composioTool — find-action substring fallback', () => {
     expect(typeof r.hits[0].score).toBe('number');
   });
 
+  test('synonyms + name-weighting rank the read action above a list action', async () => {
+    // Reproduces the live miss: query "read my gmail emails" ranked
+    // GMAIL_LIST_LABELS over GMAIL_FETCH_EMAILS under plain token overlap
+    // (both matched "gmail"). "read"→fetch synonym + "emails" exact +
+    // name-weighting must now put the fetch action first.
+    const { tool } = makeTool({
+      embeddingsEnabled: false,
+      fetchScenarios: {
+        tools: [
+          { slug: 'GMAIL_LIST_LABELS', display_name: 'Modify email labels', description: 'Add or remove labels on an email', toolkit: { slug: 'gmail' } },
+          { slug: 'GMAIL_FETCH_EMAILS', display_name: 'Fetch emails', description: 'Fetch the most recent emails from the inbox', toolkit: { slug: 'gmail' } },
+        ],
+      },
+    });
+    const r = await tool.execute(
+      { actions: [{ type: 'find-action', query: 'read my gmail emails inbox', toolkitSlug: 'gmail', topK: 2 }] },
+      { agentId: 'a1' },
+    );
+    expect(r.success).toBe(true);
+    expect(r.mode).toBe('substring-fallback');
+    expect(r.hits[0].actionSlug).toBe('GMAIL_FETCH_EMAILS');
+  });
+
   test('toolkitSlug pin restricts the scan to a single toolkit', async () => {
     const { tool, sdkClient } = makeTool({ embeddingsEnabled: false });
     const r = await tool.execute(
@@ -334,7 +360,7 @@ describe('composioTool — find-action substring fallback', () => {
     // …and we call tools.list exactly once, for that one toolkit.
     expect(sdkClient.tools.list).toHaveBeenCalledTimes(1);
     expect(sdkClient.tools.list).toHaveBeenCalledWith(
-      expect.objectContaining({ toolkit_slugs: 'slack', user_id: 'a1' })
+      expect.objectContaining({ toolkit_slug: 'slack', user_id: 'operator' })
     );
     // Every returned hit belongs to the pinned toolkit.
     for (const h of r.hits) {
@@ -403,7 +429,7 @@ describe('composioTool — backfill-actions-index', () => {
     // Calling the fetcher should route through composioService → REST.
     await fetcher('slack');
     expect(sdkClient.tools.list).toHaveBeenCalledWith(
-      expect.objectContaining({ toolkit_slugs: 'slack', user_id: 'a1' })
+      expect.objectContaining({ toolkit_slug: 'slack', user_id: 'operator' })
     );
     expect(r.success).toBe(true);
     expect(r.indexedActions).toBe(6);
@@ -446,3 +472,68 @@ describe('composioTool — backfill-actions-index', () => {
     expect(r.message).toMatch(/1 toolkits failed/);
   });
 });
+
+describe('composioTool — auto-build semantic index (connected toolkits)', () => {
+  beforeEach(() => __resetAutoIndexForTests());
+  afterAll(() => __resetAutoIndexForTests());
+
+  function connClient(toolkitSlugs) {
+    return {
+      connectedAccounts: {
+        list: jest.fn().mockResolvedValue({
+          items: toolkitSlugs.map(s => ({ toolkit: { slug: s }, status: 'ACTIVE' })),
+        }),
+      },
+      tools: { execute: jest.fn() },
+    };
+  }
+
+  test('builds the index for connected toolkits exactly once (deduped)', async () => {
+    const { tool } = makeTool({ embeddingsEnabled: true });
+    composioService._injectClientForTests(connClient(['gmail', 'gmail', 'slack']));
+
+    const p1 = tool._maybeAutoBuildIndex('operator');
+    const p2 = tool._maybeAutoBuildIndex('operator'); // concurrent → same handle, no 2nd build
+    expect(p2).toBe(p1);
+    await p1;
+
+    expect(mockIndexerInstance.indexCatalog).toHaveBeenCalledTimes(1);
+    const [toolkits, fetcher] = mockIndexerInstance.indexCatalog.mock.calls[0];
+    expect(toolkits.map(t => t.slug).sort()).toEqual(['gmail', 'slack']); // deduped, {slug} shape
+    expect(typeof fetcher).toBe('function');
+  });
+
+  test('skips when nothing is connected, and a later call retries once an app connects', async () => {
+    const { tool } = makeTool({ embeddingsEnabled: true });
+    composioService._injectClientForTests(connClient([]));
+    await tool._maybeAutoBuildIndex('operator');
+    expect(mockIndexerInstance.indexCatalog).not.toHaveBeenCalled();
+
+    composioService._injectClientForTests(connClient(['gmail']));
+    await tool._maybeAutoBuildIndex('operator');
+    expect(mockIndexerInstance.indexCatalog).toHaveBeenCalledTimes(1);
+  });
+
+  test('no-op when embeddings are disabled', () => {
+    const { tool } = makeTool({ embeddingsEnabled: false });
+    expect(tool._maybeAutoBuildIndex('operator')).toBe(null);
+    expect(mockIndexerInstance.indexCatalog).not.toHaveBeenCalled();
+  });
+
+  test('find-action with an empty index triggers the background build', async () => {
+    const { tool } = makeTool({ embeddingsEnabled: true });
+    mockIndexerInstance.stats.mockResolvedValue({ count: 0, enabled: true }); // empty index
+    composioService._injectClientForTests(connClient(['gmail']));
+
+    const r = await tool.execute(
+      { actions: [{ type: 'find-action', query: 'read gmail', toolkitSlug: 'gmail' }] },
+      { agentId: 'a1' },
+    );
+    expect(r.mode).toBe('substring-fallback');   // immediate result is still substring…
+    expect(r.fallbackCause).toBe('index-empty');
+    // …but a background build was kicked off. Awaiting the deduped handle
+    // (same in-flight promise) waits for it to finish.
+    await tool._maybeAutoBuildIndex('operator');
+    expect(mockIndexerInstance.indexCatalog).toHaveBeenCalledTimes(1);
+  });
+});

package/src/tools/__tests__/composioTool.payloadBloat.test.js

@@ -0,0 +1,427 @@
+/**
+ * PROOF TEST for the persistent Composio failure.
+ *
+ * Two exported conversations (Coder-Quick-8453 2026-06-05 and
+ * Agent-Spark-7331 2026-05-28) showed agents getting trapped the moment
+ * they touched Composio. Forensics on the exports:
+ *
+ *   - "read my last 5 gmail inbox items" produced a 64,307,740-char
+ *     conversation. A single `list-toolkits` result was 1,091,452 chars
+ *     (~1 MB); one composio result hit 56,662,194 chars (~56 MB). The
+ *     catalog has ~1043 toolkits, each returned with FULL metadata
+ *     (description, logo, categories, timestamps, counts, auth-scheme
+ *     arrays). The agent's context overflowed, it couldn't find Gmail in
+ *     the wall of text, re-called discovery over and over, and never
+ *     reached the actual task.
+ *
+ *   - `list-tools` was just as bad: the tool objects triple-duplicated the
+ *     full JSON input schema (inputParameters/input/parameters).
+ *
+ * The fix projects discovery results to a compact shape and caps the
+ * count, and adds get-action-schema for on-demand single-action schemas.
+ *
+ * THIS TEST reconstructs the failure scale (1043 toolkits, fat tool
+ * schemas) and asserts the post-fix payloads are KB, not MB — i.e. it
+ * proves the hypothesis: the bloat was the bug, and the projection cures
+ * it. If a future change reintroduces the bloat, this test fails loudly.
+ */
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import ComposioTool, { compactToolkit, compactTool, countItems } from '../composioTool.js';
+import * as composioService from '../../services/composioService.js';
+
+const SILENT_LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+
+/** A realistic FAT toolkit — the exact shape composioService._camelizeToolkit
+ *  produced and shipped to the agent before the fix. ~1 KB each. */
+function fatToolkit(i) {
+  const longDesc =
+    `Toolkit number ${i} is a fully-featured third-party integration providing ` +
+    'a broad surface of actions for productivity, messaging, storage, and ' +
+    'automation. It supports OAuth2 and API-key auth schemes, exposes dozens of ' +
+    'actions and triggers, and integrates with the rest of the suite. '.repeat(3);
+  return {
+    slug: `toolkit_${i}`,
+    name: `Toolkit ${i}`,
+    meta: {
+      description: longDesc,
+      logo: `https://logos.composio.dev/api/toolkit_${i}`,
+      categories: [{ id: 'productivity', name: 'productivity' }, { id: 'email', name: 'email' }],
+      created_at: '2024-01-01T00:00:00.000Z',
+      updated_at: '2026-06-01T00:00:00.000Z',
+      tools_count: 47,
+      triggers_count: 12,
+      app_url: `https://app.example.com/toolkit_${i}`,
+    },
+    is_local_toolkit: false,
+    auth_schemes: ['OAUTH2', 'API_KEY', 'BEARER_TOKEN'],
+    composio_managed_auth_schemes: ['OAUTH2'],
+    no_auth: false,
+  };
+}
+
+/** A realistic FAT tool/action with a big JSON input schema (the
+ *  inputParameters that the old shape duplicated three times). */
+function fatTool(i) {
+  const properties = {};
+  for (let p = 0; p < 25; p++) {
+    properties[`field_${p}`] = {
+      type: 'string',
+      description: `Field ${p} controls some aspect of the action and accepts a ` +
+        'string value with the following detailed semantics and constraints. '.repeat(2),
+      examples: [`example_${p}_a`, `example_${p}_b`],
+    };
+  }
+  const schema = { type: 'object', properties, required: ['field_0', 'field_1'] };
+  return {
+    slug: `ACTION_${i}`,
+    name: `Action ${i}`,
+    display_name: `Action ${i}`,
+    description: `Performs operation ${i} against the toolkit with many configurable parameters.`,
+    input_parameters: schema,
+    output_parameters: { type: 'object', properties: { result: { type: 'string' } } },
+    toolkit: { slug: 'gmail' },
+    deprecated: false,
+    tags: ['email', 'productivity', 'automation'],
+    scopes: ['read', 'write'],
+  };
+}
+
+const CATALOG_SIZE = 1043;   // the real catalog scale from the comment in composioService
+const TOOLS_PER_TOOLKIT = 80;
+
+function stubFatFetch() {
+  const original = global.fetch;
+  const toolkits = Array.from({ length: CATALOG_SIZE }, (_, i) => fatToolkit(i));
+  const tools = Array.from({ length: TOOLS_PER_TOOLKIT }, (_, i) => fatTool(i));
+  global.fetch = jest.fn(async (url) => {
+    const u = url instanceof URL ? url : new URL(String(url));
+    const items = u.pathname === '/api/v3.1/toolkits' ? toolkits
+      : u.pathname === '/api/v3.1/tools' ? tools
+        : [];
+    return new Response(JSON.stringify({ items, next_cursor: null }), {
+      status: 200, headers: { 'content-type': 'application/json' },
+    });
+  });
+  return { toolkits, tools, restore: () => { global.fetch = original; } };
+}
+
+function makeTool() {
+  const tool = new ComposioTool({}, SILENT_LOGGER);
+  // list-toolkits / list-tools go through composioService REST → stubbed fetch.
+  // get-action-schema also uses listTools. No SDK client needed for these.
+  return tool;
+}
+
+let savedKey;
+let stub;
+beforeEach(() => {
+  savedKey = process.env.COMPOSIO_API_KEY;
+  process.env.COMPOSIO_API_KEY = 'test-key';
+  stub = stubFatFetch();
+});
+afterEach(() => {
+  if (savedKey === undefined) delete process.env.COMPOSIO_API_KEY;
+  else process.env.COMPOSIO_API_KEY = savedKey;
+  stub.restore();
+  composioService._resetForTests();
+});
+
+const KB = 1024;
+
+describe('Composio discovery payload bloat — proof of fix', () => {
+  test('BASELINE: a fat 1043-toolkit catalog serializes to ~1 MB (this WAS shipped to the agent)', () => {
+    // Demonstrates the disease: the raw catalog the service produces is huge.
+    const rawBytes = JSON.stringify(stub.toolkits).length;
+    expect(rawBytes).toBeGreaterThan(900 * KB);   // ~1 MB, matches the 1,091,452-char export
+  });
+
+  test('FIX: list-toolkits returns a COMPACT, CAPPED payload (KB, not MB)', async () => {
+    const tool = makeTool();
+    const r = await tool.execute({ actions: [{ type: 'list-toolkits' }] }, { agentId: 'a' });
+    expect(r.success).toBe(true);
+
+    const result = r.results ? r.results[0] : r;
+    // Cap holds: never dump the whole catalog.
+    expect(result.returned).toBeLessThanOrEqual(200);
+    expect(result.total).toBe(CATALOG_SIZE);
+    expect(result.truncated).toBe(true);
+    expect(result.hint).toMatch(/find-action/);
+
+    // The serialized payload the AGENT sees must be small.
+    const bytes = JSON.stringify(result).length;
+    expect(bytes).toBeLessThan(30 * KB);   // was ~1 MB; now a few KB
+
+    // Each toolkit is projected to the routing-essential fields only.
+    const tk = result.toolkits[0];
+    expect(Object.keys(tk).sort()).toEqual(['category', 'name', 'slug']);
+    expect(tk).not.toHaveProperty('meta');
+    expect(tk).not.toHaveProperty('description');
+    expect(tk).not.toHaveProperty('authSchemes');
+  });
+
+  test('FIX: list-tools returns compact actions WITHOUT input schemas', async () => {
+    const tool = makeTool();
+    const r = await tool.execute(
+      { actions: [{ type: 'list-tools', toolkitSlug: 'gmail' }] },
+      { agentId: 'a' },
+    );
+    const result = r.results ? r.results[0] : r;
+    expect(result.success).toBe(true);
+
+    const bytes = JSON.stringify(result).length;
+    expect(bytes).toBeLessThan(20 * KB);
+
+    const t = result.tools[0];
+    // slug + displayName + (clamped) description — NO schemas.
+    expect(t).toHaveProperty('slug');
+    expect(t).toHaveProperty('displayName');
+    expect(t).not.toHaveProperty('inputParameters');
+    expect(t).not.toHaveProperty('input');
+    expect(t).not.toHaveProperty('parameters');
+    expect(result.hint).toMatch(/get-action-schema/);
+  });
+
+  test('FIX: get-action-schema returns ONE action\'s full schema on demand', async () => {
+    const tool = makeTool();
+    const r = await tool.execute(
+      { actions: [{ type: 'get-action-schema', toolkitSlug: 'gmail', actionSlug: 'ACTION_3' }] },
+      { agentId: 'a' },
+    );
+    const result = r.results ? r.results[0] : r;
+    expect(result.success).toBe(true);
+    expect(result.actionSlug).toBe('ACTION_3');
+    // THIS one carries the full schema the agent needs to build execute args.
+    expect(result.inputParameters).toBeDefined();
+    expect(result.inputParameters.properties).toBeDefined();
+    // Single-action schema is bounded — not the whole toolkit's schemas.
+    expect(JSON.stringify(result).length).toBeLessThan(40 * KB);
+  });
+
+  test('get-action-schema 404s clearly when the action slug is unknown', async () => {
+    const tool = makeTool();
+    const r = await tool.execute(
+      { actions: [{ type: 'get-action-schema', toolkitSlug: 'gmail', actionSlug: 'NOPE' }] },
+      { agentId: 'a' },
+    );
+    const result = r.results ? r.results[0] : r;
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/not found/i);
+    expect(result.error).toMatch(/list-tools/);
+  });
+
+  test('the AGGREGATE size collapse: compact discovery is <2% of the raw catalog', async () => {
+    const rawCatalogBytes = JSON.stringify(stub.toolkits).length;
+    const tool = makeTool();
+    const r = await tool.execute({ actions: [{ type: 'list-toolkits' }] }, { agentId: 'a' });
+    const result = r.results ? r.results[0] : r;
+    const compactBytes = JSON.stringify(result).length;
+    const ratio = compactBytes / rawCatalogBytes;
+    expect(ratio).toBeLessThan(0.02);   // >98% reduction — the loop-killer
+  });
+});
+
+describe('compactToolkit / compactTool projections (unit)', () => {
+  test('compactToolkit keeps slug/name/category, drops the rest', () => {
+    const out = compactToolkit(composioServiceCamelize(fatToolkit(7)));
+    expect(out).toEqual({ slug: 'toolkit_7', name: 'Toolkit 7', category: 'productivity' });
+  });
+
+  test('compactToolkit surfaces noAuth:true when present', () => {
+    const out = compactToolkit({ slug: 's', name: 'n', noAuth: true });
+    expect(out.noAuth).toBe(true);
+  });
+
+  test('compactToolkit handles missing categories', () => {
+    const out = compactToolkit({ slug: 's', name: 'n' });
+    expect(out).toEqual({ slug: 's', name: 'n' });
+  });
+
+  test('compactToolkit passes through non-objects unchanged', () => {
+    expect(compactToolkit(null)).toBe(null);
+    expect(compactToolkit('x')).toBe('x');
+  });
+
+  test('compactTool keeps slug/displayName/clamped description, drops schemas', () => {
+    const out = compactTool({
+      slug: 'A', name: 'A', displayName: 'Action A',
+      description: 'x'.repeat(500),
+      inputParameters: { huge: true }, input: { huge: true }, parameters: { huge: true },
+    });
+    expect(out.slug).toBe('A');
+    expect(out.displayName).toBe('Action A');
+    expect(out.description.length).toBeLessThanOrEqual(161); // 160 + ellipsis
+    expect(out).not.toHaveProperty('inputParameters');
+  });
+
+  test('compactTool falls back to name when displayName missing + omits empty description', () => {
+    const out = compactTool({ slug: 'A', name: 'NameOnly' });
+    expect(out.displayName).toBe('NameOnly');
+    expect(out).not.toHaveProperty('description');
+  });
+
+  test('compactTool passes through non-objects unchanged', () => {
+    expect(compactTool(undefined)).toBe(undefined);
+  });
+
+  test('countItems finds the collection size across common shapes', () => {
+    expect(countItems([1, 2, 3])).toBe(3);
+    expect(countItems({ messages: [1, 2, 3, 4, 5] })).toBe(5);   // gmail fetch shape
+    expect(countItems({ items: [1, 2] })).toBe(2);
+    expect(countItems({ response_data: { messages: [1, 2, 3] } })).toBe(3); // nested
+    expect(countItems({ ok: true })).toBe(null);                 // no collection
+    expect(countItems(null)).toBe(null);
+    expect(countItems('x')).toBe(null);
+  });
+});
+
+describe('discovery discipline + on-demand-schema wiring', () => {
+  test('getDescription steers the agent: find-action first, get-action-schema before execute', () => {
+    const tool = new ComposioTool({}, SILENT_LOGGER);
+    const desc = tool.getDescription();
+    // The new guidance block exists and names the cheap-first workflow.
+    expect(desc).toMatch(/DISCOVERY DISCIPLINE/);
+    expect(desc).toMatch(/find-action/);
+    expect(desc).toMatch(/get-action-schema/);
+    // The cap is interpolated (not a literal ${...}), so the agent is told
+    // the real number it will see.
+    expect(desc).toContain('200');
+    expect(desc).not.toContain('${');
+  });
+
+  test('getDescription steers the fast path and discourages redundant discovery', () => {
+    const tool = new ComposioTool({}, SILENT_LOGGER);
+    const desc = tool.getDescription();
+    // Two-step fast path + explicit don'ts that fix the observed redundancy.
+    expect(desc).toMatch(/fast path/i);
+    expect(desc).toMatch(/connection-status/);          // mentions it…
+    expect(desc).toMatch(/Don't call \*\*connection-status\*\* preemptively/);
+    expect(desc).toMatch(/same discovery action twice/i);
+  });
+
+  test('get-action-schema is a supported action and requires BOTH slugs', () => {
+    const tool = new ComposioTool({}, SILENT_LOGGER);
+    const missingAction = tool.customValidateParameters({
+      actions: [{ type: 'get-action-schema', toolkitSlug: 'gmail' }],
+    });
+    expect(missingAction.valid).toBe(false);
+    expect(missingAction.errors.join(' ')).toMatch(/actionSlug/);
+
+    const missingToolkit = tool.customValidateParameters({
+      actions: [{ type: 'get-action-schema', actionSlug: 'GMAIL_SEND' }],
+    });
+    expect(missingToolkit.valid).toBe(false);
+    expect(missingToolkit.errors.join(' ')).toMatch(/toolkitSlug/);
+
+    const ok = tool.customValidateParameters({
+      actions: [{ type: 'get-action-schema', toolkitSlug: 'gmail', actionSlug: 'GMAIL_SEND' }],
+    });
+    expect(ok.valid).toBe(true);
+  });
+});
+
+describe('discovery surfaces service errors instead of masking them', () => {
+  test('list-toolkits passes through a service failure', async () => {
+    // Force the REST layer to fail; the compact path must not pretend success.
+    global.fetch = jest.fn(async () => { throw new Error('composio upstream down'); });
+    const tool = makeTool();
+    const r = await tool.execute({ actions: [{ type: 'list-toolkits' }] }, { agentId: 'a' });
+    expect(r.success).toBe(false);
+    expect(r.action).toBe('list-toolkits');
+    expect(r.error).toMatch(/upstream down/);
+  });
+
+  test('get-action-schema passes through a service failure', async () => {
+    global.fetch = jest.fn(async () => { throw new Error('composio upstream down'); });
+    const tool = makeTool();
+    const r = await tool.execute(
+      { actions: [{ type: 'get-action-schema', toolkitSlug: 'gmail', actionSlug: 'ACTION_1' }] },
+      { agentId: 'a' },
+    );
+    expect(r.success).toBe(false);
+    expect(r.action).toBe('get-action-schema');
+    expect(r.error).toMatch(/upstream down/);
+  });
+});
+
+describe('defensive guards (pre-existing branches kept green)', () => {
+  test('getRequiredParameters defers to per-action validation', () => {
+    const tool = new ComposioTool({}, SILENT_LOGGER);
+    expect(tool.getRequiredParameters()).toEqual([]);
+  });
+
+  test('customValidateParameters: empty params → action required', () => {
+    const tool = new ComposioTool({}, SILENT_LOGGER);
+    const v = tool.customValidateParameters({});
+    expect(v.valid).toBe(false);
+    expect(v.errors.join(' ')).toMatch(/action is required/);
+  });
+
+  test('customValidateParameters: singular {action} is forgiven into {actions:[…]}', () => {
+    const tool = new ComposioTool({}, SILENT_LOGGER);
+    const v = tool.customValidateParameters({ action: 'list-toolkits' });
+    expect(v.valid).toBe(true);
+  });
+
+  test('customValidateParameters: an action missing its type is rejected', () => {
+    const tool = new ComposioTool({}, SILENT_LOGGER);
+    const v = tool.customValidateParameters({ actions: [{}] });
+    expect(v.valid).toBe(false);
+    expect(v.errors.join(' ')).toMatch(/type is required/);
+  });
+
+  test('_executeFindAction guards an empty query', async () => {
+    const tool = new ComposioTool({}, SILENT_LOGGER);
+    const r = await tool._executeFindAction({ query: '   ' }, { agentId: 'a' });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/query is required/);
+  });
+
+  test('_dispatch returns a clear error for an unknown action type', async () => {
+    const tool = new ComposioTool({}, SILENT_LOGGER);
+    const r = await tool._dispatch({}, 'user', { type: 'no-such-action' });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/Unknown composio action/);
+  });
+
+  test('_dispatch wraps a thrown handler error into a structured result', async () => {
+    const tool = new ComposioTool({}, SILENT_LOGGER);
+    tool._executeFindAction = async () => { throw new Error('boom inside handler'); };
+    const r = await tool._dispatch({}, 'user', { type: 'find-action', query: 'x' });
+    expect(r.success).toBe(false);
+    expect(r.action).toBe('find-action');
+    expect(r.error).toMatch(/boom inside handler/);
+  });
+
+  test('batched execute isolates a throwing action without failing the batch call', async () => {
+    const tool = makeTool();
+    // Force the dispatch itself to throw (not return) so the multi-action
+    // loop's own try/catch is exercised.
+    tool._dispatch = async () => { throw new Error('dispatch blew up'); };
+    const r = await tool.execute(
+      { actions: [{ type: 'list-toolkits' }, { type: 'list-toolkits' }] },
+      { agentId: 'a' },
+    );
+    expect(r.batched).toBe(true);
+    expect(r.success).toBe(false);
+    expect(r.results).toHaveLength(2);
+    expect(r.results.every(x => x.success === false)).toBe(true);
+    expect(r.results[0].error).toMatch(/dispatch blew up/);
+  });
+});
+
+/** Mirror composioService._camelizeToolkit just for the projection unit test
+ *  (the service function is module-private; the shape is stable and asserted
+ *  by the end-to-end tests above which DO go through the real service). */
+function composioServiceCamelize(t) {
+  return {
+    slug: t.slug,
+    name: t.name,
+    description: t.meta?.description,
+    meta: t.meta ? {
+      description: t.meta.description,
+      logo: t.meta.logo,
+      categories: t.meta.categories,
+    } : undefined,
+    noAuth: t.no_auth,
+  };
+}

package/src/tools/__tests__/composioTool.test.js

@@ -240,8 +240,9 @@ describe('ComposioTool — actions', () => {
     expect(r.success).toBe(true);
     const call = tool._fetchStub.calls.find(c => c.path === '/api/v3.1/tools');
     expect(call).toBeDefined();
-    expect(call.query.toolkit_slugs).toBe('github');
-    expect(call.query.user_id).toBe('agent-42');
+    expect(call.query.toolkit_slug).toBe('github');
+    // All agents act as the shared 'operator' entity, not their agentId.
+    expect(call.query.user_id).toBe('operator');
   });
 
   test('connect returns a Connect Link URL and connectionId via the new /link endpoint', async () => {
@@ -255,7 +256,7 @@ describe('ComposioTool — actions', () => {
     // then call connectedAccounts.link (the supported endpoint as of
     // 2026-05-28 — the previous .initiate path was deprecated).
     expect(client.connectedAccounts.link).toHaveBeenCalledWith(
-      'agent-99', 'auth-cfg-existing', {}
+      'operator', 'auth-cfg-existing', {}
     );
   });
 
@@ -291,10 +292,28 @@ describe('ComposioTool — actions', () => {
     expect(r.output).toMatchObject({ issueNumber: 42 });
     expect(client.tools.execute).toHaveBeenCalledWith(
       'GITHUB_CREATE_AN_ISSUE',
-      { userId: 'agent-1', arguments: { owner: 'acme', repo: 'api', title: 'Bug' } }
+      {
+        userId: 'operator',
+        arguments: { owner: 'acme', repo: 'api', title: 'Bug' },
+        version: 'latest',
+        dangerouslySkipVersionCheck: true,
+      }
     );
   });
 
+  test('execute surfaces itemCount when the action returns a collection', async () => {
+    // Fixes the "summarised 3 of 5" under-read: the agent gets an explicit
+    // count of how many items came back.
+    const client = makeMockClient();
+    client.tools.execute = jest.fn().mockResolvedValue({ successful: true, data: { messages: [1, 2, 3, 4, 5] } });
+    const tool = makeTool({ client });
+    const r = await tool.execute({
+      actions: [{ type: 'execute', toolkitSlug: 'gmail', actionSlug: 'GMAIL_FETCH_EMAILS', arguments: {} }],
+    }, { agentId: 'a' });
+    expect(r.success).toBe(true);
+    expect(r.itemCount).toBe(5);
+  });
+
   test('execute surfaces upstream errors structurally', async () => {
     const client = makeMockClient();
     client.tools.execute.mockResolvedValueOnce({ successful: false, error: 'rate limited' });
@@ -345,28 +364,38 @@ describe('ComposioTool — batched execution', () => {
   });
 });
 
-describe('ComposioTool — userId scoping', () => {
-  test('agentId is used as Composio userId', async () => {
+describe('ComposioTool — userId scoping (shared entity)', () => {
+  // All agents act as ONE shared Composio entity ('operator' by default) so
+  // they can use connections the human set up once. The agentId is NOT used
+  // as the Composio userId — doing so was the ConnectedAccountNotFound bug.
+  test('uses the shared operator entity regardless of agentId', async () => {
     const client = makeMockClient();
     const tool = makeTool({ client });
     await tool.execute({ actions: [{ type: 'execute', toolkitSlug: 'gh', actionSlug: 'X', arguments: {} }] }, { agentId: 'agent-zeta' });
     expect(client.tools.execute).toHaveBeenCalledWith(
       'X',
-      expect.objectContaining({ userId: 'agent-zeta' })
+      expect.objectContaining({ userId: 'operator' })
     );
   });
 
-  test('falls back to default-user when agentId is missing (no crash)', async () => {
+  test('still uses the shared entity when agentId is missing (no crash)', async () => {
     const client = makeMockClient();
     const tool = makeTool({ client });
     await tool.execute({ actions: [{ type: 'list-toolkits' }] }, {});
-    // The fallback userId is used internally; list-toolkits doesn't pass
-    // it explicitly to the SDK in this implementation, but we verified
-    // no crash. Spot-check with execute too:
     await tool.execute({ actions: [{ type: 'execute', toolkitSlug: 'gh', actionSlug: 'X', arguments: {} }] }, {});
     expect(client.tools.execute).toHaveBeenCalledWith(
       'X',
-      expect.objectContaining({ userId: 'default-user' })
+      expect.objectContaining({ userId: 'operator' })
+    );
+  });
+
+  test('execute passes a toolkit version so composio-core does not reject it', async () => {
+    const client = makeMockClient();
+    const tool = makeTool({ client });
+    await tool.execute({ actions: [{ type: 'execute', toolkitSlug: 'gh', actionSlug: 'X', arguments: {} }] }, { agentId: 'a' });
+    expect(client.tools.execute).toHaveBeenCalledWith(
+      'X',
+      expect.objectContaining({ version: 'latest', dangerouslySkipVersionCheck: true })
     );
   });
 });