Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

158 KB
Raw Blame
import { afterEach, describe, expect, test } from "bun:test";
import {
  BrokerAccountGoneError,
  BrokerRefusalError,
} from "../src/plugins/broker";
import {
  askAction,
  type ComposioAction,
  type ComposioActions,
  type ComposioResult,
  callTool,
  effectOf,
  LISTING_LIMIT,
  listNeedsCredential,
  listTools,
  toolkitOf,
  useComposioClient,
  vendorSentence,
  withheldArguments,
} from "../src/plugins/composio";
import { MAX_RESULT_CHARS } from "../src/plugins/mcp";

/**
 * The Composio transport's boundary, asserted with no network and no database.
 *
 * What is under test is the boundary rather than the SDK: which app a connection names, whose id a
 * call is attributed to, what a label means, which version is sent, and what a refusal reads as. The
 * client arrives through {@link useComposioClient}, which is the only seam the module has —
 * `transportFor` resolves a kind to a MODULE, so there is no constructor to pass one to. Same shape
 * as `builtin-routines`.
 *
 * The security property this file exists for is the attribution one: the user id comes off the
 * connection and never out of the arguments a model produced. A model that could name a user id
 * could open somebody else's mailbox.
 */

afterEach(() => useComposioClient(null));

/**
 * One call as the vendor received it: the four fields that decide what it MEANS, and the arguments.
 *
 * THE ARGUMENTS ARE HERE BECAUSE THE ATTRIBUTION PROPERTY IS ABOUT BOTH HALVES. The recorder used to
 * take the call record and drop `args` on the floor, so the one test this file exists for — a user
 * id that comes off the connection and never out of a model's arguments — could only ever see the
 * half that was already right. `@composio/client` resolves the connected account from the execute
 * body's `user_id` and carries the model's own arguments beside it in `arguments`
 * (0.1.0-alpha.76, `resources/tools.d.ts:480-493`), so what a transport sends into the second of
 * those is as much of the call as what it sends into the first.
 */
type Recorded = {
  toolkit: string;
  slug: string;
  userId: string;
  version: string;
  /** Absent unless the caller named one account of the person's in particular. */
  connectedAccountId?: string;
  args: Record<string, unknown>;
};

/**
 * An answer in the shape `ToolExecuteResponseSchema` actually permits.
 *
 * Every stub here goes through this rather than returning a shape of its own, because the SDK's
 * schema makes `data`, `error` and `successful` all REQUIRED — so a stub that resolves `null`, or a
 * bare string, is testing a case the library cannot produce, and a test built on an impossible input
 * proves nothing about the code that reads a real one.
 */
function answered(
  data: Record<string, unknown>,
  outcome: { error?: string | null; successful?: boolean } = {},
) {
  return {
    data,
    error: outcome.error ?? null,
    successful: outcome.successful ?? true,
  };
}

/**
 * The two numbers this file reasons about, WRITTEN OUT rather than imported.
 *
 * AN ASSERTION THAT IMPORTS THE CONSTANT IT IS ABOUT CANNOT FAIL WHEN THAT CONSTANT MOVES, because
 * both sides move together. The previous version of this file replaced a loose bound with an
 * equality against `MAX_RESULT_CHARS` itself and called the number pinned; it was not. Applied to
 * the modules, `MAX_RESULT_CHARS` 20,000 → 40,000 and `LISTING_LIMIT` 1000 → 20 both left all 44
 * tests passing: the cap tests measured the answer against whatever the cap had just become, and
 * the listing test asked for whatever page the module had just decided to ask for.
 *
 * So the literals live here, and one test below is the only place the imported constants are read.
 * Changing either constant now reddens exactly that test, which is where the argument for the
 * number belongs: 20,000 is how much of a model's context one tool result may spend, and 1000 is
 * the vendor's stated page ceiling and therefore the whole listing.
 */
const RESULT_CAP = 20_000;
const WHOLE_LISTING = 1000;
const TRUNCATION_MARKER = "\n\n[truncated]";
const CAPPED_LENGTH = RESULT_CAP + TRUNCATION_MARKER.length;

/** The nesting `vendorSentence` reaches through, with whatever the vendor left at the bottom of it. */
function nested(message: unknown): unknown {
  return { cause: { error: { error: { message } } } };
}

/**
 * The SAME failure with nothing wrapped around it, which is how several of these calls arrive.
 *
 * `@composio/client`'s `APIError` hangs the response body on `.error` and sets no `cause` at all,
 * and builds its own `message` as the status code followed by that body JSON-stringified whole
 * where the body has no top-level `message` — `${"${status}"} ${"${JSON.stringify(error)}"}`
 * (`@composio/client` 0.1.0-alpha.76, `src/core/error.ts:9-45`). Composio's body puts its sentence
 * at `error.message`, so that fallback is what every one of these throws carries in `.message`.
 *
 * It reaches this transport unwrapped from five calls: `@composio/core` 0.18.1 awaits
 * `this.client.authConfigs.list`, `this.client.connectedAccounts.list` and `this.client.tools.list`
 * with no try around them (`src/models/AuthConfigs.ts`, `src/models/ConnectedAccounts.ts`,
 * `src/models/Tools.ts:552-555`), and `./composio-adapter` calls both raw deletes on the client
 * itself. So the sentence sits one level shallower here than in {@link nested}, and the dump is
 * what escaped in its place.
 */
function unwrapped(message: unknown): Error {
  const body = { error: { message } };
  return Object.assign(new Error(`404 ${JSON.stringify(body)}`), {
    status: 404,
    headers: { "x-request-id": "must-not-appear" },
    error: body,
  });
}

/** The same client error for a body with no sentence anywhere in it: status code, then the lot. */
function dumped(body: Record<string, unknown>): Error {
  return Object.assign(new Error(`502 ${JSON.stringify(body)}`), {
    status: 502,
    headers: { "x-request-id": "must-not-appear" },
    error: body,
  });
}

/**
 * The dump AS A BARE STRING, for the places one arrives already unwrapped from its Error.
 *
 * Taken off {@link dumped} rather than written out a second time, so the two cannot drift: what the
 * envelope's `error` field and a candidate sentence are tested against is byte-for-byte the string
 * `@composio/client` builds. A vendor gateway that proxies an upstream status and body into the
 * field its own schema spells a sentence produces exactly this, and so does one that puts its
 * client's message there — the shape is what is refused, not the route it took.
 */
const RESPONSE_DUMP = dumped({
  detail: [{ loc: ["body", "arguments"], msg: "unrecognised" }],
  request_id: "must-not-appear",
}).message;

function recording(answers: Partial<ComposioActions> = {}): {
  client: ComposioActions;
  calls: Recorded[];
} {
  const calls: Recorded[] = [];
  return {
    calls,
    client: {
      listActions: answers.listActions ?? (async () => []),
      execute:
        answers.execute ??
        (async (call, args) => {
          // SNAPSHOTTED RATHER THAN HELD BY REFERENCE, for the reason the schema test snapshots:
          // `toEqual` against a live reference holds whatever happened to the object afterwards, so
          // a transport that handed its arguments over and then edited them would be recorded as
          // having sent whatever it edited them into.
          calls.push({ ...call, args: structuredClone(args) });
          return answered({ ok: true });
        }),
    },
  };
}

const GMAIL_READ = {
  slug: "GMAIL_FETCH_EMAILS",
  description: "Fetch emails.",
  inputParameters: {
    type: "object",
    properties: { query: { type: "string" } },
  },
  tags: ["readOnlyHint", "important"],
  version: "20260903_00",
};

/** A parameter that stages a file, in the shape `JSONSchemaPropertySchema` keeps it. */
const FILE_PROPERTY = { type: "string", file_uploadable: true };

/**
 * One subschema keyword carrying `sub`, hung off a property so the root stays a `ParametersSchema`.
 *
 * A COMPUTED KEY, for `then` and for nothing else: biome refuses a literal `then` key on an object
 * literal, and the conditional trio has to be reachable here or the branch that walks it is being
 * asserted by nothing. `if`, `then`, `else`, `items` and `$ref` live on `JSONSchemaPropertySchema`
 * and not on the parameters root (`@composio/core` 0.18.1, `src/types/tool.types.ts:77-131` against
 * `:134-175`), so a case for one of them has to nest to be a shape the vendor could send.
 *
 * REQUIRED BY DEFAULT, because a file under a property the action can do without is withheld
 * rather than dropping the action. A walk that missed the keyword and one that found it would
 * then both offer the action, and these cases are about which of the two this is; required, a
 * file found is an action dropped and a file missed is an action offered. Pass `false` for the
 * other reading, where a file found is a `field` removed.
 */
function underProperty(
  keyword: string,
  sub: unknown,
  required = true,
): Record<string, unknown> {
  return {
    type: "object",
    properties: { field: { type: "object", [keyword]: sub } },
    ...(required ? { required: ["field"] } : {}),
  };
}

/** One action whose whole schema is the case under test, listed beside a plain one. */
function listing(inputParameters: Record<string, unknown>) {
  return recording({
    listActions: async () => [
      GMAIL_READ,
      { slug: "GMAIL_STAGES_A_FILE", version: "20260903_00", inputParameters },
    ],
  }).client;
}

describe("the numbers these assertions are about", () => {
  test("the modules hold the numbers this file has written out", () => {
    // The only reads of the imported constants in this file. Every other assertion measures
    // against the literals above, so a constant that moves reddens this one test — which states
    // the number — instead of quietly redefining what all the others are checking.
    expect(MAX_RESULT_CHARS).toBe(RESULT_CAP);
    expect(LISTING_LIMIT).toBe(WHOLE_LISTING);
  });
});

describe("which app a connection names", () => {
  test("the app slug comes off the url", () => {
    expect(toolkitOf("composio://gmail")).toBe("gmail");
    expect(toolkitOf("composio://gmail/")).toBe("gmail");
  });

  test("anything that is not a composio url names no app", () => {
    expect(toolkitOf("https://mcp.notion.com/mcp")).toBeNull();
    expect(toolkitOf("composio://")).toBeNull();
    expect(toolkitOf("")).toBeNull();
  });

  test("anything past the app slug means the url does not name one app", () => {
    // This answer is the app a person's connection is checked against — `accessFor` puts it on
    // `ServerAccess.toolkit` (`access.ts:133`) and the brokered gate looks `composio_connections`
    // up by it. A url this function reads loosely is a check performed against the wrong app, so
    // anything it cannot read as exactly one slug has to be no app rather than a best guess.
    expect(toolkitOf("composio://gmail/messages")).toBeNull();
    expect(toolkitOf("composio://gmail?scope=read")).toBeNull();
    expect(toolkitOf("composio://gmail#inbox")).toBeNull();
    expect(toolkitOf("composio://gmail slack")).toBeNull();
  });

  test("surrounding space is taken off before the trailing slash, not after", () => {
    // The strip ran first and the trim second, so a slash that was not the last character survived
    // it: `composio://gmail/ ` answered `"gmail/"`, which matches no row in `composio_connections`
    // and is not the app anybody meant.
    expect(toolkitOf("composio://gmail/ ")).toBe("gmail");
    expect(toolkitOf("composio://gmail  ")).toBe("gmail");
    expect(toolkitOf("composio://google_drive//")).toBe("google_drive");
  });
});

describe("what a label means", () => {
  test("read-only is a read", () => {
    expect(effectOf(["readOnlyHint", "openWorldHint", "gmail"])).toEqual({
      effect: "read",
      destructive: false,
    });
  });

  test("destructive is a destructive write", () => {
    expect(effectOf(["destructiveHint", "important"])).toEqual({
      effect: "write",
      destructive: true,
    });
  });

  test("create and update are writes that are not destructive", () => {
    expect(effectOf(["createHint", "openWorldHint"])).toEqual({
      effect: "write",
      destructive: false,
    });
    expect(effectOf(["updateHint", "labels", "inbox"])).toEqual({
      effect: "write",
      destructive: false,
    });
  });

  test("idempotent is not a read, because deleting is idempotent", () => {
    expect(effectOf(["idempotentHint", "openWorldHint"])).toEqual({
      effect: "write",
      destructive: false,
    });
  });

  test("no label at all is a write", () => {
    // Measured across five apps and never seen, so this branch guards the future rather than the
    // present: an app that labels nothing, or a label added later, must land on write.
    expect(effectOf([])).toEqual({ effect: "write", destructive: false });
    expect(effectOf(undefined)).toEqual({
      effect: "write",
      destructive: false,
    });
    expect(effectOf(["gmail", "inbox"])).toEqual({
      effect: "write",
      destructive: false,
    });
  });

  test("destructive wins over read-only when both are present", () => {
    // Contradictory labels are somebody else's bug, and the safe reading is the strict one.
    expect(effectOf(["readOnlyHint", "destructiveHint"])).toEqual({
      effect: "write",
      destructive: true,
    });
  });

  /**
   * A PADDED LABEL IS THE LABEL, AND READ RAW IT FAILS THE DANGEROUS WAY ROUND.
   *
   * `Set.has` is an identity comparison, so `" destructiveHint "` matched nothing and the action was
   * recorded with `destructive: false` — on the row that decides whether a Bot is stopped before it
   * runs the action at all, with nothing about the row looking wrong. The slug and the version read
   * out of the same listing are both trimmed; this was the field that was not.
   */
  test("a label Composio padded is still the label it spells", () => {
    expect(effectOf([" destructiveHint "])).toEqual({
      effect: "write",
      destructive: true,
    });
    expect(effectOf(["\treadOnlyHint\n"])).toEqual({
      effect: "read",
      destructive: false,
    });
  });
});

describe("finding the vendor's own sentence", () => {
  test("the sentence nested inside the cause is what comes out", () => {
    // The real shape, copied from a live failure. The top-level message is useless.
    const error = Object.assign(new Error("Error executing the tool X"), {
      cause: {
        status: 404,
        headers: { "x-request-id": "must-not-appear" },
        error: {
          error: {
            message:
              "No connected account found for user ID u1 for toolkit gmail",
            code: 1810,
          },
        },
      },
    });

    expect(vendorSentence(error)).toBe(
      "No connected account found for user ID u1 for toolkit gmail",
    );
  });

  test("an error with no such sentence yields nothing rather than a guess", () => {
    expect(vendorSentence(new Error("boom"))).toBeNull();
    expect(vendorSentence({ cause: { error: {} } })).toBeNull();
    expect(vendorSentence(undefined)).toBeNull();
  });

  test("a sentence made only of whitespace is not a sentence", () => {
    // The `.trim()` on the return had nothing asserting it. A blank message that counted as a
    // sentence is worse than none: `callTool` and `listingSentence` both prefer it over their
    // fallbacks, so the reader gets an empty refusal instead of the one line naming what to do.
    expect(vendorSentence(nested(""))).toBeNull();
    expect(vendorSentence(nested("   "))).toBeNull();
    expect(vendorSentence(nested("\n\t "))).toBeNull();
  });

  test("the sentence comes back as it was measured, without its padding", () => {
    // The guard trimmed and the return did not, so the one thing the function had already decided
    // about the string was thrown away again. What comes out is a refusal in a model's context and
    // a sentence in an audit row; leading newlines in both are this module's own untidiness, and
    // the cap that measures the string measures the padding with it.
    expect(vendorSentence(nested("  Gmail rejected the query.\n"))).toBe(
      "Gmail rejected the query.",
    );
  });

  test("a message that is not a string is not read as one", () => {
    // Nothing asserted the type guard either. Composio's payloads are somebody else's JSON, so the
    // field can be a number, an object or null; handed on unchecked, each of those reaches a model's
    // context and an audit row as `[object Object]` or `1810`.
    expect(vendorSentence(nested(1810))).toBeNull();
    expect(vendorSentence(nested(null))).toBeNull();
    expect(vendorSentence(nested({ text: "a nested sentence" }))).toBeNull();
    expect(vendorSentence(nested(["a sentence in a list"]))).toBeNull();
  });

  test("the vendor's placeholder is not a sentence, however deep it arrives", () => {
    /*
     * THE GUARD COVERED THE BRANCH THAT THROWS AND NOT THE ONE THIS FUNCTION READS, which is the
     * half that matters: `listingSentence` and `callTool` both prefer this answer over their own
     * fallbacks, so "Error executing the tool X" found nested inside `cause` walked straight past a
     * check written for exactly that string. This module's own comment calls it the one sentence
     * never worth passing on; a reader who asked for that tool learns from it only that they asked.
     */
    expect(
      vendorSentence(nested("Error executing the tool GMAIL_FETCH_EMAILS")),
    ).toBeNull();
    expect(vendorSentence(nested("  error executing the tool X\n"))).toBeNull();

    // Matched on its opening and not looked for anywhere in the string, because a real sentence
    // that goes on to mention the phrase is still a real sentence.
    expect(
      vendorSentence(
        nested("No connected account found; error executing the tool X."),
      ),
    ).toBe("No connected account found; error executing the tool X.");
  });

  test("the sentence is found where a client error with no wrapper puts it", () => {
    /*
     * ONE DEPTH WAS READ AND TWO ARE THROWN. See {@link unwrapped}: five of this transport's calls
     * surface `@composio/client`'s own `APIError`, which carries the body on `.error` and no
     * `cause`, so `cause.error.error.message` found nothing on any of them and the vendor's
     * readable sentence was skipped in favour of a status code and the whole response body.
     */
    expect(
      vendorSentence(
        unwrapped(
          "No connected account found for user ID u1 for toolkit gmail",
        ),
      ),
    ).toBe("No connected account found for user ID u1 for toolkit gmail");
  });

  test("every judgement this function makes applies at the shallower depth too", () => {
    /*
     * THE POINT OF THE JUDGEMENT LIVING HERE. It was moved into this function so that no caller
     * could reach a sentence without it; a second depth read without it would be that bypass
     * rebuilt. Each of these is the assertion its {@link nested} sibling above makes, asked of the
     * place a client error actually puts the field.
     */
    expect(
      vendorSentence(unwrapped("Error executing the tool GMAIL_FETCH_EMAILS")),
    ).toBeNull();
    expect(
      vendorSentence(unwrapped("  error executing the tool X\n")),
    ).toBeNull();
    expect(vendorSentence(unwrapped(""))).toBeNull();
    expect(vendorSentence(unwrapped("   "))).toBeNull();
    expect(vendorSentence(unwrapped(1810))).toBeNull();
    expect(vendorSentence(unwrapped(null))).toBeNull();
    expect(vendorSentence(unwrapped({ text: "a nested sentence" }))).toBeNull();
    expect(vendorSentence(unwrapped(["a sentence in a list"]))).toBeNull();
    expect(vendorSentence(unwrapped("  Gmail rejected the query.\n"))).toBe(
      "Gmail rejected the query.",
    );
  });

  test("a body with no sentence in it yields nothing rather than the body", () => {
    // The shape `dumped` is named for: nothing at `error.message`, so there is no sentence to find
    // and the function must say so rather than reaching for whatever else the body holds.
    expect(
      vendorSentence(dumped({ detail: "something went wrong" })),
    ).toBeNull();
    expect(vendorSentence(dumped({}))).toBeNull();
  });

  test("a response dump found where the sentence belongs is not a sentence either", () => {
    /*
     * THE OTHER HALF OF THE JUDGEMENT, WHICH ONLY ONE OF THE THREE READERS WAS MAKING. The dump
     * refusal was added to the thrown-message guard and to nothing else, so a status code followed
     * by a whole response body arriving AT `error.message` — the field this function reaches for —
     * was passed on as the vendor's own explanation, at both depths. The test above only covers a
     * body with no `message` at all; it says nothing about a `message` that is itself a dump, which
     * is what a gateway proxying an upstream reply puts there.
     *
     * Refused for the reason the placeholder is: it is not an explanation, and it costs a request
     * id in a model's context and an audit row the size of a response body to say so.
     */
    expect(vendorSentence(nested(RESPONSE_DUMP))).toBeNull();
    expect(vendorSentence(unwrapped(RESPONSE_DUMP))).toBeNull();
  });

  test("a status code with a real sentence after it is still a sentence", () => {
    /*
     * THE LIMIT ON THE REFUSAL ABOVE, asserted so that widening it reddens something. What the
     * module refuses is a three-digit status followed by the OPENING OF A JSON DOCUMENT, because
     * that is the string the client builds and nothing a person writes. A status code followed by
     * words is the client's other branch — the body's own `message` came through — and it is the
     * most useful sentence on this path; refusing it would replace a named cause with advice to
     * check a connection that is fine.
     */
    expect(vendorSentence(nested("400 Invalid auth config id"))).toBe(
      "400 Invalid auth config id",
    );
    expect(vendorSentence(unwrapped("404 status code (no body)"))).toBe(
      "404 status code (no body)",
    );
  });
});

describe("listing an app's actions", () => {
  test("listing needs no credential", () => {
    expect(listNeedsCredential).toBe(false);
  });

  test("the listing asks for a page, and for one big enough to be the whole list", async () => {
    const asked: unknown[] = [];
    useComposioClient(
      recording({
        listActions: async (toolkit, page) => {
          asked.push({ toolkit, page });
          return [GMAIL_READ];
        },
      }).client,
    );

    await listTools({ url: "composio://gmail" });

    // Composio's default page is 20 and Gmail publishes 63 actions, so an omitted limit truncates.
    // It also NARROWED, through the wrapper this listing used to go through: `getRawComposioTools`
    // auto-applied `important=true` when no limit, no tags and no search were given
    // (`@composio/core` 0.18.1, `src/models/Tools.ts:505-515`), and nothing in the short answer
    // said a filter had been applied. Asking for a page is therefore not an optimisation, and the
    // seam must not let a caller forget to — what it sizes now is each request rather than the
    // answer, because `./composio-adapter` reads on until Composio's cursor stops.
    expect(asked).toEqual([
      { toolkit: "gmail", page: { limit: WHOLE_LISTING } },
    ]);
  });

  /**
   * THIS TEST ASSERTED A REFUSAL AND WAS CHANGED ON PURPOSE.
   *
   * It was "a listing that filled the biggest page the SDK can ask for is not called complete", and
   * it pinned the refusal this module made of any listing at {@link WHOLE_LISTING} rows. The reason
   * it gave was true of the WRAPPER: "`ToolListParamsSchema` accepts no cursor and
   * `getRawComposioTools` drops the response's `next_cursor`, so one page at the API's stated
   * maximum is the largest listing expressible through this SDK".
   *
   * IT IS NOT TRUE OF THE VENDOR. `@composio/client`'s `ToolListParams` carries a `cursor` and its
   * `ToolListResponse` carries `next_cursor` (0.1.0-alpha.76, `resources/tools.d.ts:421-432`,
   * `:200-204`), and `./composio-adapter` now reads that client and follows the cursor to the end.
   * A listing this long is an app with a lot of actions, and refusing it would be refusing a
   * complete answer — which is what the same ceiling, one file over, was doing to the app picker
   * on every single call.
   *
   * SO WHAT IS ASSERTED IS THE INVERSE, AT THE SAME BOUNDARY. The seam below hands back a full page
   * because that is what the adapter's pager resolves to once it has read every page; this module's
   * job is to commit it rather than to second-guess its length. The refusals this module still
   * makes — an empty listing, an unreadable row, a listing that did not answer — are unmoved, and
   * each has its own test above.
   */
  test("a listing as long as the biggest page is committed rather than called a fragment", async () => {
    useComposioClient(
      recording({
        listActions: async () =>
          Array.from({ length: WHOLE_LISTING }, (_unused, index) => ({
            ...GMAIL_READ,
            slug: `GMAIL_ACTION_${index}`,
          })),
      }).client,
    );

    const listed = await listTools({ url: "composio://gmail" });

    expect(listed).toHaveLength(WHOLE_LISTING);
  });

  test("an action arrives with its schema, its effect and its version", async () => {
    // RECORDED AND ASSERTED AFTERWARDS, NOT CHECKED INSIDE THE STUB. `listTools` wraps this call in
    // the try that turns a throw into `listingSentence`'s sentence, so a failed `expect` in there
    // is not a failed test: it is swallowed and re-emerges as a refusal about Composio, which this
    // test would then report as a listing failure rather than as the wrong app being asked for.
    const asked: string[] = [];
    const { client } = recording({
      listActions: async (toolkit) => {
        asked.push(toolkit);
        return [GMAIL_READ];
      },
    });
    useComposioClient(client);

    expect(await listTools({ url: "composio://gmail" })).toEqual([
      {
        name: "GMAIL_FETCH_EMAILS",
        description: "Fetch emails.",
        inputSchema: {
          type: "object",
          properties: { query: { type: "string" } },
        },
        effect: "read",
        destructive: false,
        version: "20260903_00",
      },
    ]);
    expect(asked).toEqual(["gmail"]);
  });

  test("an action that needs a file is not offered at all", async () => {
    // REQUIRED HERE ON PURPOSE. Composio's own GMAIL_SEND_EMAIL requires nothing and is offered
    // without its attachment (`composio-file-parameters.test.ts`); the `required` below is what
    // makes this the case no call can satisfy.
    useComposioClient(
      recording({
        listActions: async () => [
          GMAIL_READ,
          {
            slug: "GMAIL_SEND_EMAIL",
            description: "Send an email.",
            tags: ["createHint"],
            version: "20260903_00",
            inputParameters: {
              type: "object",
              properties: {
                recipient: { type: "string" },
                // What the SDK hands on under its default file handling: the vendor's own staging
                // descriptor, untouched. `dangerouslyAllowAutoUploadDownloadFiles` is off unless a
                // client asks for it (`src/models/Tools.ts:136`, `:242-248`), and only that flag
                // collapses the shape. An `s3key` is issued by an upload nothing here performs.
                attachment: {
                  type: "object",
                  file_uploadable: true,
                  properties: {
                    name: { type: "string" },
                    mimetype: { type: "string" },
                    s3key: { type: "string" },
                  },
                },
              },
              required: ["recipient", "attachment"],
            },
          },
        ],
      }).client,
    );

    const listed = await listTools({ url: "composio://gmail" });

    // Dropped rather than offered with a field the model can only invent. Offering it guarantees a
    // hallucinated key and a rejection at the vendor's staging lookup, and a grant recorded against
    // a name that can never work.
    expect(listed.map((tool) => tool.name)).toEqual(["GMAIL_FETCH_EMAILS"]);
  });

  test("a file parameter reached through $defs and a variant is found too", async () => {
    useComposioClient(
      recording({
        listActions: async () => [
          GMAIL_READ,
          {
            slug: "GMAIL_GET_ATTACHMENT",
            version: "20260903_00",
            inputParameters: {
              type: "object",
              properties: { body: { $ref: "#/$defs/upload" } },
              $defs: {
                upload: {
                  anyOf: [
                    { type: "null" },
                    { type: "string", file_uploadable: true },
                  ],
                },
              },
            },
          },
        ],
      }).client,
    );

    // Composio toolkits routinely express the flag through a `$ref`/`$defs` indirection, which is
    // why the SDK's own predicate walks `$defs` and every composed variant
    // (`src/utils/modifiers/FileToolModifier.utils.neutral.ts:77-134`). A walk that stopped at
    // `properties` would answer false for every ref-based schema and offer it anyway.
    const listed = await listTools({ url: "composio://gmail" });
    expect(listed.map((tool) => tool.name)).toEqual(["GMAIL_FETCH_EMAILS"]);
  });

  test("a file parameter is found down every subschema keyword the SDK keeps", async () => {
    /*
     * ONE CASE PER KEYWORD, because a keyword the walk does not descend is an action offered to a
     * model under BOTH auto-upload settings — the parameter is either a bucket key nobody here can
     * issue or a server-side path nobody should promise — so every call against it fails.
     *
     * `additionalProperties` is the one that was missing, and it is not exotic: both
     * `ParametersSchema` and `JSONSchemaPropertySchema` keep it as a full subschema
     * (`@composio/core` 0.18.1, `src/types/tool.types.ts:154` and `:111`), which is precisely how a
     * toolkit spells "a bag of attachments". The rest were already walked and asserted by nothing.
     */
    const hidden: { where: string; schema: Record<string, unknown> }[] = [
      {
        where: "additionalProperties at the root",
        schema: { type: "object", additionalProperties: FILE_PROPERTY },
      },
      {
        where: "additionalProperties under a property",
        schema: underProperty("additionalProperties", FILE_PROPERTY),
      },
      {
        where: "patternProperties at the root",
        schema: {
          type: "object",
          patternProperties: { "^attachment_": FILE_PROPERTY },
        },
      },
      {
        where: "patternProperties under a property",
        schema: underProperty("patternProperties", { any: FILE_PROPERTY }),
      },
      {
        where: "not at the root",
        schema: { type: "object", not: FILE_PROPERTY },
      },
      { where: "not", schema: underProperty("not", FILE_PROPERTY) },
      { where: "if", schema: underProperty("if", FILE_PROPERTY) },
      { where: "then", schema: underProperty("then", FILE_PROPERTY) },
      { where: "else", schema: underProperty("else", FILE_PROPERTY) },
      { where: "items", schema: underProperty("items", FILE_PROPERTY) },
      {
        where: "items as a tuple",
        schema: underProperty("items", [{ type: "string" }, FILE_PROPERTY]),
      },
      { where: "oneOf", schema: underProperty("oneOf", [FILE_PROPERTY]) },
      { where: "allOf", schema: underProperty("allOf", [FILE_PROPERTY]) },
      {
        where: "definitions at the root",
        schema: {
          type: "object",
          properties: { body: { $ref: "#/definitions/upload" } },
          definitions: { upload: FILE_PROPERTY },
        },
      },
    ];

    for (const { where, schema } of hidden) {
      useComposioClient(listing(schema));
      const listed = await listTools({ url: "composio://gmail" });
      // The keyword is carried into the comparison so a failure names which one escaped.
      expect({ where, offered: listed.map((tool) => tool.name) }).toEqual({
        where,
        offered: ["GMAIL_FETCH_EMAILS"],
      });
    }
  });

  test("a file parameter is found down the keywords the wire can actually carry", async () => {
    /*
     * THE KEYWORDS THE STRIP USED TO MAKE UNREACHABLE, which is why they were never walked and why
     * they are reachable now.
     *
     * The list beside the walk was bounded by a premise about the WRAPPER: a keyword
     * `ParametersSchema` and `JSONSchemaPropertySchema` did not name could not be present to be
     * walked, because `ToolSchema.parse` removed it before any caller saw the schema. That premise
     * is retired. `./composio-adapter` reads `client.tools.list` and runs no parse at all — the
     * listing left the wrapper because the wrapper is the one method of the vendor's tool model
     * that cannot be paged — so what reaches the walk is the schema Composio published, whole.
     *
     * Every keyword below is a 2020-12 (or draft-07) applicator carrying a subschema, and none of
     * them appears in either of those two zod objects. So before the strip went away they could
     * not arrive; after it went away they arrived and went unwalked, which is an action offered to
     * a model whose every call fails at the vendor's staging lookup.
     */
    const carried: { where: string; schema: Record<string, unknown> }[] = [
      {
        where: "prefixItems",
        schema: underProperty("prefixItems", [
          { type: "string" },
          FILE_PROPERTY,
        ]),
      },
      { where: "contains", schema: underProperty("contains", FILE_PROPERTY) },
      {
        where: "dependentSchemas at the root",
        schema: {
          type: "object",
          properties: { send: { type: "boolean" } },
          dependentSchemas: {
            send: { type: "object", properties: { body: FILE_PROPERTY } },
          },
        },
      },
      {
        where: "dependentSchemas under a property",
        schema: underProperty("dependentSchemas", { send: FILE_PROPERTY }),
      },
      {
        where: "dependencies under a property",
        schema: underProperty("dependencies", { send: FILE_PROPERTY }),
      },
      {
        where: "propertyNames",
        schema: underProperty("propertyNames", FILE_PROPERTY),
      },
      {
        where: "unevaluatedProperties at the root",
        schema: { type: "object", unevaluatedProperties: FILE_PROPERTY },
      },
      {
        where: "unevaluatedProperties under a property",
        schema: underProperty("unevaluatedProperties", FILE_PROPERTY),
      },
      {
        where: "unevaluatedItems",
        schema: underProperty("unevaluatedItems", FILE_PROPERTY),
      },
    ];

    for (const { where, schema } of carried) {
      useComposioClient(listing(schema));
      const listed = await listTools({ url: "composio://gmail" });
      // The keyword is carried into the comparison so a failure names which one escaped.
      expect({ where, offered: listed.map((tool) => tool.name) }).toEqual({
        where,
        offered: ["GMAIL_FETCH_EMAILS"],
      });
    }
  });

  test("the keywords the wire carries drop an action only where the flag is set", async () => {
    /*
     * THE OTHER HALF, on the keywords beside them. `dependencies` is draft-07's overload and its
     * other arm is a list of required property NAMES rather than a subschema; `unevaluatedItems`
     * and `unevaluatedProperties` are unions with `boolean` exactly as `additionalProperties` is.
     * A walk that recursed into those without reading them as "not a subschema" would drop an
     * action nobody has to stage anything for.
     */
    const kept: { where: string; schema: Record<string, unknown> }[] = [
      {
        where: "dependencies naming required properties",
        schema: {
          type: "object",
          properties: { send: { type: "boolean" }, body: { type: "string" } },
          dependencies: { send: ["body"] },
        },
      },
      {
        where: "unevaluatedProperties is closed",
        schema: { type: "object", unevaluatedProperties: false },
      },
      {
        where: "unevaluatedItems is open",
        schema: underProperty("unevaluatedItems", true),
      },
      {
        where: "contains without the flag",
        schema: underProperty("contains", { type: "string" }),
      },
    ];

    for (const { where, schema } of kept) {
      useComposioClient(listing(schema));
      const listed = await listTools({ url: "composio://gmail" });
      expect({ where, offered: listed.map((tool) => tool.name) }).toEqual({
        where,
        offered: ["GMAIL_FETCH_EMAILS", "GMAIL_STAGES_A_FILE"],
      });
    }
  });

  test("an action is dropped only where the flag is actually set", async () => {
    /*
     * THE OTHER HALF OF THE WALK, which decides what stays offered. `file_uploadable` is
     * `z.boolean().optional()` (`src/types/tool.types.ts:89`), so `false` is a value the vendor
     * really sends and the comparison against `true` rather than against truthiness is what keeps
     * it from dropping an action nobody has to stage anything for. `additionalProperties` is a
     * union with `boolean` (`:111`, `:154`), so `true` and `false` arrive there as values and the
     * walk has to read them as "not a subschema" instead of tripping over them.
     */
    const offered: { where: string; schema: Record<string, unknown> }[] = [
      {
        where: "the flag is explicitly false",
        schema: {
          type: "object",
          properties: { note: { type: "string", file_uploadable: false } },
        },
      },
      {
        where: "additionalProperties is open",
        schema: { type: "object", additionalProperties: true },
      },
      {
        where: "additionalProperties is closed",
        schema: { type: "object", additionalProperties: false },
      },
    ];

    for (const { where, schema } of offered) {
      useComposioClient(listing(schema));
      const listed = await listTools({ url: "composio://gmail" });
      expect({ where, offered: listed.map((tool) => tool.name) }).toEqual({
        where,
        offered: ["GMAIL_FETCH_EMAILS", "GMAIL_STAGES_A_FILE"],
      });
    }
  });

  test("a file under a parameter nothing requires is removed, down every keyword the walk reads", async () => {
    /*
     * THE SAME KEYWORDS AS THE TWO TESTS ABOVE, READ THE OTHER WAY. There `field` is required, so a
     * file found beneath it is an action nobody can call. Here it is not, so a file found beneath it
     * is a parameter the call can leave out: the action is offered and `field` is gone from it. A
     * keyword the walk did not descend would leave `field` in place, file and all, which is the one
     * outcome that gives a model a parameter it can only fill with an invented staging key.
     */
    const keywords: [string, unknown][] = [
      ["additionalProperties", FILE_PROPERTY],
      ["patternProperties", { any: FILE_PROPERTY }],
      ["not", FILE_PROPERTY],
      ["if", FILE_PROPERTY],
      ["then", FILE_PROPERTY],
      ["else", FILE_PROPERTY],
      ["items", FILE_PROPERTY],
      ["items", [{ type: "string" }, FILE_PROPERTY]],
      ["anyOf", [{ type: "null" }, FILE_PROPERTY]],
      ["oneOf", [FILE_PROPERTY]],
      ["allOf", [FILE_PROPERTY]],
      ["prefixItems", [{ type: "string" }, FILE_PROPERTY]],
      ["contains", FILE_PROPERTY],
      ["dependentSchemas", { send: FILE_PROPERTY }],
      ["dependencies", { send: FILE_PROPERTY }],
      ["propertyNames", FILE_PROPERTY],
      ["unevaluatedProperties", FILE_PROPERTY],
      ["unevaluatedItems", FILE_PROPERTY],
    ];

    for (const [keyword, sub] of keywords) {
      useComposioClient(listing(underProperty(keyword, sub, false)));
      const listed = await listTools({ url: "composio://gmail" });
      const staged = listed.find((tool) => tool.name === "GMAIL_STAGES_A_FILE");
      expect({ keyword, schema: staged?.inputSchema }).toEqual({
        keyword,
        schema: { type: "object", properties: {} },
      });
    }
  });

  test("a file is removed at the deepest parameter a call can leave out, and nothing else goes with it", async () => {
    /*
     * A FILE THE OBJECT AROUND IT REQUIRES MAKES THAT OBJECT THE FILE PARAMETER, one level up. So an
     * optional `message` that requires its `attachment` goes whole, a required `message` whose
     * `attachment` is optional loses only the `attachment`, and required all the way down is an
     * action no call can satisfy. Every sibling, every `required` and every description stays.
     */
    const message = (requiresAttachment: boolean) => ({
      type: "object",
      description: "The message to send.",
      properties: {
        subject: { type: "string", description: "Its subject." },
        attachment: FILE_PROPERTY,
      },
      ...(requiresAttachment ? { required: ["subject", "attachment"] } : {}),
    });
    const action = (
      requiresMessage: boolean,
      requiresAttachment: boolean,
    ): Record<string, unknown> => ({
      type: "object",
      properties: {
        to: { type: "string", description: "Who it goes to." },
        message: message(requiresAttachment),
      },
      required: requiresMessage ? ["to", "message"] : ["to"],
    });

    const cases: { where: string; schema: Record<string, unknown> }[] = [
      { where: "optional inside a required one", schema: action(true, false) },
      { where: "required inside an optional one", schema: action(false, true) },
    ];
    const offered = [
      {
        type: "object",
        properties: {
          to: { type: "string", description: "Who it goes to." },
          message: {
            type: "object",
            description: "The message to send.",
            properties: {
              subject: { type: "string", description: "Its subject." },
            },
          },
        },
        required: ["to", "message"],
      },
      {
        type: "object",
        properties: { to: { type: "string", description: "Who it goes to." } },
        required: ["to"],
      },
    ];

    for (const [index, { where, schema }] of cases.entries()) {
      const asHandedOver = structuredClone(schema);
      useComposioClient(listing(schema));
      const listed = await listTools({ url: "composio://gmail" });
      const staged = listed.find((tool) => tool.name === "GMAIL_STAGES_A_FILE");
      expect({ where, schema: staged?.inputSchema }).toEqual({
        where,
        schema: offered[index],
      });
      // Removed from what a model is shown, never from the object the vendor handed over.
      expect({ where, schema }).toEqual({ where, schema: asHandedOver });
    }

    useComposioClient(listing(action(true, true)));
    const listed = await listTools({ url: "composio://gmail" });
    expect(listed.map((tool) => tool.name)).toEqual(["GMAIL_FETCH_EMAILS"]);
  });

  test("a file required anywhere a requirement can be written still drops the action", async () => {
    /*
     * A PARAMETER REMOVED THAT THE VENDOR STILL INSISTS ON IS THE WORST OUTCOME AVAILABLE: offered,
     * granted, and failing on every call. So "nothing requires it" is read wherever a requirement
     * can apply to the object, and a requirement that cannot be read is taken as one.
     */
    const file = { attachment: FILE_PROPERTY, body: { type: "string" } };
    const required: { where: string; schema: Record<string, unknown> }[] = [
      {
        where: "required under allOf",
        schema: {
          type: "object",
          properties: file,
          allOf: [{ required: ["attachment"] }],
        },
      },
      {
        where: "required by one arm of anyOf",
        schema: {
          type: "object",
          properties: file,
          anyOf: [{ required: ["body"] }, { required: ["attachment"] }],
        },
      },
      {
        where: "required once another parameter is sent",
        schema: {
          type: "object",
          properties: file,
          dependentRequired: { body: ["attachment"] },
        },
      },
      {
        where: "required by a draft-07 dependency",
        schema: {
          type: "object",
          properties: file,
          dependencies: { body: ["attachment"] },
        },
      },
      {
        where: "a required list that is not a list",
        schema: { type: "object", properties: file, required: "attachment" },
      },
      {
        where: "a reference nothing here resolves",
        schema: {
          type: "object",
          properties: file,
          $ref: "#/$defs/needsAttachment",
        },
      },
    ];

    for (const { where, schema } of required) {
      useComposioClient(listing(schema));
      const listed = await listTools({ url: "composio://gmail" });
      expect({ where, offered: listed.map((tool) => tool.name) }).toEqual({
        where,
        offered: ["GMAIL_FETCH_EMAILS"],
      });
    }
  });

  test("a call is checked for a removed file wherever the listing removed it", () => {
    const schema = {
      type: "object",
      properties: {
        to: { type: "string" },
        attachment: FILE_PROPERTY,
        message: {
          type: "object",
          properties: { subject: { type: "string" }, inline: FILE_PROPERTY },
        },
      },
      required: ["to", "message"],
    };
    const invented = { name: "a.pdf", mimetype: "application/pdf", s3key: "x" };

    expect(
      withheldArguments(schema, {
        to: "[email protected]",
        attachment: invented,
        message: { subject: "Hi", inline: [invented] },
      }),
    ).toEqual(["attachment", "message.inline"]);
    // Absent, or the `null` Composio documents as "no file", is nothing to refuse.
    expect(
      withheldArguments(schema, {
        to: "[email protected]",
        attachment: null,
        message: { subject: "Hi" },
      }),
    ).toEqual([]);
    // A parameter of the same name somewhere the listing removed nothing is not one it removed.
    expect(
      withheldArguments(schema, { to: "[email protected]", inline: invented }),
    ).toEqual([]);
    // And an action the listing never offered has nothing withheld to check for.
    expect(
      withheldArguments(
        { ...schema, required: ["to", "message", "attachment"] },
        { attachment: invented },
      ),
    ).toEqual([]);
  });

  /**
   * A SCHEMA NOBODY CAN WALK TO THE BOTTOM IS A VENDOR VALUE ADMITTED WITHOUT A GUARD, and the walk
   * that reads it sits OUTSIDE the try that wraps the vendor's call.
   *
   * Every other read of this listing is bounded — the element check, the slug, the labels, the
   * version and the description each refuse in a sentence naming the app and the action. The walk
   * recursed as deep as the vendor nested, so a schema deep enough to exhaust the stack left
   * through the one door with nothing standing in it: `RangeError: Maximum call stack size
   * exceeded`, which is what `refreshTools` writes into the app row's `lastError` for an
   * administrator to read. That sentence names neither the app nor the action, and the engine is
   * not a party anybody can act on.
   */
  test("a schema nested past what this deployment walks is refused in its own sentence", async () => {
    let schema: Record<string, unknown> = { type: "string" };
    for (let level = 0; level < 20_000; level += 1) {
      schema = { type: "object", properties: { deeper: schema } };
    }
    useComposioClient(listing(schema));

    const failure = await listTools({ url: "composio://gmail" }).then(
      () => null,
      (raised: unknown) => raised,
    );

    expect(failure).toBeInstanceOf(Error);
    const said = failure instanceof Error ? failure.message : "";
    // Not the engine's, which is the whole finding: it names neither the app nor the action.
    expect(said).not.toMatch(/call stack|RangeError/i);
    expect(said).toMatch(/gmail/);
    expect(said).toMatch(/GMAIL_STAGES_A_FILE/);
    // And the listing is not committed over it, which is what every sibling refusal here promises.
    expect(said).toMatch(/actions already recorded for this app are kept/);
  });

  /**
   * AND THE FLAG ITSELF IS A VENDOR VALUE, WHICH THIS WAS THE LAST SITE TO READ AS `=== true`.
   *
   * `"true" === true` is false, so a vendor publishing the flag as a string left a file-staging
   * action OFFERED — the filter's only fail-open direction, and the one it exists to close. What a
   * model gets is a parameter it can only invent an `s3key` for, a call that fails at the vendor's
   * staging lookup every time, and a grant recorded against a name that can never work.
   */
  test("a file flag that is not a flag is refused rather than read as no file", async () => {
    useComposioClient(
      listing({
        type: "object",
        properties: { attachment: { type: "string", file_uploadable: "true" } },
      }),
    );

    const failure = await listTools({ url: "composio://gmail" }).then(
      () => null,
      (raised: unknown) => raised,
    );

    expect(failure).toBeInstanceOf(Error);
    const said = failure instanceof Error ? failure.message : "";
    expect(said).toMatch(/gmail/);
    expect(said).toMatch(/GMAIL_STAGES_A_FILE/);
    expect(said).toMatch(/actions already recorded for this app are kept/);
  });

  test("the schema a model is shown is the one the SDK handed over, unaltered", async () => {
    /*
     * A CHARACTERIZATION TEST, and it passed before the claim beside `inputParameters` was
     * corrected — the correction is to a comment, because the loss it describes happens inside
     * `ToolSchema.parse` and there is no key left here to restore.
     *
     * What it pins is the narrower promise that replaced the false one: this module adds nothing to
     * the schema and removes nothing from it. The keys below are ones `ParametersSchema` and
     * `JSONSchemaPropertySchema` would have stripped, so a real client never delivers them — which
     * is exactly why they are the right probe for whether anything HERE also strips. `listTools`
     * now walks the schema looking for a file parameter, and a walk that rebuilt what it read
     * would silently narrow every schema in the listing.
     */
    const schema = {
      type: "object",
      properties: {
        query: { type: "string", deprecated: true, contentEncoding: "utf-8" },
      },
      if: { required: ["query"] },
      // No `then` beside it: biome bans a `then` key on an object literal, and the point of these
      // is only that they are root keywords `ParametersSchema` does not name.
      else: { required: [] },
      examples: [{ query: "is:unread" }],
      "x-openbot-probe": "kept",
    };
    /*
     * SNAPSHOTTED BEFORE THE CALL, because comparing the answer to `schema` compares it to the very
     * object the stub handed over. `toEqual` between two references to one object holds whatever
     * happened in between, so an in-place `delete` inside `listTools` — a walk that pruned what it
     * read — passed this test unchanged. Proven: one added `delete` of a root keyword in the map
     * left all 44 tests green.
     *
     * The snapshot is what the SDK handed over. The first assertion is that a model is shown that;
     * the second is that the vendor's own object still IS that, because a module returning a
     * faithful copy while wrecking the original would corrupt every later reader of one listing.
     */
    const asHandedOver = structuredClone(schema);
    useComposioClient(
      recording({
        listActions: async () => [{ ...GMAIL_READ, inputParameters: schema }],
      }).client,
    );

    const [tool] = await listTools({ url: "composio://gmail" });
    expect(tool?.inputSchema).toEqual(asHandedOver);
    expect(schema).toEqual(asHandedOver);
  });

  test("an action with no schema is still listed, with an open one", async () => {
    useComposioClient(
      recording({
        listActions: async () => [
          { slug: "GMAIL_ODD", tags: ["updateHint"], version: "20260903_00" },
        ],
      }).client,
    );

    const [tool] = await listTools({ url: "composio://gmail" });

    // Offered rather than dropped: the vendor is the right party to reject a bad argument, and a
    // silently missing action reads to an administrator as an app that does not have it.
    expect(tool?.name).toBe("GMAIL_ODD");
    expect(tool?.inputSchema).toEqual({});
    expect(tool?.effect).toBe("write");
  });

  test("an action Composio published no version for is listed with no version key", async () => {
    useComposioClient(
      recording({
        listActions: async () => [
          { slug: "GMAIL_UNVERSIONED", tags: ["readOnlyHint"] },
        ],
      }).client,
    );

    const [tool] = await listTools({ url: "composio://gmail" });

    // The branch that spreads the key only when the vendor sent one had nothing exercising it:
    // every listing stub above carries a version. What it guards is not cosmetic. `store.ts`
    // writes `tool.version ?? null`, so a key present and empty would be recorded as a version this
    // deployment believes it has, and `callTool` would send `""` to a vendor that rejects it —
    // instead of the refusal that names what the reader can and cannot do about it.
    expect(Object.keys(tool ?? {})).not.toContain("version");
    expect(tool?.name).toBe("GMAIL_UNVERSIONED");
    expect(tool?.effect).toBe("read");
  });

  test("a listing nobody was asked for throws rather than answering empty", async () => {
    // `[]` means "the vendor was asked and advertises none" everywhere else in this codebase, and
    // `refreshTools` commits it as a healthy refresh. No client installed is the SHIPPED state —
    // nothing under `server/src` calls `useComposioClient` — so `[]` here was the only answer a
    // real Composio refresh could produce, and committing it deleted every recorded action.
    const refused = listTools({ url: "composio://gmail" });

    await expect(refused).rejects.toThrow(
      /not configured for this deployment/i,
    );

    const thrown = (await refused.catch((error: unknown) => error)) as Error;
    expect(thrown.message).toContain("gmail");
    // Not a crash report. No deployment installs a client yet, so an operator reading this has to
    // recognise a state rather than go hunting for a fault.
    expect(thrown.message).toMatch(/expected/i);
  });

  test("a url that names no app throws about the url, and asks nobody", async () => {
    /*
     * THE REFUSAL IS ONLY HALF THE CLAIM, and this test used to make only that half.
     *
     * With the default stub answering `[]`, nothing here noticed whether Composio had been asked
     * at all — so the guard could be moved to after the dial and every assertion below still
     * passed, while the transport handed `https://example.com` to the vendor as an app slug. That
     * is the failure the guard exists to prevent: `toolkitOf` is what keeps a url this deployment
     * cannot read from becoming a request, and a test that cannot tell a refusal from a round trip
     * is not testing the guard.
     */
    const asked: unknown[] = [];
    useComposioClient(
      recording({
        listActions: async (toolkit, page) => {
          asked.push({ toolkit, page });
          return [];
        },
      }).client,
    );

    const refused = listTools({ url: "https://example.com" });

    // The two refusals send an operator to different places — one to this deployment's
    // configuration, one to the row — so they must not share a sentence.
    await expect(refused).rejects.toThrow(/does not name a Composio app/i);

    const thrown = (await refused.catch((error: unknown) => error)) as Error;
    expect(thrown.message).not.toMatch(/not configured/i);
    expect(thrown.message).toContain("https://example.com");
    expect(asked).toEqual([]);
  });

  test("a listing the vendor's own schema rejects throws a sentence, not a Zod dump", async () => {
    const issues = [
      {
        code: "invalid_type",
        expected: "string",
        received: "number",
        path: ["slug"],
        message: "Expected string, received number",
      },
    ];
    useComposioClient(
      recording({
        listActions: async () => {
          // What `ToolSchema` throws: `message` is the issue array as JSON, which is what would land
          // in `lastError` and, before `refreshTools` existed, in a model's context.
          throw Object.assign(new Error(JSON.stringify(issues, null, 2)), {
            name: "ZodError",
            issues,
          });
        },
      }).client,
    );

    const refused = listTools({ url: "composio://gmail" });

    // Propagated rather than answered empty, because `refreshTools` records a throw in `lastError`
    // and leaves the tools it already holds alone. An empty answer would read as an app that has no
    // actions, and every grant would point at a name nothing advertises.
    await expect(refused).rejects.toThrow(/did not match/i);

    const thrown = await refused.catch((error: unknown) => error);
    expect(String((thrown as Error).message)).not.toContain("invalid_type");
    expect(String((thrown as Error).message)).toContain("gmail");
  });

  test("a listing that failed with nothing said still names the app it was about", async () => {
    // The other arm of `listingSentence`'s fallback, which nothing reached. `refreshTools` puts
    // this string in the row's `lastError` and an administrator reads it off the Plugins page, so
    // a blank one is a refresh that reports having failed and declines to say about what.
    for (const thrown of [{ status: 502 }, new Error(""), new Error("   ")]) {
      useComposioClient(
        recording({
          listActions: async () => {
            throw thrown;
          },
        }).client,
      );

      const message = await listTools({ url: "composio://gmail" }).then(
        () => "",
        (error: unknown) => (error as Error).message,
      );

      expect(message.trim()).not.toBe("");
      expect(message).toContain("gmail");
    }
  });

  test("a listing failure carrying only the vendor's placeholder says something else", async () => {
    /*
     * `callTool` already refuses to pass "Error executing the tool X" on, and the listing path did
     * not. Same string, same reader: `refreshTools` writes this sentence into the row's
     * `lastError` and an administrator reads it off the Plugins page, where the name of the thing
     * they asked to refresh is the one fact they already have.
     */
    useComposioClient(
      recording({
        listActions: async () => {
          throw new Error("Error executing the tool GMAIL_FETCH_EMAILS");
        },
      }).client,
    );

    const message = await listTools({ url: "composio://gmail" }).then(
      () => "",
      (error: unknown) => (error as Error).message,
    );

    expect(message).not.toMatch(/error executing the tool/i);
    expect(message).toContain("gmail");
  });

  test("a listing refusal this deployment authored beats whatever the vendor said", async () => {
    /*
     * THE RULE THIS PATH NEVER ASKED ABOUT. `routes.ts` reads `brokerSentence` first and
     * `vendorSentence` second, and `callTool`'s own catch was corrected to the same order; this one
     * consulted `brokerSentence` nowhere at all. `./composio-adapter`'s `askVendor` wraps the raw
     * tool listing exactly as it wraps the execute, so a `BrokerRefusalError` arrives here as
     * readily as it arrives there — and an authored sentence is the only one that names the step
     * that clears the condition.
     *
     * WHAT IT LOST TO IS A READ ONE LEVEL SHALLOW, the same way it did on the call path.
     * `vendorRefusal` authors only where `vendorSentence` of the ORIGINAL was null, so asking the
     * WRAPPER the same question lands somewhere the adapter never judged and comes back with
     * whatever sits there — below, two words naming nothing, in place of a remedy.
     */
    const authored =
      'Composio refuses a call whose toolkit version is "latest", and that is the version travelling with this one, so gmail\'s action list was not refreshed and the tools already held are untouched. A dated version is recorded when an app\'s actions are listed, so refreshing gmail\'s tools on its Plugins page replaces "latest" with a version Composio will accept.';

    useComposioClient(
      recording({
        listActions: async () => {
          throw new BrokerRefusalError(authored, {
            cause: { error: { error: { message: "Invalid request" } } },
          });
        },
      }).client,
    );

    const message = await listTools({ url: "composio://gmail" }).then(
      () => "",
      (error: unknown) => (error as Error).message,
    );

    // Pinned whole rather than by a fragment, for the reason its sibling on the call path is: a
    // substring check passes on a sentence joined to the vendor's or cut short of the remedy.
    expect(message).toBe(authored);
    expect(message).not.toContain("Invalid request");
  });

  test("a listing that failed with no wrapper still carries the vendor's sentence", async () => {
    /*
     * `./composio-adapter`'s listing calls `client.tools.list` directly, with no try around it, so
     * what lands here is `@composio/client`'s own error — see {@link unwrapped}. `refreshTools` writes this string into the row's
     * `lastError` for an administrator to read off the Plugins page, and what it used to write was
     * a status code followed by the entire response body.
     */
    useComposioClient(
      recording({
        listActions: async () => {
          throw unwrapped("Composio holds no auth config for gmail.");
        },
      }).client,
    );

    const message = await listTools({ url: "composio://gmail" }).then(
      () => "",
      (error: unknown) => (error as Error).message,
    );

    expect(message).toBe("Composio holds no auth config for gmail.");
    // The error carries the whole HTTP response beside the sentence. None of it belongs on an
    // admin page, in an audit row, or in a model's context.
    expect(message).not.toContain("must-not-appear");
    expect(message).not.toContain("x-request-id");
  });

  test("a listing failure whose body says nothing is not answered with the body", async () => {
    /*
     * WHAT ESCAPES WHEN THERE IS NO SENTENCE HAS TO BE WORTH SHOWING. `APIError` builds its message
     * by JSON-stringifying the whole body behind the status code where the body has no top-level
     * `message`, so the fallback to the thrown message handed an operator a response dump — the
     * same thing the Zod-dump refusal above exists to stop, arriving through a different door.
     */
    useComposioClient(
      recording({
        listActions: async () => {
          throw dumped({
            detail: [{ loc: ["body", "toolkit"], msg: "unrecognised" }],
            request_id: "must-not-appear",
          });
        },
      }).client,
    );

    const message = await listTools({ url: "composio://gmail" }).then(
      () => "",
      (error: unknown) => (error as Error).message,
    );

    expect(message).not.toContain("must-not-appear");
    expect(message).not.toContain("unrecognised");
    expect(message).not.toContain("{");
    expect(message).toContain("gmail");
  });

  test("a destructive action is listed as destructive", async () => {
    /*
     * THE ONE CLASSIFICATION THAT MATTERS MOST, AND NOTHING STOOD OVER IT. `effectOf` is asserted
     * on both answers directly, but every assertion that reached this mapping asserted
     * `destructive: false` — so hardcoding `destructive: false` here left the whole suite green,
     * and the field a Bot is gated on before it runs a dangerous action was pinned by nobody.
     *
     * `store.ts` records it on the `mcp_tools` row and a grant is what a person approves against
     * it: an action recorded as safe that deletes a mailbox is approved once and run for ever.
     */
    useComposioClient(
      recording({
        listActions: async () => [
          GMAIL_READ,
          {
            slug: "GMAIL_DELETE_MESSAGE",
            description: "Delete a message.",
            tags: ["destructiveHint"],
            version: "20260903_00",
          },
        ],
      }).client,
    );

    const listed = await listTools({ url: "composio://gmail" });

    // Both rows, so the assertion fails on a mapping that hardcodes EITHER answer rather than
    // reading the labels.
    expect(
      listed.map((tool) => `${tool.name}: ${tool.effect}/${tool.destructive}`),
    ).toEqual([
      "GMAIL_FETCH_EMAILS: read/false",
      "GMAIL_DELETE_MESSAGE: write/true",
    ]);
  });

  test("an action Composio described in no words is listed with an empty description", async () => {
    /*
     * `description` is optional on the vendor's tool and `ListedTool`'s is not, so the mapping has
     * to supply something. Nothing asserted which: `?? "no description available"`, `?? tool.name`
     * and `?? null` all left the suite green, and the last of those is a row `store.ts` writes as
     * NULL against a NOT NULL column.
     *
     * The empty string is the honest answer — the vendor said nothing, so this deployment says
     * nothing rather than inventing a sentence a model will read as the action's own.
     *
     * AND `null` IS THE SAME ABSENCE, which is the limit on the refusal further down, the same
     * limit the tags and version guards draw on the fields beside this one. "Composio described
     * this action in no words" is a real state with an answer already, `null` is how JSON spells
     * it, and `?? ""` has always read it that way. Refusing it would abort the WHOLE listing for
     * the app — every other action's effect, version and grant — over a field that reads fine.
     */
    useComposioClient(
      recording({
        listActions: async () =>
          [
            {
              slug: "GMAIL_ODD",
              tags: ["readOnlyHint"],
              version: "20260903_00",
            },
            {
              slug: "GMAIL_NULL_DESCRIPTION",
              description: null,
              tags: ["readOnlyHint"],
            },
          ] as unknown as ComposioAction[],
      }).client,
    );

    const [tool, nulled] = await listTools({ url: "composio://gmail" });

    expect(tool?.description).toBe("");
    expect(nulled?.description).toBe("");
    // Asserted separately from `toEqual`, which treats a key holding `undefined` as a key that is
    // not there and would accept the fallback being dropped altogether.
    expect(Object.keys(tool ?? {})).toContain("description");
    expect(Object.keys(nulled ?? {})).toContain("description");
  });

  test("an answer that is not a list of actions throws a sentence, not a TypeError", async () => {
    /*
     * `ComposioActions` is OUR projection of the vendor, implemented by an adapter nobody has
     * written yet, and TypeScript polices none of what a promise actually resolves to at runtime.
     * A client that answers `null` — a 204, an SDK path that returns before assigning, a mock in
     * somebody's staging deployment — used to reach `actions.length` and `actions.filter` outside
     * the try that wraps the vendor's call, so what propagated was `null is not an object`. That
     * lands verbatim in `lastError` on the Plugins page and tells an administrator nothing about
     * which app or what to do, which is the whole reason this path throws sentences.
     */
    // `[null]` is the same failure one level down: it clears `Array.isArray` and then reaches
    // `action.inputParameters` in the filter, which is outside that try as well.
    // NOT `"gmail"` AS THE SCALAR, which is what this loop used to carry: the assertion below is
    // that the sentence names the app, and a shape that IS the app's name satisfies it whether the
    // name came from the url or from the malformed answer being echoed back.
    for (const shape of [
      null,
      undefined,
      { items: [] },
      "an action list",
      [null],
    ]) {
      useComposioClient(
        recording({
          listActions: async () => shape as unknown as ComposioAction[],
        }).client,
      );

      const message = await listTools({ url: "composio://gmail" }).then(
        () => "",
        (error: unknown) => (error as Error).message,
      );

      expect(message).toContain("gmail");
      expect(message).not.toMatch(/is not an object|is not a function/i);
    }
  });

  test("an action with no slug breaks the listing rather than being dropped from it", async () => {
    /*
     * The slug is the action's whole identity: `name` in `mcp_tools`, which is NOT NULL and half
     * the primary key, the string a grant records, and the `slug` `callTool` sends back to call it.
     * An element without one reached the map and became a tool named `undefined`, so one malformed
     * action in a listing of sixty took the entire app's refresh down on the insert.
     *
     * REFUSED RATHER THAN SKIPPED, which is what this asserts. Skipping would hand `refreshTools` a
     * SHORT listing, and it commits a listing as the complete truth about the app: the replace is a
     * delete and an insert, so every recorded action missing from it is deleted along with its
     * `version`, under a refresh that reported success. Nobody could even be told which action went
     * missing, because the thing that names it is the thing that is not there.
     */
    for (const slug of [undefined, null, "", "   ", 7]) {
      useComposioClient(
        recording({
          listActions: async () =>
            [
              GMAIL_READ,
              { slug, description: "Nameless.", tags: ["readOnlyHint"] },
            ] as unknown as ComposioAction[],
        }).client,
      );

      const outcome = await listTools({ url: "composio://gmail" }).then(
        () => "the listing was committed",
        (error: unknown) => (error as Error).message,
      );

      // The success arm says nothing about a slug, so this is the refusal and not a message match.
      expect(outcome).toContain("slug");
      expect(outcome).toContain("gmail");
    }
  });

  test("a version made only of whitespace is recorded as no version at all", async () => {
    /*
     * TRIMMED ON THE WAY IN BECAUSE IT IS TRIMMED ON THE WAY OUT. `callTool` trims the recorded
     * version and refuses an empty one, so a blank string that counts as a version here is written
     * to `mcp_tools` as a version this deployment believes it has and is then permanently
     * unusable — and the refusal the caller gets names a refresh, which rewrites the same blank.
     * That is exactly the loop the test above reasons about, reached by recording rather than by
     * the vendor publishing nothing.
     */
    useComposioClient(
      recording({
        listActions: async () => [
          { slug: "GMAIL_BLANK", tags: ["readOnlyHint"], version: "   " },
          {
            slug: "GMAIL_PADDED",
            tags: ["readOnlyHint"],
            version: " 20260903_00\n",
          },
        ],
      }).client,
    );

    const [blank, padded] = await listTools({ url: "composio://gmail" });

    expect(Object.keys(blank ?? {})).not.toContain("version");
    // Recorded as the version `callTool` will actually send, rather than as one it has to repair.
    expect(padded?.version).toBe("20260903_00");
  });

  test("the name recorded is the slug the guard measured, without its padding", async () => {
    /*
     * The guard above admits an action by measuring `slug.trim()`, and the version beside it is
     * recorded trimmed for a reason this file writes down — so the name went to `mcp_tools` and on
     * to Composio with the padding still on it. That name is NOT NULL and half the primary key, it
     * is what a grant records, and it is the `slug` `callTool` sends back; a row keyed on
     * " GMAIL_FETCH_EMAILS " is a different action from the one anybody granted.
     */
    useComposioClient(
      recording({
        listActions: async () => [
          { ...GMAIL_READ, slug: " GMAIL_FETCH_EMAILS\n" },
        ],
      }).client,
    );

    const [tool] = await listTools({ url: "composio://gmail" });

    expect(tool?.name).toBe("GMAIL_FETCH_EMAILS");
  });

  test("a slug listed twice is listed twice, because the collision is settled downstream", async () => {
    /*
     * WHY THIS IS NOT A FIFTH REFUSAL, written down because it was proposed as one. `mcp_tools`
     * holds one row per name, so a vendor naming an action twice IS a collision — and
     * `storableTools` in `./store` already resolves it before a transaction is opened, keying the
     * insert by name and keeping the first occurrence. "a vendor naming one action twice records it
     * once" in `plugin-store.integration.test.ts` pins that end: one row, and `lastError` null.
     * Refusing here would replace a healthy refresh with a total failure and strand every grant on
     * the app — the loss the refusals around this one exist to prevent, caused by one of them.
     *
     * WHAT THIS PATH DOES OWE THAT DE-DUPLICATION is the name it de-duplicates by. The map records
     * the trimmed slug, so two spellings of one action arrive downstream as one name rather than
     * as two rows the database will happily keep apart.
     */
    useComposioClient(
      recording({
        listActions: async () => [
          GMAIL_READ,
          {
            ...GMAIL_READ,
            slug: "  GMAIL_FETCH_EMAILS  ",
            description: "Fetch emails, listed again.",
            version: "20260101_00",
          },
        ],
      }).client,
    );

    const listed = await listTools({ url: "composio://gmail" });

    expect(listed.map((tool) => tool.name)).toEqual([
      "GMAIL_FETCH_EMAILS",
      "GMAIL_FETCH_EMAILS",
    ]);
  });

  test("tags that are not a list of labels break the listing rather than the runtime", async () => {
    /*
     * `effectOf` builds a Set out of whatever is in this field, and the element guard above only
     * settles that the action is an object. A `tags` that is not iterable throws
     * `{} is not iterable` out of a map that sits OUTSIDE the try wrapping the vendor's call, so
     * that string is what `refreshTools` writes into `lastError` for a person to read.
     *
     * A STRING IS THE WORSE HALF, because it does not throw at all: `new Set("readOnlyHint")`
     * yields its characters, no hint matches, and a read-only action is recorded as a write. That
     * is the silent wrong answer a refusal exists to prevent, so both shapes are refused rather
     * than repaired.
     */
    for (const tags of [{}, "readOnlyHint", 7, { 0: "readOnlyHint" }]) {
      useComposioClient(
        recording({
          listActions: async () =>
            [
              GMAIL_READ,
              { slug: "GMAIL_ODD", description: "Odd labels.", tags },
            ] as unknown as ComposioAction[],
        }).client,
      );

      const outcome = await listTools({ url: "composio://gmail" }).then(
        () => "the listing was committed",
        (error: unknown) => (error as Error).message,
      );

      expect(outcome).not.toBe("the listing was committed");
      expect(outcome).toContain("GMAIL_ODD");
      expect(outcome).toContain("gmail");
      expect(outcome).not.toMatch(/is not iterable|is not a function/i);
    }
  });

  test("a list whose labels are not labels records no action as safe", async () => {
    /*
     * THE CONTAINER WAS CHECKED AND ITS CONTENTS WERE TRUSTED, which is the third distinct way this
     * one field has been found unheld. `Array.isArray` settles that `tags` can be iterated and says
     * nothing about what comes out, and `effectOf` decides by `Set.has("destructiveHint")` — an
     * identity comparison that no non-string element can ever satisfy. So a destructive action
     * whose labels arrive as objects, as nested arrays or as numbers is recorded with
     * `destructive: false`.
     *
     * WHICH IS THE SAME SILENT WRONG ANSWER THE STRING CASE ABOVE IS REFUSED FOR, and worse in the
     * direction it fails. `new Set("readOnlyHint")` at least loses a READ, and an action wrongly
     * called a write is only asked about too often. This loses the DESTRUCTIVE flag, and that field
     * is what decides whether a Bot is stopped before it runs the action at all — nobody sees it is
     * wrong, because a row that says "not destructive" looks exactly like an action that is not.
     *
     * `["readOnlyHint", 7]` IS HERE BECAUSE THE HOLE IS PER-ELEMENT. A list that is mostly labels is
     * the shape a vendor actually sends when one entry is malformed, and a guard written as "are
     * any of these strings" rather than "are all of these strings" would pass it.
     */
    for (const tags of [
      [["destructiveHint"]],
      [{ name: "destructiveHint" }],
      [123],
      [null],
      ["readOnlyHint", 7],
    ]) {
      useComposioClient(
        recording({
          listActions: async () =>
            [
              GMAIL_READ,
              { slug: "GMAIL_DELETE_DRAFT", description: "Delete.", tags },
            ] as unknown as ComposioAction[],
        }).client,
      );

      const outcome = await listTools({ url: "composio://gmail" }).then(
        (listed) =>
          `the listing was committed, as ${JSON.stringify(
            listed.map((tool) => [tool.name, tool.destructive]),
          )}`,
        (error: unknown) => (error as Error).message,
      );

      const named = JSON.stringify(tags);
      // NAMED IN THE SUCCESS ARM, so the failure message says what was recorded rather than only
      // that something was. The wrong answer this test exists for is a specific pair —
      // ["GMAIL_DELETE_DRAFT",false] — and a reader of a red run should not have to go and find it.
      expect(`${named}: ${outcome}`).not.toContain("the listing was committed");
      expect(outcome).toContain("GMAIL_DELETE_DRAFT");
      expect(outcome).toContain("gmail");
      expect(outcome).not.toMatch(/is not iterable|is not a function/i);
    }
  });

  test("an absent tags list is still absent rather than unreadable", async () => {
    /*
     * THE LIMIT ON THE TWO REFUSALS ABOVE, AND THE SAME ONE THE VERSION GUARD BELOW ALREADY DRAWS.
     * "This action carries no labels" is a real state with an answer already — `effectOf` reads the
     * field as `tags ?? []` and lands the action on write, which is what an unlabelled action is —
     * and `null` is how JSON spells it. Refusing it would abort the WHOLE listing for the app, so
     * one action publishing a null strands every other action's effect, version and grant, on every
     * refresh, permanently. That is the loss these refusals exist to prevent rather than to cause.
     *
     * ASKED OF THE FIELD AND NOT OF ITS ELEMENTS. A `tags` of `[null]` is still refused above: the
     * list is present, and a label that is not a label is the silent misclassification that guard
     * is about.
     */
    useComposioClient(
      recording({
        listActions: async () =>
          [
            { slug: "GMAIL_NO_TAGS", description: "Unlabelled." },
            {
              slug: "GMAIL_NULL_TAGS",
              description: "Null labels.",
              tags: null,
            },
          ] as unknown as ComposioAction[],
      }).client,
    );

    const listed = await listTools({ url: "composio://gmail" });

    expect(
      listed.map((tool) => [tool.name, tool.effect, tool.destructive]),
    ).toEqual([
      ["GMAIL_NO_TAGS", "write", false],
      ["GMAIL_NULL_TAGS", "write", false],
    ]);
  });

  test("a version that is not a version breaks the listing rather than the runtime", async () => {
    /*
     * THE FIELD BESIDE THE LABELS, WITH THE FAILURE THE LABELS' GUARD EXISTS TO PREVENT. `version`
     * is read as `action.version?.trim()` in a map that sits OUTSIDE the try wrapping the vendor's
     * call, and `?.` guards nothing but null and undefined — so a number, an object or a boolean
     * throws `action.version?.trim is not a function` out of `listTools`, and that engine sentence
     * is what `refreshTools` writes into the row's `lastError` for an administrator to read.
     *
     * REFUSED RATHER THAN TREATED AS NO VERSION, which is the other candidate repair and the wrong
     * one. An action recorded with no version is permanently uncallable and its refusal names a
     * refresh — which would write the same unreadable field back — and committing the listing
     * deletes the version already held for every OTHER action on the app, which no later refresh
     * reconstructs where Composio publishes none. Keeping what is held is what every sibling
     * refusal on this path does.
     */
    for (const version of [5, { major: 1 }, ["20260903_00"], true]) {
      useComposioClient(
        recording({
          listActions: async () =>
            [
              GMAIL_READ,
              { slug: "GMAIL_ODD_VERSION", tags: ["readOnlyHint"], version },
            ] as unknown as ComposioAction[],
        }).client,
      );

      const outcome = await listTools({ url: "composio://gmail" }).then(
        () => "the listing was committed",
        (error: unknown) => (error as Error).message,
      );

      const named = JSON.stringify(version);
      expect(`${named}: ${outcome}`).not.toBe(
        `${named}: the listing was committed`,
      );
      expect(outcome).toContain("GMAIL_ODD_VERSION");
      expect(outcome).toContain("gmail");
      expect(outcome).not.toMatch(/is not a function|undefined is not/i);
    }
  });

  test("an absent version is still absent rather than unreadable", async () => {
    /*
     * THE LIMIT ON THE REFUSAL ABOVE. "Composio published no version" is a real and common state
     * this file already has an answer for — the action is listed with no version key — and `null`
     * is how JSON spells it. The `?.` in the map has always read null that way, so refusing it
     * would turn a healthy refresh into a total failure for every app that publishes one, which is
     * exactly the loss the refusal above is written to avoid.
     */
    useComposioClient(
      recording({
        listActions: async () =>
          [
            { slug: "GMAIL_NO_VERSION", tags: ["readOnlyHint"] },
            {
              slug: "GMAIL_NULL_VERSION",
              tags: ["readOnlyHint"],
              version: null,
            },
          ] as unknown as ComposioAction[],
      }).client,
    );

    const listed = await listTools({ url: "composio://gmail" });

    expect(listed.map((tool) => tool.name)).toEqual([
      "GMAIL_NO_VERSION",
      "GMAIL_NULL_VERSION",
    ]);
    for (const tool of listed) {
      expect(Object.keys(tool)).not.toContain("version");
    }
  });

  test("a description that is not text breaks the listing rather than the row that records it", async () => {
    /*
     * THE FOURTH FIELD THE MAP READS, AND THE ONE THE OTHER THREE GUARDS LEFT UNHELD.
     *
     * `slug`, `tags` and `version` each have a check above; `description` had none, so whatever the
     * vendor put there travelled into `ListedTool.description` — typed `string`, holding a number,
     * an object or a list. The read that meets it is one module on: `storableTools` in `./store`
     * writes `(tool.description ?? "").replaceAll(NUL, "")`, and `??` guards absence, not type.
     *
     * WHICH FAILS THE WHOLE APP'S REFRESH WITH A SENTENCE ABOUT NOTHING. That throw is caught — the
     * `try` around `storableTools` exists so a vendor's answer never leaves `refreshTools` raw —
     * and what it records in `lastError` is "an action whose schema could not be stored as it
     * arrived" followed by the engine's own `replaceAll is not a function`. Neither half is true or
     * useful: it was not the schema, and nothing in that row names the action or the field, so an
     * administrator has sixty actions to search and a sentence pointing at the wrong one.
     * `plugin-store.integration.test.ts` pins that end.
     *
     * SO IT IS REFUSED HERE, WHERE A SENTENCE CAN STILL NAME THE ACTION, which is the argument the
     * three guards above make and the reason they refuse rather than repair. Defaulting a malformed
     * description to `""` would record the action with the vendor's own words silently dropped, on
     * a row a model reads to decide whether to call it at all.
     */
    for (const description of [
      7,
      { text: "Fetch emails." },
      ["Fetch."],
      true,
    ]) {
      useComposioClient(
        recording({
          listActions: async () =>
            [
              GMAIL_READ,
              {
                slug: "GMAIL_ODD_DESCRIPTION",
                description,
                tags: ["readOnlyHint"],
              },
            ] as unknown as ComposioAction[],
        }).client,
      );

      const outcome = await listTools({ url: "composio://gmail" }).then(
        (listed) =>
          `the listing was committed, as ${JSON.stringify(
            listed.map((tool) => [tool.name, tool.description]),
          )}`,
        (error: unknown) => (error as Error).message,
      );

      const named = JSON.stringify(description);
      // NAMED IN THE SUCCESS ARM for the reason the labels test names its pair: the wrong answer
      // here is a specific value on a specific action, and a red run should say which.
      expect(`${named}: ${outcome}`).not.toContain("the listing was committed");
      expect(outcome).toContain("GMAIL_ODD_DESCRIPTION");
      expect(outcome).toContain("gmail");
      expect(outcome).not.toMatch(/is not a function|undefined is not/i);
    }
  });

  test("a vendor complaint that merely carries issues is not answered with an upgrade", async () => {
    /*
     * `isSchemaMismatch` duck-types on the PRESENCE of an `issues` array, and an array under that
     * name is not the vendor's SDK refusing its own answer. A gateway's validation payload carries
     * one, and so does any error somebody built with a list of complaints in it. Read as a schema
     * mismatch, the one sentence saying what actually went wrong is replaced by an instruction to
     * upgrade a package that is working perfectly.
     */
    for (const thrown of [
      Object.assign(
        new Error(
          "Composio's gmail gateway rejected the query: from: is not a search operator.",
        ),
        { issues: ["from: is not a search operator."] },
      ),
      Object.assign(new Error("Composio rejected the request for gmail."), {
        issues: [{ field: "query", reason: "required" }],
      }),
    ]) {
      useComposioClient(
        recording({
          listActions: async () => {
            throw thrown;
          },
        }).client,
      );

      const message = await listTools({ url: "composio://gmail" }).then(
        () => "",
        (error: unknown) => (error as Error).message,
      );

      // PINNED WHOLE RATHER THAN BY THE ONE WORD EVERY CANDIDATE ANSWER CONTAINS. "rejected" is in
      // the fixture, so it survived the sentence being wrapped, prefixed or cut short — and both
      // of the answers this branch must not give, the upgrade advice and "Composio did not answer
      // with an action list for gmail.", are sentences a fragment check cannot tell from this one.
      expect(message).toBe(thrown.message);
      // And it names the row the operator is looking at, which is what every sibling refusal on
      // this path asserts and this one did not: `refreshTools` writes this string into `lastError`
      // and an administrator reads it off the Plugins page beside a list of apps.
      expect(message).toContain("gmail");
      expect(message).not.toMatch(/upgrad/i);
    }
  });

  test("a listing left empty by the file filter is not committed as an app with no actions", async () => {
    /*
     * THE FILTER CAN EMPTY A LISTING, and an empty listing is the one thing this function's four
     * other refusals exist to prevent. `refreshTools` commits a listing as the complete truth
     * about the app — the replace is a delete and an insert — so every recorded action goes, with
     * its `effect`, `destructive` and `version`, under a refresh that reported success. The
     * versions are the loss no later refresh repairs where Composio publishes none.
     *
     * An app whose actions all need files is not an app with no actions, and the sentence has to
     * say which of the two this is. Both files are REQUIRED here, as they are on Composio's own two
     * Drive uploads: an optional one is removed from the action rather than dropping it, and would
     * leave nothing for this refusal to be about.
     */
    const upload = {
      type: "object",
      properties: {
        file_to_upload: FILE_PROPERTY,
        folder_to_upload_to: { type: "string" },
      },
      required: ["file_to_upload"],
    };
    const onlyFiles = [
      {
        slug: "GOOGLEDRIVE_UPLOAD_FILE",
        description: "Upload a file.",
        tags: ["createHint"],
        version: "20260903_00",
        inputParameters: upload,
      },
      {
        slug: "GOOGLEDRIVE_RESUMABLE_UPLOAD",
        description: "Upload a large file.",
        tags: ["createHint"],
        version: "20260903_00",
        inputParameters: upload,
      },
    ];
    useComposioClient(recording({ listActions: async () => onlyFiles }).client);

    const outcome = await listTools({ url: "composio://googledrive" }).then(
      (listed) => `the listing was committed with ${listed.length} actions`,
      (error: unknown) => (error as Error).message,
    );

    expect(outcome).not.toContain("committed");
    expect(outcome).toContain("googledrive");
    expect(outcome).toMatch(/file/i);
    // The COUNT, which is the only thing separating this refusal from the empty answer asserted
    // below. Both are listings with nothing left in them; a sentence that did not say how many
    // actions the app really published would send an operator looking for the wrong fault.
    expect(outcome).toContain("2");

    /*
     * AND THE VENDOR'S OWN EMPTY ANSWER IS STILL AN ANSWER, which is a decision this file shares
     * with `store.ts` rather than one it makes alone.
     *
     * `@composio/core` used to manufacture an empty listing out of a response it could not read —
     * `getRawComposioTools` ends `if (!tools) { return []; }` (0.18.1,
     * `src/models/Tools.ts:553-557`) — and that half is gone with the wrapper, because
     * `./composio-adapter` refuses an answer that is not a page rather than emptying it. What is
     * left is a listing Composio really did answer with no rows, and it is answered at the layer
     * that does the committing: `refreshTools` has its own empty-listing guard, which
     * keeps every recorded action with its `effect`, `destructive` and `version` whenever an app
     * that holds actions lists none, and stamps no refresh
     * (`plugin-store.integration.test.ts`, "a refresh the vendor answered with no actions at all").
     *
     * Refusing here as well would buy nothing that guard does not hold, and would cost the case it
     * is careful to allow: an app that genuinely advertises nothing stays recordable instead of
     * reading as broken for good. The refusal above is about a listing this deployment emptied,
     * not one that arrived empty.
     */
    useComposioClient(recording({ listActions: async () => [] }).client);
    expect(await listTools({ url: "composio://gmail" })).toEqual([]);
  });

  test("an action this deployment will not offer cannot refuse the listing", async () => {
    /*
     * THE GUARDS ARE ABOUT THE MAP, SO THEY ARE ABOUT THE ACTIONS THE MAP SEES.
     *
     * Each of the three refusals below is written in `./composio` as a fact about the map at the
     * end of `listTools`: a slug that is absent becomes `a tool named undefined that fails the
     * insert`, a `tags` that is not iterable throws `{} is not iterable` out of it, a `version`
     * that is not a string throws `version?.trim is not a function` out of it. The map runs over
     * the OFFERED actions. An action that needs a file never reaches it — the file filter has
     * already dropped it, deliberately and on every refresh — so nothing it carries can reach the
     * thing the guard exists to protect.
     *
     * Asked of the whole listing instead, they cost the opposite of what they buy. A refusal here
     * is a total failure of the refresh: `refreshTools` records the sentence and keeps the rows, so
     * every OTHER action on the app stops being refreshable because of one action this deployment
     * was never going to publish. That is exactly the tool-and-version stranding the refusals were
     * written to prevent, caused by the refusals.
     *
     * The malformed field is paired with a required file in each case, so the only thing keeping
     * the listing alive is that the action was dropped before it was read. Required, because an
     * optional file is removed from an action that is then offered, and its broken field would
     * reach the map after all.
     */
    const dropped: { where: string; action: Record<string, unknown> }[] = [
      { where: "no slug", action: { slug: undefined } },
      { where: "a slug of only padding", action: { slug: "   " } },
      { where: "a slug that is not a string", action: { slug: 7 } },
      {
        where: "tags that are not a list",
        action: { slug: "GMAIL_SEND_EMAIL", tags: {} },
      },
      {
        where: "tags whose labels are not labels",
        action: {
          slug: "GMAIL_SEND_EMAIL",
          tags: [{ name: "destructiveHint" }],
        },
      },
      {
        where: "a version that is not a version",
        action: { slug: "GMAIL_SEND_EMAIL", version: 20260903 },
      },
    ];

    for (const { where, action } of dropped) {
      useComposioClient(
        recording({
          listActions: async () =>
            [
              GMAIL_READ,
              {
                ...action,
                inputParameters: {
                  type: "object",
                  properties: { attachment: FILE_PROPERTY },
                  required: ["attachment"],
                },
              },
            ] as unknown as ComposioAction[],
        }).client,
      );

      const outcome = await listTools({ url: "composio://gmail" }).then(
        (listed) => listed.map((tool) => tool.name),
        (error: unknown) => (error as Error).message,
      );

      expect({ where, outcome }).toEqual({
        where,
        outcome: ["GMAIL_FETCH_EMAILS"],
      });
    }
  });
});

describe("calling one action", () => {
  test("the call runs as the connection's actor, at the recorded version", async () => {
    const { client, calls } = recording();
    useComposioClient(client);

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { query: "is:unread", __version: "20260903_00" },
    );

    expect(calls).toEqual([
      {
        toolkit: "gmail",
        slug: "GMAIL_FETCH_EMAILS",
        userId: "user_asker",
        version: "20260903_00",
        args: { query: "is:unread" },
      },
    ]);
    expect(result.isError).toBe(false);
  });

  test("the app goes out with the call, and follows the url when the url changes", async () => {
    /*
     * THE DEEPEST HOLE THIS TRANSPORT HAD. `toolkitOf` resolved the app, `accessFor` gated the
     * person's `composio_connections` row on it, and then the call went out as the slug alone —
     * and a slug is what a LISTING recorded, not what the url says now. A url edited between a
     * refresh and a call was therefore gated on the app it names today and run against the app it
     * named when the tools were last read: a person who connected Slack satisfying the gate for a
     * Gmail action that still runs in their Gmail.
     *
     * Composio's wire cannot carry the pair — `ToolExecuteParams` has no toolkit field and
     * `tools.execute(toolSlug, params)` takes the slug alone (`@composio/client` 0.1.0-alpha.76,
     * `resources/tools.d.ts:480-493` and `:41`) — so what binds them here is that the app is an
     * argument of the call this module makes and an implementation has to reconcile it with the
     * tool it resolves. Asserting it is passed asserts the implementation was handed the fact it
     * needs; asserting it FOLLOWS the url is the part a check performed and then discarded could
     * never show, and discarding it was the defect.
     */
    const { client, calls } = recording();
    useComposioClient(client);

    for (const app of ["gmail", "slack"]) {
      await callTool(
        { url: `composio://${app}`, actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );
    }

    expect(calls.map((call) => call.toolkit)).toEqual(["gmail", "slack"]);
  });

  test("the version is not passed on to the vendor as an argument", async () => {
    const seen: Record<string, unknown>[] = [];
    useComposioClient(
      recording({
        execute: async (_call, args) => {
          seen.push(args);
          return answered({});
        },
      }).client,
    );

    // Held in a variable rather than written inline, because `seen` showing the version absent
    // shows it only of whatever object the module chose to pass on. Deleting the key from the
    // CALLER'S object and forwarding that satisfies the assertion below while destroying the
    // record the call path still holds — the same identity-for-value mistake the schema test had.
    const args = { query: "is:unread", __version: "20260903_00" };
    await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      args,
    );

    expect(seen).toEqual([{ query: "is:unread" }]);
    expect(args).toEqual({ query: "is:unread", __version: "20260903_00" });
  });

  test("a call with no recorded version refuses rather than guessing one", async () => {
    const { client, calls } = recording();
    useComposioClient(client);

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      {},
    );

    // Composio refuses a call without a specific version and refuses "latest" too. A guessed version
    // is a call against some other revision of the action, which is worse than not calling.
    expect(result.isError).toBe(true);
    expect(result.text).toMatch(/version/i);
    expect(calls).toEqual([]);

    // The refusal used to name a refresh as THE fix, unconditionally. It is not one where the
    // vendor published no version: `listTools` sets the field only when Composio sent one, so a
    // refresh writes the same nothing back and the reader presses the button again. The sentence
    // has to make the remedy conditional on the vendor, which is the part nobody here controls.
    expect(result.text).not.toContain(
      "Refresh this app's tools on its Plugins page and try again.",
    );
    expect(result.text).toMatch(/only if Composio publishes/i);
  });

  test("the version goes out without its padding, and padding alone is no version", async () => {
    /*
     * THE CALL SIDE OF A TRIM THE LISTING SIDE ALREADY TESTS. "a version made only of whitespace is
     * recorded as no version at all" pins what `listTools` writes; nothing pinned what `callTool`
     * sends, so the `.trim()` here could be deleted with the whole suite green.
     *
     * BOTH HALVES OF IT MATTER AND THEY FAIL DIFFERENTLY. A padded version forwarded as it arrived
     * is a string Composio does not match to any revision of the action — the call fails at the
     * vendor, wearing the vendor's words, for a fault that is this deployment's. A version made
     * only of padding is not a version at all, and read as one it sends `"   "` where the module's
     * own refusal says there is nothing to fall back on; the recorded-version guard is the thing
     * that keeps that off the wire, and it is the trim that lets the guard see it.
     *
     * The same two shapes the listing side uses, reached from the other end: `mcp_tools` holds what
     * `listTools` wrote, and `store.ts` hands it back through `__version` on the next call.
     */
    const { client, calls } = recording();
    useComposioClient(client);

    const padded = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: " 20260903_00\n" },
    );

    expect(padded.isError).toBe(false);
    expect(calls.map((call) => call.version)).toEqual(["20260903_00"]);

    const blank = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "   " },
    );

    expect(blank.isError).toBe(true);
    expect(blank.text).toMatch(/no recorded version/i);
    // Refused before dialling, which is the half a message match cannot show: nothing was added to
    // the record above.
    expect(calls).toHaveLength(1);
  });

  test("an actor named in the arguments is ignored, whichever way it is spelled", async () => {
    /*
     * THE HEADLINE PROPERTY OF THIS FILE, AND IT WAS ASSERTED OF HALF THE CALL. The recorder's
     * default `execute` dropped the arguments, so what this test could see was the call record's
     * own `userId` — the half a transport gets right by construction, because it is the field it
     * fills from the connection. What it could not see was the object actually forwarded to the
     * vendor, which is where a model's three spellings of an identity live and where the vendor
     * reads `arguments` from. Both halves go out on one request, so both halves are the claim.
     *
     * ASSERTED AS THE WHOLE CALL rather than field by field, the way the adapter suite's own
     * attribution test is ("a call that runs carries the person, the version and the arguments"):
     * an EXTRA field on this request is as much a finding as a wrong one, and a per-field check is
     * blind to every one of them.
     *
     * THE THREE SPELLINGS TRAVEL ON AS ARGUMENTS, which is the correct outcome and not an
     * oversight. They are the model's own arguments; the vendor is the party that decides what an
     * action's `userId` parameter means, and stripping keys by name would be this module reading
     * `args` for an identity — the very thing that makes the property structural rather than
     * merely checked. What must never happen is one of them reaching the field beside them.
     *
     * THE PERSON IS NAMED AFTER NOTHING ELSE IN THIS FILE, which is what makes the assertion able
     * to tell attribution from coincidence: `user_asker` is the house id every other call here
     * uses, so it is exactly the literal a transport that had stopped reading the connection would
     * most plausibly be hard-coded to.
     */
    const { client, calls } = recording();
    useComposioClient(client);

    const spelled = {
      userId: "user_victim",
      user_id: "user_victim",
      entityId: "user_victim",
    };

    await callTool(
      { url: "composio://gmail", actorId: "user_whose_mailbox_this_is" },
      "GMAIL_FETCH_EMAILS",
      { ...spelled, query: "is:unread", __version: "20260903_00" },
    );

    // The identity is not a field a model fills. This is the defect OpenTag got wrong three times,
    // and the only structural defence is that the argument name is never read.
    expect(calls).toEqual([
      {
        toolkit: "gmail",
        slug: "GMAIL_FETCH_EMAILS",
        userId: "user_whose_mailbox_this_is",
        version: "20260903_00",
        args: { ...spelled, query: "is:unread" },
      },
    ]);
  });

  test("a call with nobody attributed refuses and reaches nothing", async () => {
    /*
     * AN ACTOR MADE OF PADDING IS NOBODY, and that is the half of this guard nothing was asking.
     * Only the absent key was tested, so the `.trim()` in front of the check could be deleted with
     * the suite green — and what it keeps out is worse than an absent id, not better: `" "` is a
     * user id Composio will happily look up, find no connected account for, and refuse. The call
     * would then read as somebody's lapsed connection rather than as a run this deployment never
     * attributed to anybody, which sends the person who reads it to the wrong page.
     *
     * The shapes are the ones an identifier arrives as when something upstream had nothing to put
     * in it: a column read back empty, a header that was sent blank, a value assembled by a shell.
     */
    for (const actorId of [undefined, "", "   ", "\n\t "]) {
      const { client, calls } = recording();
      useComposioClient(client);

      const result = await callTool(
        { url: "composio://gmail", actorId },
        "GMAIL_FETCH_EMAILS",
        {
          __version: "20260903_00",
        },
      );

      const named = JSON.stringify(actorId ?? null);
      expect(`${named}: ${result.isError}`).toBe(`${named}: true`);
      expect(result.text).toMatch(/not attributed to anybody/i);
      expect(calls).toEqual([]);
    }
  });

  test("a thrown failure is reported with the vendor's own sentence", async () => {
    useComposioClient(
      recording({
        execute: async () => {
          throw Object.assign(
            new Error("Error executing the tool GMAIL_FETCH_EMAILS"),
            {
              cause: {
                status: 404,
                headers: { "x-request-id": "must-not-appear" },
                error: {
                  error: {
                    message:
                      "No connected account found for user ID u1 for toolkit gmail",
                  },
                },
              },
            },
          );
        },
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).toContain("No connected account found");
    // The error also carries the whole HTTP response. None of it belongs in a model's context or an
    // audit row.
    expect(result.text).not.toContain("must-not-appear");
    expect(result.text).not.toContain("x-request-id");
  });

  test("a failure with no vendor sentence falls back to the thrown message, whole", async () => {
    /*
     * WHY THIS ONE REFUSAL NAMES NEITHER THE ACTION NOR A REMEDY, which every sibling around it
     * does and which this test used to accept without saying anything about.
     *
     * `toContain` accepted the current answer and would have accepted any of the wrong ones too: a
     * sentence with this deployment's generic advice bolted on, one cut short of the vendor's
     * words, one with the action's name prefixed. So what the fallback actually IS was pinned by
     * nobody, and the difference between the branches is the whole subject of this describe.
     *
     * THE RULE THE MODULE FOLLOWS IS THAT THE WORDS THAT WERE SAID BEAT THE WORDS WE WOULD INVENT,
     * and it is the same rule `listingSentence` follows on the other path. `unexplained` — which
     * names the action and sends the reader to the Plugins page — is what the two sibling tests
     * below assert, and it is reached only where the vendor said NOTHING usable: an empty message,
     * or the placeholder. A transport fault that came with a diagnosis is not that case, and
     * replacing "composio unreachable" with "check that this app is still connected" would be
     * exactly the wrong advice at exactly the wrong moment — the connection is fine and Composio
     * is down. The action's name is in `store.ts`'s audit row beside this sentence either way, and
     * the model reading it has just called the action.
     *
     * So this refusal carrying neither is deliberate, and the test now says so by pinning the
     * answer WHOLE rather than by looking for a fragment inside whatever arrived.
     *
     * THE PADDED ONE IS HERE BECAUSE THE TRIM IS. What comes back is measured by the cap and read
     * by a person, and the module already decided this string was worth passing on — with the
     * padding dropped, the way `vendorSentence` drops it.
     */
    for (const thrown of ["composio unreachable", "  composio unreachable\n"]) {
      useComposioClient(
        recording({
          execute: async () => {
            throw new Error(thrown);
          },
        }).client,
      );

      const result = await callTool(
        { url: "composio://gmail", actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );

      expect(result.isError).toBe(true);
      expect(result.text).toBe("composio unreachable");
      expect(result.truncated).toBe(false);
    }
  });

  test("a thrown client error with no wrapper is reported with its sentence", async () => {
    /*
     * The same correction as the listing's, on the path where the string reaches a model rather
     * than an admin page. See {@link unwrapped} for which calls throw this shape; what used to be
     * handed on for them was a status code followed by the whole response body, which is both the
     * request id this file already refuses to pass on and somebody's context window spent on it.
     */
    useComposioClient(
      recording({
        execute: async () => {
          throw unwrapped("Gmail rejected the query: invalid search syntax.");
        },
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).toBe(
      "Gmail rejected the query: invalid search syntax.",
    );
    expect(result.text).not.toContain("must-not-appear");
    expect(result.text).not.toContain("x-request-id");
  });

  test("a failure whose body says nothing is not answered with the body", async () => {
    // The dump reaching a model, rather than an operator. `unexplained` is the right answer here
    // for the reason it is the right answer to the placeholder: neither says anything the reader
    // can act on, and one of them costs a context window to say it.
    useComposioClient(
      recording({
        execute: async () => {
          throw dumped({
            detail: [{ loc: ["body", "arguments"], msg: "unrecognised" }],
            request_id: "must-not-appear",
          });
        },
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).not.toContain("must-not-appear");
    expect(result.text).not.toContain("unrecognised");
    expect(result.text).not.toContain("{");
    expect(result.text).toMatch(/connected on Connections/);
    expect(result.text).toContain("GMAIL_FETCH_EMAILS");
  });

  test("a result the exact size of the cap is not cut, and one character more is", async () => {
    /*
     * THE BOUNDARY, WHICH IS THE ONLY PLACE A CAP CAN BE WRONG. Every other test here measures a
     * string far over the limit or far under it, so `<=` and `<` answered both of them the same
     * way — and the off-by-one is the version that reports `truncated: true` beside text nothing
     * was taken from, which is a lie in the field whose whole job is telling a model that what it
     * is reading stops early.
     */
    for (const [length, cut] of [
      [RESULT_CAP, false],
      [RESULT_CAP + 1, true],
    ] as const) {
      useComposioClient(
        recording({
          execute: async () => {
            throw new Error("x".repeat(length));
          },
        }).client,
      );

      const result = await callTool(
        { url: "composio://gmail", actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );

      expect(`${length}: ${result.truncated}`).toBe(`${length}: ${cut}`);
      expect(`${length}: ${result.text.length}`).toBe(
        `${length}: ${cut ? CAPPED_LENGTH : RESULT_CAP}`,
      );
      expect(result.text.endsWith(TRUNCATION_MARKER)).toBe(cut);
    }
  });

  test("a result is capped visibly rather than silently", async () => {
    useComposioClient(
      recording({
        execute: async () => answered({ body: "x".repeat(60_000) }),
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    // VISIBLY is the marker and RATHER THAN SILENTLY is the flag, and this test asserted only the
    // flag. `truncated: true` beside text that just stops is exactly the silent cut the name
    // promises against: the model reads a JSON document that ends mid-token and completes it from
    // memory, because nothing in what it was handed says the ending is ours.
    expect(result.isError).toBe(false);
    expect(result.truncated).toBe(true);
    expect(result.text.slice(-TRUNCATION_MARKER.length)).toBe(
      TRUNCATION_MARKER,
    );
    expect(result.text.length).toBe(CAPPED_LENGTH);
  });

  test("a result or a failure over the cap is cut between characters, not through an emoji", async () => {
    /*
     * `slice` counts UTF-16 code units and an emoji is two of them. When the cap lands between the
     * halves, the last unit a model reads is a lone high surrogate: JSON carries it as a bare
     * `\ud83d` and UTF-8 as U+FFFD, a broken character that was never in what Composio sent. A
     * result and a failure go through the same cap, so both are driven to the same boundary.
     */
    const straddling = (lead: number) =>
      `${"x".repeat(lead)}😀${"x".repeat(100)}`;
    // `JSON.stringify(data, null, 2)` writes `{\n  "body": "` before the string, so this puts the
    // emoji's high surrogate on the cap's last unit.
    const opening = '{\n  "body": "'.length;
    const answers = [
      {
        name: "result",
        execute: async () =>
          answered({ body: straddling(RESULT_CAP - opening - 1) }),
      },
      {
        name: "failure",
        execute: async () => {
          throw new Error(straddling(RESULT_CAP - 1));
        },
      },
    ];

    const seen: string[] = [];
    for (const { name, execute } of answers) {
      useComposioClient(recording({ execute }).client);

      const result = await callTool(
        { url: "composio://gmail", actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );

      const kept = result.text.endsWith(TRUNCATION_MARKER)
        ? result.text.slice(0, -TRUNCATION_MARKER.length)
        : result.text;
      const last = kept.charCodeAt(kept.length - 1);
      const lone = last >= 0xd800 && last <= 0xdbff;
      seen.push(
        `${name}: truncated ${result.truncated}, marked ${kept !== result.text}, kept ${kept.length}, ends on a lone surrogate ${lone}`,
      );
    }

    // The orphan is dropped rather than completed, so the cap is never exceeded.
    expect(seen).toEqual([
      `result: truncated true, marked true, kept ${RESULT_CAP - 1}, ends on a lone surrogate false`,
      `failure: truncated true, marked true, kept ${RESULT_CAP - 1}, ends on a lone surrogate false`,
    ]);
  });

  test("an empty answer says so in words rather than being empty", async () => {
    useComposioClient(recording({ execute: async () => answered({}) }).client);

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    // An empty string in front of a model reads as "the action had nothing to say" rather than "there
    // is nothing there", and the model closes the gap from memory. Same reasoning as `resultText`.
    // `data` is a required record, so the empty answer the SDK can actually produce is `{}` — if that
    // did not count, this branch would be unreachable and its promise would be a fiction.
    expect(result.text).toMatch(/returned nothing/i);
    // Nothing to say is not a failure and is not a truncation. Both fields were unasserted, so this
    // branch could have started reporting an error and the test would not have noticed.
    expect(result.isError).toBe(false);
    expect(result.truncated).toBe(false);
  });

  test("an answer the vendor marked unsuccessful is a failure, not content", async () => {
    // `ToolExecuteResponseSchema` makes `successful` REQUIRED and resolves `{ data, error,
    // successful }`, so a 200 answer can carry a failure. Reported as a success it is audited as
    // `mcp.call_succeeded` and the failure is handed to the model as though it were content.
    useComposioClient(
      recording({
        execute: async () =>
          answered(
            {},
            {
              successful: false,
              error: "Gmail rejected the query: invalid search syntax.",
            },
          ),
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).toContain("invalid search syntax");
  });

  test("a successful answer hands the model the action's data and not the envelope", async () => {
    useComposioClient(
      recording({
        execute: async () => ({
          ...answered({ messages: [{ id: "m1" }] }),
          logId: "log_must_not_appear",
        }),
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(false);
    // `successful`, `error` and `logId` are the envelope this transport reads to decide the
    // outcome. Reporting them as content spends a model's context on our own bookkeeping. Pinned
    // as the whole string rather than as three absences, because a list of things that must not
    // appear is only ever as long as the fields the envelope had on the day it was written — the
    // vendor's `sessionInfo` is already in the type and named in none of them.
    expect(result.text).toBe(
      JSON.stringify({ messages: [{ id: "m1" }] }, null, 2),
    );
  });

  test("an unsuccessful answer with no sentence still says something actionable", async () => {
    useComposioClient(
      recording({
        execute: async () => answered({}, { successful: false, error: null }),
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).toContain("GMAIL_FETCH_EMAILS");
    expect(result.text).toMatch(/connected on Connections/);
  });

  test("a failure carrying only the vendor's placeholder says something actionable", async () => {
    // "Error executing the tool X" is the string this module's own comment calls useless. Echoing it
    // tells a person nothing they did not already know: they asked for that tool.
    useComposioClient(
      recording({
        execute: async () => {
          throw new Error("Error executing the tool GMAIL_FETCH_EMAILS");
        },
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    // ASKED OF THE WHOLE STRING, the way the listing-side sibling asks it. A not-equals only
    // refuses the placeholder standing alone, so a refusal that carried it in the middle of a
    // sentence — "GMAIL_FETCH_EMAILS failed: Error executing the tool GMAIL_FETCH_EMAILS" — is the
    // same useless words in a model's context and in the audit row, and passed.
    expect(result.text).not.toMatch(/error executing the tool/i);
    expect(result.text).toMatch(/connected on Connections/);
  });

  test("a failure that carries no message at all still says something actionable", async () => {
    /*
     * The empty-message arm of the fallback, which nothing reached. Both ways of arriving at it are
     * real: `@composio/core` rejects with plain objects on some paths, so `error instanceof Error`
     * is false and there is no message to read at all; and a thrown `Error` whose message is blank
     * or whitespace is what a transport-level abort produces.
     *
     * Passed on unchanged, either one lands in a model's context and in `store.ts`'s audit row as an
     * empty refusal — a failure with `isError: true` and nothing said, which reads to a model as
     * permission to invent a reason and retry.
     */
    for (const thrown of [{ status: 502 }, new Error(""), new Error("  \n ")]) {
      useComposioClient(
        recording({
          execute: async () => {
            throw thrown;
          },
        }).client,
      );

      const result = await callTool(
        { url: "composio://gmail", actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );

      expect(result.isError).toBe(true);
      expect(result.text.trim()).not.toBe("");
      expect(result.text).toContain("GMAIL_FETCH_EMAILS");
      expect(result.text).toMatch(/connected on Connections/);
    }
  });

  test("an enormous vendor sentence is capped in a refusal too, and says so", async () => {
    useComposioClient(
      recording({
        execute: async () =>
          answered({}, { successful: false, error: "x".repeat(60_000) }),
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    // A refusal goes into a model's context exactly as a result does, so an uncapped vendor sentence
    // is the same unbounded spend the success path already refuses to make.
    expect(result.isError).toBe(true);
    expect(result.truncated).toBe(true);
    // "and says so" is the marker, which nothing here used to check.
    expect(result.text.slice(-TRUNCATION_MARKER.length)).toBe(
      TRUNCATION_MARKER,
    );
    expect(result.text.length).toBe(CAPPED_LENGTH);
  });

  test("an enormous thrown message is capped in a refusal too", async () => {
    useComposioClient(
      recording({
        execute: async () => {
          throw new Error("y".repeat(60_000));
        },
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.truncated).toBe(true);
    expect(result.text.slice(-TRUNCATION_MARKER.length)).toBe(
      TRUNCATION_MARKER,
    );
    expect(result.text.length).toBe(CAPPED_LENGTH);
  });

  test("our own serialization failure is not reported as the action having failed", async () => {
    useComposioClient(
      recording({
        execute: async () => {
          const data: Record<string, unknown> = { subject: "hello" };
          // A circular reference, which `JSON.stringify` refuses. The action already ran and the
          // vendor already answered; what fails is this deployment reading that answer.
          data.itself = data;
          return answered(data);
        },
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    // Two different events, and the audit trail has to be able to tell them apart: the vendor did
    // its part here.
    expect(result.text).toMatch(/could not turn that answer into text/i);
    expect(result.text).toContain("GMAIL_FETCH_EMAILS");
  });

  test("the serialization refusal quotes a reason through the same door as the rest", async () => {
    /*
     * THE ONE PATH THAT REACHED A MODEL AND THE AUDIT ROW WITHOUT PASSING THE DOOR AT ALL.
     *
     * Every other refusal in this module reads its candidate sentence through the judgement that
     * refuses the vendor's placeholder and the response dump. This one interpolated a raw
     * `error.message` — whatever `JSON.stringify` threw with — straight into the sentence
     * `store.ts` records, with nothing asked of it. A `toJSON` is the vendor's own hook on the
     * vendor's own data, so what it throws with is theirs; the class of message is the same one
     * refused four lines away, and the guard is not a guard if the string can walk round it.
     *
     * WHAT THE REFUSAL STILL HAS TO SAY is which of the two events this was: the action ran and
     * Composio answered, and it is this deployment that could not read the answer. That claim is
     * this file's own and survives having no reason to quote.
     */
    useComposioClient(
      recording({
        execute: async () =>
          answered({
            attachment: {
              toJSON() {
                throw new Error(RESPONSE_DUMP);
              },
            },
          }),
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).toMatch(/could not turn that answer into text/i);
    expect(result.text).toContain("GMAIL_FETCH_EMAILS");
    expect(result.text).not.toContain("must-not-appear");
    expect(result.text).not.toContain("unrecognised");
    expect(result.text).not.toContain("{");
  });

  test("an answer reporting an error while claiming success is a failure", async () => {
    /*
     * `ToolExecuteResponseSchema` spells `error` and `successful` as two independent required
     * fields and correlates them nowhere; `transformToolExecuteResponse` copies both straight off
     * the wire (`@composio/core` 0.18.1, `src/models/Tools.ts:215-222`). So the combination is a
     * shape the vendor's own schema permits, and keying only on `successful === false` dropped the
     * one sentence in it that says anything — audited as `mcp.call_succeeded`, with the failure
     * handed to the model as though it were content.
     *
     * The strict reading is the safe one and it is also the vendor's: where the SDK has to derive
     * the flag itself it writes `successful: !response.error` (`src/models/Tools.ts:1247`), so a
     * present error IS a failure by their own arithmetic. Same rule as `effectOf` uses for
     * contradictory labels — both at once is somebody else's bug, and we take the strict branch.
     */
    useComposioClient(
      recording({
        execute: async () =>
          answered(
            { messages: [{ id: "m1" }] },
            {
              successful: true,
              error: "Gmail rejected the query: invalid search syntax.",
            },
          ),
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).toContain("invalid search syntax");
    // The data must not be handed over as content beside a reported failure.
    expect(result.text).not.toContain("m1");
  });

  test("an error made of nothing but padding beside a success is still a success", async () => {
    /*
     * The other side of the rule, and the reason it is worded as a SENTENCE rather than as a
     * present field: `successful: !response.error` treats `""` as success, so an empty string is
     * the vendor saying nothing went wrong in the least committal way available to it.
     *
     * THE PADDED ONES ARE THE HALF THAT WAS UNASSERTED. Only `""` was here, so the `.trim()` that
     * decides whether this field says anything could be deleted with the suite green — and what it
     * would cost is the worst outcome on this path: a newline in `error` read as a complaint turns
     * a call that worked into a reported failure, the action's own data is withheld from the model
     * as content, and `store.ts` audits a failure against a call the vendor was perfectly happy
     * with. A blank field is not a sentence here for the same reason it is not one in
     * `vendorSentence`.
     */
    for (const error of ["", "   ", "\n\t", "\r\n "]) {
      useComposioClient(
        recording({
          execute: async () =>
            answered({ messages: [] }, { successful: true, error }),
        }).client,
      );

      const result = await callTool(
        { url: "composio://gmail", actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );

      const named = JSON.stringify(error);
      expect(`${named}: ${result.isError}`).toBe(`${named}: false`);
      expect(result.text).toBe(JSON.stringify({ messages: [] }, null, 2));
    }
  });

  test("a list where the envelope should be is refused, not called an empty success", async () => {
    /*
     * `typeof [] === "object"`, so an array cleared a guard written as a bare `typeof` test and was
     * then read as an envelope: `error` and `successful` came off it as undefined, so nothing was
     * reported, and `data` came off it as undefined, so `resultOf` answered "The action returned
     * nothing." An answer this deployment could not read reached the model as a call that worked
     * and found nothing, and `store.ts` wrote `mcp.call_succeeded` beside it — which is the exact
     * outcome the third kind of failure exists to keep off the trail.
     *
     * Not a hypothetical shape: an envelope unwrapped one level too far, or a client that answers
     * the batch form, is a list where this expects a record.
     */
    for (const shape of [[], [{ data: { messages: [] }, successful: true }]]) {
      useComposioClient(
        recording({
          execute: async () => shape as unknown as ComposioResult,
        }).client,
      );

      const result = await callTool(
        { url: "composio://gmail", actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );

      expect(result.isError).toBe(true);
      expect(result.text).toContain("GMAIL_FETCH_EMAILS");
      expect(result.text).not.toContain("returned nothing");
    }
  });

  test("an object that is not the envelope is refused, not called an empty success", async () => {
    /*
     * THE HOLE THE ARRAY FIX LEFT, WHICH IS EVERY OTHER OBJECT. The guard above this one asked
     * whether an object had arrived, so it caught `[]` and admitted the whole of the rest of the
     * world — and the two shapes it was written about walked straight through it.
     *
     * An envelope unwrapped ONE level, which is what a client reaching one field too far resolves,
     * is the action's own `data` standing where the envelope belongs: `error` and `successful`
     * come off it as absent, so nothing is reported, and `data` comes off it as absent, so
     * `resultOf` answers "The action returned nothing." A bare `{}` does the same by having
     * nothing on it at all. Both reached the model as a call that worked and found nothing, and
     * `store.ts` wrote `mcp.call_succeeded` beside each — while the refusal that never fired
     * claimed the `{ data, error, successful }` envelope had been checked for.
     *
     * THE PARTIAL ONES ARE HERE FOR THE SAME REASON THE WHOLE ONES ARE. An answer carrying two of
     * the three fields is not an envelope either, and each of them lands on the identical false
     * success: no `data` serializes to nothing, and no `successful` reports nothing.
     */
    const shapes: Record<string, unknown> = {
      "an envelope unwrapped one level": { messages: [{ id: "m1" }] },
      "a bare object": {},
      "an envelope with no data": { error: null, successful: true },
      "an envelope with no successful": {
        data: { messages: [{ id: "m1" }] },
        error: null,
      },
      "an envelope whose successful is present as undefined": {
        data: {},
        error: null,
        successful: undefined,
      },
    };

    for (const [shape, answer] of Object.entries(shapes)) {
      useComposioClient(
        recording({
          execute: async () => answer as ComposioResult,
        }).client,
      );

      const result = await callTool(
        { url: "composio://gmail", actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );

      expect(`${shape}: ${result.isError}`).toBe(`${shape}: true`);
      expect(result.text).toContain("GMAIL_FETCH_EMAILS");
      // The two halves of the false success this guard exists to stop: the sentence that reads as
      // a call that worked, and the vendor's data handed over as content beside it.
      expect(result.text).not.toContain("returned nothing");
      expect(result.text).not.toContain("m1");
    }
  });

  test("an error that is not a sentence is not read as silence", async () => {
    /*
     * `ToolExecuteResponseSchema` spells `error` a nullable string, so an object — or the issue
     * list a gateway leaves there — is a field this deployment cannot read. Collapsed to `""` by a
     * `typeof` test, it was indistinguishable from the vendor saying nothing went wrong: the data
     * was handed to the model as content and the call was audited as a success, with the one field
     * carrying the complaint shown to nobody.
     *
     * THE FLAG DECIDES WHICH SENTENCE, because the two states differ. Beside `successful: false`
     * the vendor has already reported the failure and only its reason is unreadable, which is the
     * actionable connection sentence. Beside a claimed success nothing here knows whether the
     * action ran, and that failure is ours rather than the vendor's, so it says so in our words.
     */
    const unreadable = { message: "Quota exceeded.", code: 429 };

    useComposioClient(
      recording({
        execute: async () =>
          ({
            data: { messages: [{ id: "m1" }] },
            error: unreadable,
            successful: true,
          }) as unknown as ComposioResult,
      }).client,
    );

    const claimed = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(claimed.isError).toBe(true);
    expect(claimed.text).toContain("could not read");
    // The data must not be handed over as content beside a complaint nobody could read.
    expect(claimed.text).not.toContain("m1");

    useComposioClient(
      recording({
        execute: async () =>
          ({
            data: {},
            error: unreadable,
            successful: false,
          }) as unknown as ComposioResult,
      }).client,
    );

    const reported = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(reported.isError).toBe(true);
    expect(reported.text).toContain("connected on Connections");
  });

  test("a reported error that is a response dump is refused like the placeholder", async () => {
    /*
     * THE ESCAPE THE EXTRACTION WAS MEANT TO CLOSE, LEFT OPEN ON THE ONE CALLER THAT WAS NOT MOVED.
     *
     * `thrownSentence` was given both refusals — the vendor's placeholder AND the status code
     * followed by a stringified body — precisely so that no path could grow one without the other.
     * This path never went through it: it tested `VENDOR_PLACEHOLDER` against the envelope's `error`
     * field itself, so the second refusal simply did not exist here, and a dump arriving in that
     * field went to the model as the vendor's own report and into `store.ts`'s audit row beside it.
     *
     * BOTH FLAG VALUES, because the dump is equally unreadable under either and the branch that
     * judges the sentence is reached under both. `successful: true` beside a non-empty `error` is
     * already a reported failure by this module's own rule, so the only question left is what is
     * said about it — and a request id and a validation payload are not it.
     */
    for (const successful of [false, true]) {
      useComposioClient(
        recording({
          execute: async () =>
            answered(
              { messages: [{ id: "m1" }] },
              { successful, error: RESPONSE_DUMP },
            ),
        }).client,
      );

      const result = await callTool(
        { url: "composio://gmail", actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );

      const named = `successful: ${successful}`;
      expect(`${named}: ${result.isError}`).toBe(`${named}: true`);
      // Everything the dump would have carried into a model's context and the audit row.
      expect(result.text).not.toContain("must-not-appear");
      expect(result.text).not.toContain("unrecognised");
      expect(result.text).not.toContain("{");
      // And what is said instead names the action and the one thing the reader can do about it,
      // which is what every sibling on this path answers an unreadable report with.
      expect(result.text).toContain("GMAIL_FETCH_EMAILS");
      expect(result.text).toMatch(/connected on Connections/);
      // The data must not be handed over as content beside a reported failure either.
      expect(result.text).not.toContain("m1");
    }
  });

  test("a reported error that is a status code and words is still passed on", async () => {
    /*
     * THE LIMIT ON THE REFUSAL ABOVE, on this path as well as on `vendorSentence`'s. A dump is a
     * status followed by the opening of a JSON document; a status followed by the body's own
     * sentence is the client's other branch and is the most useful thing a reader gets. Widening
     * the refusal to every message that opens with three digits would swap a named cause for
     * advice about a connection that is working, so it has to redden something.
     */
    useComposioClient(
      recording({
        execute: async () =>
          answered(
            {},
            { successful: false, error: "400 Invalid auth config id" },
          ),
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).toBe("400 Invalid auth config id");
  });

  test("a successful flag that is not a boolean is not read as a success", async () => {
    /*
     * `successful !== false` ASKED ONE QUESTION OF A FIELD WITH THREE ANSWERS. The schema spells
     * it a required boolean, but the value is the vendor's and the type is this module's
     * projection — and every shape below is none of them literally `false`, so each one passed as
     * a success: the reported failure was handed to the model as content and `store.ts` audited
     * `mcp.call_succeeded` beside it. This is the same defect the `error` field beside it was
     * fixed for, on the field that decides the outcome outright.
     *
     * `"false"` IS THE ONE THAT PROVES FALSINESS IS NOT THE REPAIR. A non-empty string is truthy,
     * so a plain `!answer.successful` reads the vendor's literal word "false" as a success just as
     * the old check did, and `0` — which no schema permits and no reader can interpret — it would
     * read as a considered no. What is wanted is neither: a field this deployment cannot read is
     * the third kind of failure, and it says so in this file's own words rather than guessing a
     * value for it.
     */
    for (const successful of ["false", 0, null, "true", {}]) {
      useComposioClient(
        recording({
          execute: async () =>
            ({
              data: { messages: [{ id: "m1" }] },
              error: null,
              successful,
            }) as unknown as ComposioResult,
        }).client,
      );

      const result = await callTool(
        { url: "composio://gmail", actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );

      const named = JSON.stringify(successful);
      expect(`${named}: ${result.isError}`).toBe(`${named}: true`);
      expect(result.text).toContain("GMAIL_FETCH_EMAILS");
      // Not the vendor's words: nobody reported this failure, so the sentence must not read as
      // though Composio had. And the data must not travel beside it as content.
      expect(result.text).toMatch(/could not read/i);
      expect(result.text).not.toContain("m1");
    }
  });

  test("an unreadable flag loses to the sentence Composio did send", async () => {
    /*
     * THE SHAPE CHECK ABOVE MUST NOT COST A READER THE ONE USEFUL SENTENCE. A malformed flag
     * beside a real complaint is a failure either way, and "this deployment could not read the
     * flag" is the less actionable of the two things that could be said about it. So the vendor's
     * own words still win, and the check is reached only where the alternative would be calling
     * the answer a success.
     */
    useComposioClient(
      recording({
        execute: async () =>
          ({
            data: {},
            error: "Gmail rejected the query: invalid search syntax.",
            successful: "false",
          }) as unknown as ComposioResult,
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).toContain("invalid search syntax");
    expect(result.text).not.toMatch(/could not read/i);
  });

  test("an answer that is not an envelope refuses rather than throwing", async () => {
    /*
     * THE NEVER-THROW CONTRACT, asserted against the shape that broke it. This module documents a
     * failure as a RESULT and `store.ts` relies on it: a model is mid-run with a person waiting,
     * and an exception ends the turn with nothing said and nothing audited.
     *
     * `reportedFailure(answer, …)` read `answer.successful` outside every try, so a client
     * resolving `null` threw a `TypeError` straight out of `callTool`. Like the listing case, this
     * is a shape `ToolExecuteResponseSchema` forbids and `ComposioActions` cannot police — the
     * projection is ours, the adapter is unwritten, and a runtime resolution is not a type.
     */
    for (const shape of [null, undefined, "ok", 7]) {
      useComposioClient(
        recording({
          execute: async () => shape as unknown as ComposioResult,
        }).client,
      );

      const result = await callTool(
        { url: "composio://gmail", actorId: "user_asker" },
        "GMAIL_FETCH_EMAILS",
        { __version: "20260903_00" },
      );

      expect(result.isError).toBe(true);
      expect(result.text).toContain("GMAIL_FETCH_EMAILS");
      expect(result.text).not.toMatch(/is not an object|undefined is not/i);
    }
  });

  test("a schema mismatch on the way to the call is not handed on as a Zod dump", async () => {
    /*
     * THE SDK'S PARSE RUNS BEFORE THE SDK'S OWN TRY DOES. `./composio-adapter` resolves the tool
     * first — `getRawComposioToolBySlug`, which runs `ToolSchema.parse` — so a vendor answer their
     * schema rejects arrives here as a raw `ZodError`, whose `message` is the issue array as JSON.
     * The listing path has refused that string since the day it was written; this path passed the
     * whole dump to the model and into `store.ts`'s audit row, wearing the vendor's words for a
     * failure that is a version skew between this deployment and their package.
     */
    const issues = [
      {
        code: "invalid_type",
        expected: "string",
        received: "undefined",
        path: ["toolkit", "slug"],
        message: "Required",
      },
    ];
    useComposioClient(
      recording({
        execute: async () => {
          throw Object.assign(new Error(JSON.stringify(issues, null, 2)), {
            name: "ZodError",
            issues,
          });
        },
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).not.toContain("invalid_type");
    expect(result.text).not.toContain("received");
    expect(result.text).toContain("GMAIL_FETCH_EMAILS");
    // A vendor change rather than anything an administrator can do to this connection, so the
    // sentence has to name the one step that helps.
    expect(result.text).toMatch(/upgrad/i);
  });

  test("a placeholder nested in the cause is refused like the thrown one", async () => {
    /*
     * The same string, reached by the route the guard did not cover. `vendorSentence` is preferred
     * over the thrown message, so a placeholder sitting where the useful sentence usually sits was
     * handed to the model past a check written to stop it.
     */
    useComposioClient(
      recording({
        execute: async () => {
          throw Object.assign(
            new Error("Error executing the tool GMAIL_FETCH_EMAILS"),
            {
              cause: {
                error: {
                  error: {
                    message: "Error executing the tool GMAIL_FETCH_EMAILS",
                  },
                },
              },
            },
          );
        },
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    // ANCHORED TO NOTHING, for the reason above: the module's own `VENDOR_PLACEHOLDER` is anchored
    // because it is deciding whether a string IS the placeholder, and this is asking whether a
    // refusal CARRIES it. A start-anchored question of the answer lets it through anywhere but the
    // first character.
    expect(result.text).not.toMatch(/error executing the tool/i);
    expect(result.text).toMatch(/connected on Connections/);
  });

  test("a refusal this deployment authored beats whatever the vendor said", async () => {
    /*
     * THE ORDER `routes.ts` USES, WHICH THIS PATH HAD BACKWARDS. `brokerRefusal` there reads
     * `brokerSentence` first and falls back to `vendorSentence`; this catch read `vendorSentence`
     * first. Both meet the same throws — `./composio-adapter`'s `askVendor` raises a
     * `BrokerRefusalError` out of the execute path as readily as out of a listing — so one vendor
     * condition was answered with two different sentences depending on which door the reader came
     * through, and on this one the authored remedy lost.
     *
     * AND IT LOST TO A READ ONE LEVEL SHALLOW. `vendorRefusal` authors a refusal only where
     * `vendorSentence` of the ORIGINAL error was null, so the vendor keeps the last word wherever
     * it had one. Asking the same question of the WRAPPER is a different question: its `cause` is
     * the original, so the reach for `cause.error.error.message` lands one level in from where it
     * landed before and finds whatever sits there — below, a bare "Invalid request" that the
     * adapter had already judged not to be an explanation.
     *
     * What that costs is the whole point of translating the condition: a sentence naming the step
     * that clears it, replaced by three words naming nothing.
     */
    const authored =
      'Composio refuses a call whose toolkit version is "latest", and that is the version travelling with this one, so GMAIL_FETCH_EMAILS was not run. A dated version is recorded when an app\'s actions are listed, so refreshing gmail\'s tools on its Plugins page replaces "latest" with a version Composio will accept.';

    useComposioClient(
      recording({
        execute: async () => {
          throw new BrokerRefusalError(authored, {
            cause: { error: { error: { message: "Invalid request" } } },
          });
        },
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    // Pinned whole rather than by a fragment: what this asserts is that the authored sentence
    // arrives as its author wrote it, and a substring check would pass on a sentence that had
    // been joined to the vendor's or cut short of the remedy.
    expect(result.text).toBe(authored);
    expect(result.text).not.toContain("Invalid request");
  });

  test("an account the vendor lost travels as a fact on the result, beside its sentence", async () => {
    /*
     * The one authored condition the store acts on: it turns this result into a refusal that
     * offers Reconnect. Read off a field rather than off the wording, so rephrasing the sentence
     * cannot quietly stop the card being drawn — and set on nothing else.
     */
    const authored =
      "Composio holds no connected account for this person and gmail, so GMAIL_FETCH_EMAILS was not run.";
    useComposioClient(
      recording({
        execute: async () => {
          throw new BrokerAccountGoneError(authored);
        },
      }).client,
    );

    const gone = await askAction(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );
    expect(gone.result).toMatchObject({
      isError: true,
      text: authored,
      accountGone: true,
    });
    // Not a verdict on the key: a probe meeting this keeps its "could not find out".
    expect(gone.answered).toBe(false);

    useComposioClient(
      recording({
        execute: async () => {
          throw new BrokerRefusalError("Some other authored refusal.");
        },
      }).client,
    );
    const other = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );
    expect(other.accountGone).toBeUndefined();
  });

  test("a failure this deployment cannot explain still reaches for the vendor's words", async () => {
    // The other half of the precedence, and the reason it is `brokerSentence` rather than
    // `error.message`. `./broker` raises its class only where the sentence names the step that
    // fixes it; a failure it knows nothing about stays a plain `Error`, and for those the vendor's
    // own nested sentence is still worth far more than a generic top-level message.
    useComposioClient(
      recording({
        execute: async () => {
          throw Object.assign(
            new Error("Error executing the tool GMAIL_FETCH_EMAILS"),
            nested(
              "No connected account found for user ID u1 for toolkit gmail",
            ),
          );
        },
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).toContain("No connected account found");
  });

  test("an answer that serializes to nothing at all is refused in this file's own words", async () => {
    /*
     * `JSON.stringify` ANSWERS `undefined` RATHER THAN THROWING for a function, a symbol, or
     * anything else with no JSON form — `ComposioResult` is this module's projection and the value
     * is the vendor's, so that is a shape this path meets rather than one it forbids. The
     * `undefined` then reached the cap, which measures `.length`, and the engine's own
     * `undefined is not an object` became the second half of a sentence this file wrote.
     */
    useComposioClient(
      recording({
        execute: async () => ({
          data: (() => "x") as unknown as Record<string, unknown>,
          error: null,
          successful: true,
        }),
      }).client,
    );

    const result = await callTool(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(result.isError).toBe(true);
    expect(result.text).toMatch(/could not turn that answer into text/i);
    expect(result.text).toContain("GMAIL_FETCH_EMAILS");
    expect(result.text).not.toMatch(
      /is not an object|undefined is not|TypeError/i,
    );
  });
});

/**
 * WHICH FAILURES ARE THE VENDOR'S VERDICT AND WHICH ARE THIS DEPLOYMENT NOT FINDING OUT.
 *
 * `isError` is one flag over three kinds of failure — this transport refusing before it dialled,
 * Composio reporting a failure of a call it made, and an answer nothing here can read — and for a
 * model reading a result that is the right amount of detail: the call did not work, and the sentence
 * says why. For a caller writing the answer down as a verdict on somebody's credential it is not:
 * `probeBrokeredConnection` spends one call to find out whether a key works, and reading `isError`
 * as that verdict made a Composio OUTAGE into a rejected key — which deleted the account somebody
 * had just made and told them their key was refused, and, at the other caller, cleared a working
 * connection's verification.
 *
 * SO THE SEAM ANSWERS IT, and this is where the classification itself is pinned. Each case below is
 * one branch of `askAction`, asserted on the `answered` flag rather than on the sentence, because a
 * sentence is prose and this is a contract: `answered: true` means Composio ran the action in the
 * account and said how it went, and nothing else in the module may claim it.
 */
describe("what a failed call is evidence of", () => {
  test("a call this transport never sent is not a verdict on anything", async () => {
    const { client, calls } = recording();
    useComposioClient(client);

    // No recorded version, which this module refuses before dialling. Nothing went out, so nothing
    // about anybody's credential was established.
    const answer = await askAction(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      {},
    );

    expect(answer.result.isError).toBe(true);
    expect(answer.answered).toBe(false);
    expect(calls).toEqual([]);
  });

  test("a vendor that threw is not a vendor that answered", async () => {
    useComposioClient(
      recording({
        execute: async () => {
          throw new Error("connect ETIMEDOUT 104.18.0.1:443");
        },
      }).client,
    );

    const answer = await askAction(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    // The sentence is still the vendor's, because it is the useful thing for whoever reads it. What
    // it is NOT is evidence: an outage, a socket that closed and a gateway all arrive here.
    expect(answer.result.isError).toBe(true);
    expect(answer.result.text).toMatch(/ETIMEDOUT/);
    expect(answer.answered).toBe(false);
  });

  test("an answer this deployment cannot read is not a verdict either", async () => {
    useComposioClient(
      recording({
        // The envelope's own fields missing, which this module refuses as not being the envelope.
        execute: async () => ({}) as unknown as ComposioResult,
      }).client,
    );

    const answer = await askAction(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(answer.result.isError).toBe(true);
    expect(answer.answered).toBe(false);
  });

  test("a flag neither true nor false is the vendor speaking unreadably, not refusing", async () => {
    useComposioClient(
      recording({
        execute: async () =>
          ({
            data: {},
            error: null,
            successful: "false",
          }) as unknown as ComposioResult,
      }).client,
    );

    const answer = await askAction(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    // Its own sentence says nothing here can tell whether the action ran, and the flag beside it
    // has to agree: a refusal that cannot say the call happened cannot be read as a verdict on it.
    expect(answer.result.isError).toBe(true);
    expect(answer.answered).toBe(false);
  });

  test("a failure Composio reported IS a verdict on the call it ran", async () => {
    useComposioClient(
      recording({
        execute: async () =>
          answered({}, { successful: false, error: "Invalid API key." }),
      }).client,
    );

    const answer = await askAction(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(answer.result.isError).toBe(true);
    expect(answer.result.text).toMatch(/Invalid API key/);
    // The one shape that is: Composio ran the action in the account and said how it went.
    expect(answer.answered).toBe(true);
  });

  test("a call that worked is the plainest answer there is", async () => {
    useComposioClient(
      recording({ execute: async () => answered({ ok: true }) }).client,
    );

    const answer = await askAction(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(answer.result.isError).toBe(false);
    expect(answer.answered).toBe(true);
  });

  test("the account a caller names travels with the call", async () => {
    const { client, calls } = recording();
    useComposioClient(client);

    await askAction(
      {
        url: "composio://gmail",
        actorId: "user_asker",
        accountId: "ca_the_one_just_made",
      },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );
    // And a call that names none sends none, which is what a Bot's ordinary tool call is: any
    // account this person holds for the app will do.
    await askAction(
      { url: "composio://gmail", actorId: "user_asker" },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(calls.map((call) => call.connectedAccountId)).toEqual([
      "ca_the_one_just_made",
      undefined,
    ]);
  });

  /**
   * AND AN ACCOUNT NAMED WITH SOMETHING THAT IS NOT AN ACCOUNT ID IS NOT A CALL TO SEND.
   *
   * The pin was forwarded on `=== undefined` alone, so a blank one went to the wire as an EXPLICIT
   * pin at an account nothing holds. The person's id two lines above is trimmed and refused, which
   * is the treatment this field was owed and did not get: pinning is not decoration here. It was
   * added because a verification spends one call to find out whether ONE key works and writes the
   * answer down as a verdict on the account that key just made — so a pin that misses, and a pin
   * dropped in favour of "whichever account the vendor picks", both end with a verdict about a
   * different account. Both are refusals rather than a call.
   */
  test("an account named as blank space is a refusal rather than a pin nothing holds", async () => {
    const { client, calls } = recording();
    useComposioClient(client);

    const answer = await askAction(
      { url: "composio://gmail", actorId: "user_asker", accountId: "   " },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    // Nothing was sent, so there is no verdict to read either way.
    expect(calls).toEqual([]);
    expect(answer.result.isError).toBe(true);
    expect(answer.answered).toBe(false);
  });

  /**
   * AND `null` IS THE SPELLING A NULLABLE COLUMN USES FOR "NO ACCOUNT IN PARTICULAR", which the
   * `=== undefined` test read as a pin. `{ connectedAccountId: null }` on the wire is a named
   * account rather than the app-level question a re-check asks.
   */
  test("an account named as null is the app-level question rather than a pin", async () => {
    const { client, calls } = recording();
    useComposioClient(client);

    await askAction(
      { url: "composio://gmail", actorId: "user_asker", accountId: null },
      "GMAIL_FETCH_EMAILS",
      { __version: "20260903_00" },
    );

    expect(calls.map((call) => call.connectedAccountId)).toEqual([undefined]);
  });
});