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.
/**
* The Arcade transport's vendor-free half. Imports no vendor package and nothing from
* `arcade-adapter.ts`: the adapter imports this module, never the reverse (see `./broker`, which
* records that the other direction is a cycle).
*/
import { cutAtCodeUnits } from "../channels/text";
import { flagOf } from "./broker";
import { type ListedTool, MAX_RESULT_CHARS, type McpCallResult } from "./mcp";
/**
* Whether listing tools needs somebody's credential. It does not: the listing uses the deployment's
* own Arcade key, and a listing is not a person's.
*/
export const listNeedsCredential = false;
const TOOLKIT_NAME = /^[A-Za-z0-9_-]+$/;
/**
* Which toolkit this connection is about, from `arcade://Toolkit`.
*
* CASE IS PRESERVED AND NOTHING IS NORMALIZED. Arcade's toolkit and action names are case-sensitive,
* and action names are dotted (`Apollo.EnrichOrganization`: the dot separates toolkit from action,
* so a toolkit name never contains one and `TOOLKIT_NAME` rightly rejects it), where Composio's
* slugs are neither, so a lowercased toolkit reaches nothing:
* `arcade://Gmail` and `arcade://gmail` are distinct apps.
*
* ONE TOOLKIT OR NOTHING. This answer is the name the brokered gate looks a person's row up by, so a
* url read loosely is one app's connection satisfying a call against another.
* `arcade://Gmail/messages` must not answer `"Gmail/messages"`: a path segment is not an app.
*
* TRIMMED BEFORE THE SLASHES COME OFF, as `composio.ts` does: the other order leaves a space as the
* last character, so the slash is not at the end and nothing matches.
*/
export function toolkitOf(url: string): string | null {
const prefix = "arcade://";
if (!url.startsWith(prefix)) return null;
const name = url.slice(prefix.length).trim().replace(/\/+$/, "");
return TOOLKIT_NAME.test(name) ? name : null;
}
/**
* What a tool does, from `metadata.behavior`. DESTRUCTIVE IS READ FIRST, and the order is the
* decision: a reading that checked `read_only` first would record a both-flagged tool as a READ,
* the one direction nothing downstream recovers from, since nothing ever asks again.
*
* ABSENT METADATA, OR A FLAG THAT `flagOf` ANSWERS NULL (a vendor publishing a string where it
* documents a boolean), IS A DESTRUCTIVE WRITE, which is also what a listing that would not say
* already records in `./mcp`. It fails safe by putting an approval in front of a read, which is
* annoying and correct; the alternative lets a deletion through unannounced.
*
* AN EMPTY BEHAVIOUR OBJECT IS A VENDOR THAT SAID NOTHING, AND IS READ EXACTLY AS AN ABSENT ONE.
* `{}` — or a block carrying only `idempotent` and the like — states NEITHER flag, so the two
* `flagOf(…, false)` defaults below would otherwise manufacture "not destructive, not read-only"
* out of nothing and answer the plain-write verdict: a container Arcade opened and put nothing in,
* read as Arcade declaring the action safe to run unannounced. The absence of a stated restriction
* is not the absence of a restriction, and an EMPTY container cannot be allowed to be worth more
* than NO container two lines above it.
*
* NOT THE SAME CALL AS `arcade-adapter.ts`'s `connectionIsLive`, WHERE SILENCE IS DELIBERATELY
* PERMISSIVE AND SAYS SO AT LENGTH. There
* the silent field is `connection_status`, optional on the wire, and a pessimistic reading
* un-connects every real connection against any engine that omits it — the cost of failing closed
* falls on people who did nothing wrong. Here the cost of failing closed is one approval prompt in
* front of an action that may turn out to be a read; the cost of failing open is a deletion that
* nobody was asked about. The flags' per-field defaults stand once EITHER flag is stated, which is
* the vendor describing this action rather than saying nothing at all.
*/
export function classify(metadata: unknown): {
effect: "read" | "write";
destructive: boolean;
} {
const closed = { effect: "write", destructive: true } as const;
if (typeof metadata !== "object" || metadata === null) return closed;
const behavior = (metadata as { behavior?: unknown }).behavior;
if (typeof behavior !== "object" || behavior === null) return closed;
const flags = behavior as { destructive?: unknown; read_only?: unknown };
const stated = (value: unknown) => value !== undefined && value !== null;
if (!stated(flags.destructive) && !stated(flags.read_only)) return closed;
const destructive = flagOf(flags.destructive, false);
const readOnly = flagOf(flags.read_only, false);
if (destructive === null || readOnly === null) return closed;
if (destructive) return { effect: "write", destructive: true };
if (readOnly) return { effect: "read", destructive: false };
return { effect: "write", destructive: false };
}
/**
* What this transport needs of Arcade's client, and nothing more: `./arcade-adapter` maps the
* vendor's SDK onto it, so this file imports no vendor package. Mirrors `ComposioActions`.
*
* `listTools` carries no `user_id` by construction: the query type has no such field.
*/
export type ArcadeActions = {
listTools(q: {
toolkit: string;
limit: number;
offset: number;
}): Promise<{ items: unknown[]; total_count?: number }>;
execute(r: {
tool_name: string;
input: Record<string, unknown>;
user_id: string;
}): Promise<{
success?: boolean;
output?: {
value?: unknown;
error?: { message?: string };
authorization?: unknown;
};
}>;
};
let installed: ArcadeActions | null = null;
/** Installs (or, with `null`, removes) the Arcade client. Null is also the unconfigured state. */
export function useArcadeClient(client: ArcadeActions | null): void {
installed = client;
}
export type ArcadeListedTool = ListedTool & { scopes: string[] };
const PAGE_SIZE = 100;
/** A runaway guard, not a bound: 1000 pages of 100 is far past any one toolkit. */
const MAX_PAGES = 1000;
function record(value: unknown): Record<string, unknown> | null {
return typeof value === "object" && value !== null && !Array.isArray(value)
? (value as Record<string, unknown>)
: null;
}
/**
* WHAT ARRIVED WHERE A SHAPE BELONGED, named without quoting it.
*
* A listing row carries whatever the vendor chose to put on it, and a refusal from here is read off
* an admin page, so the SHAPE is the part that is both safe to say and the part that helps —
* `sent` in `composio-adapter.ts` says this at length and this is the same judgement, kept local
* because that file is the other vendor's door and neither imports the other.
*/
export function shapeOf(value: unknown): string {
if (Array.isArray(value)) return "a list";
// `typeof null` IS `"object"`, so the bare template would write "a object" — the wrong grammar
// and, worse, the wrong fact: a hole is not a shape this deployment read and could not use, it
// is the absence of one. The callers that pass a present-but-unreadable field guard both of
// these before asking; `connectionsFor`'s unreadable ROW is the one that can carry a `null`.
if (value === null || value === undefined) return "nothing";
if (typeof value === "string" && value.trim() === "") return "a blank string";
return `a ${typeof value}`;
}
/*
* ---------------------------------------------------------------------------------------------
* THE ONE READING OF A VENDOR AUTHORIZATION FIELD — absent, unreadable, or read.
*
* Every Arcade field this deployment draws an AUTHORIZATION conclusion from is read through one of
* the three functions below, and all three apply the same rule, stated once here:
*
* ABSENT — the key missing, `undefined`, or `null` — is the vendor saying nothing, and answers the
* field's documented default. `null` IS ABSENCE ON EVERY FIELD, NOT ON SOME: the SDK declares
* these fields optional, Arcade sends `metadata: null` and `requirements: null` for "none"
* (`AirtableApi`, `Apollo` in `fixtures/arcade-catalogue.json`), and a serializer that writes an
* unset optional as `null` rather than dropping the key is saying what a missing key says. A rule
* under which `null` meant "absent" on one field and "a value I cannot read" on the next would
* make the same vendor answer mean opposite things one line apart.
*
* UNREADABLE — present, but not the field's shape — is NEITHER default. Each caller decides what
* an unreadable field costs it, and every caller fails CLOSED: the catalogue and the transport
* listing refuse, the grants screen says `unknown`, a connection is not live, a mint is refused.
* A BLANK STRING IS UNREADABLE on a field whose value is a decision. It is present (so it is not
* absence) and carries no value (so it is not text); `authProvidersNamedBy` already refuses a
* blank `provider_id` for exactly this reason. `textOf` in `arcade-adapter.ts` reads a blank
* LABEL as absence, which is right for a display name and is not the question asked here.
*
* READ — the value in this deployment's vocabulary: a status FOLDED AND TRIMMED (a case or a
* space the vendor changes must not change an answer about somebody's account), a scope list
* whose every element is a scope.
*
* WHY ONE READING. `authorizationRequirementOf` (C2) answered this tri-state for the authorization
* block, and every OTHER reader of a field inside or beside it picked its own default for what it
* could not read — the permissive one, each time: a missing `token_status` fell back to the
* PROVIDER's `status: "active"` and drew every action as held; an unreadable `oauth2`/`scopes`
* became `[]`, which the gate reads as "the connection itself is the grant"; a non-text
* `connection_status` read as live; a non-text mint `status` handed a bearer url on as a live
* redirect. One reading means a new reader cannot pick a sixth default by accident.
* ---------------------------------------------------------------------------------------------
*/
/**
* What one listed action's `requirements.authorization` SAYS, read once for every caller that asks.
*
* THE ONE READING OF THIS FIELD'S ABSENCE. Two readers once reached opposite answers on the same
* row: `requiresAuthorization` read a missing block as "needs nothing" and filed the app as
* `no-auth`, while `grantStateOf` read the same silence as "could not be read" and drew every
* action of that app as a broker outage on the grants screen, forever. The vendor's own listing
* settles which is right — `Apollo` publishes NO authorization block and a deployment secret
* instead, verbatim in `fixtures/arcade-catalogue.json` — so `null` and an absent field are
* `none`, here and therefore everywhere.
*
* A PRESENT FIELD THIS DEPLOYMENT CANNOT READ IS NEITHER ANSWER. It is `unreadable`, with WHICH
* field and the shape that arrived there, and each caller decides what an unreadable row costs it:
* the catalogue refuses, the grants screen says `unknown`.
*
* HERE, IN THE TRANSPORT, AND NOT IN THE ADAPTER, because the transport's own listing reads the same
* block for the scopes the gate checks, and the adapter imports this module, never the reverse.
*/
export type AuthorizationRequirement =
| { kind: "none" }
| {
kind: "unreadable";
field: "requirements" | "authorization";
shape: string;
}
| { kind: "required"; authorization: Record<string, unknown> };
export function authorizationRequirementOf(
item: unknown,
): AuthorizationRequirement {
const requirements = record(item)?.requirements;
if (requirements === undefined || requirements === null) {
return { kind: "none" };
}
if (typeof requirements !== "object" || Array.isArray(requirements)) {
return {
kind: "unreadable",
field: "requirements",
shape: shapeOf(requirements),
};
}
const authorization = (requirements as Record<string, unknown>).authorization;
if (authorization === undefined || authorization === null) {
return { kind: "none" };
}
if (typeof authorization !== "object" || Array.isArray(authorization)) {
return {
kind: "unreadable",
field: "authorization",
shape: shapeOf(authorization),
};
}
return {
kind: "required",
authorization: authorization as Record<string, unknown>,
};
}
/**
* The OAuth scopes one listed action asks for — `requirements.authorization.oauth2.scopes` — read
* by {@link authorizationRequirementOf}'s rule, one level further in.
*
* `[]` IS A CLAIM, NOT A SHRUG. An action whose scopes are `[]` is one whose connection IS the
* grant (Github's 43 actions publish exactly that), and the gate, the catalogue's counts and the
* grants screen all read it so. So `[]` is answered only when the vendor SAID it: no authorization
* block, an `oauth2` absent or `{}`, a `scopes` absent or `[]`. An `oauth2` or a `scopes` in any
* other shape is `unreadable`, and so is a list holding anything but scope text: `["repo", 5]`
* read as `["repo"]` would be a narrower grant than the one the vendor described, which is the same
* fail-open answer one element at a time.
*/
export type ScopesRequirement =
| { kind: "read"; scopes: string[] }
| {
kind: "unreadable";
field: "requirements" | "authorization" | "oauth2" | "scopes";
shape: string;
};
export function requiredScopesOf(item: unknown): ScopesRequirement {
const read = authorizationRequirementOf(item);
if (read.kind === "none") return { kind: "read", scopes: [] };
if (read.kind === "unreadable") return read;
const oauth2 = read.authorization.oauth2;
if (oauth2 === undefined || oauth2 === null) {
return { kind: "read", scopes: [] };
}
if (typeof oauth2 !== "object" || Array.isArray(oauth2)) {
return { kind: "unreadable", field: "oauth2", shape: shapeOf(oauth2) };
}
const scopes = (oauth2 as Record<string, unknown>).scopes;
if (scopes === undefined || scopes === null) {
return { kind: "read", scopes: [] };
}
if (!Array.isArray(scopes)) {
return { kind: "unreadable", field: "scopes", shape: shapeOf(scopes) };
}
const odd = scopes.findIndex(
(scope) => typeof scope !== "string" || scope.trim() === "",
);
if (odd !== -1) {
return {
kind: "unreadable",
field: "scopes",
shape: `a list holding ${shapeOf(scopes[odd])}`,
};
}
return { kind: "read", scopes: scopes as string[] };
}
/**
* One vendor STATUS field — `token_status`, `connection_status`, a mint's or a flow's `status` —
* read by the rule above: absent, unreadable, or its text FOLDED AND TRIMMED.
*
* NOT `textOf`, deliberately: `textOf` answers a blank string as absence, which is right for a
* label and wrong for a decision, and it does not fold. Each status reader once spelled its own
* `textOf(x)?.trim().toLowerCase()` (or forgot to), and the one that forgot answered a vendor-side
* change of case differently from the ones that did.
*/
export type VendorStatus =
| { kind: "absent" }
| { kind: "unreadable"; shape: string }
| { kind: "text"; text: string };
export function vendorStatusOf(value: unknown): VendorStatus {
if (value === undefined || value === null) return { kind: "absent" };
if (typeof value !== "string" || value.trim() === "") {
return { kind: "unreadable", shape: shapeOf(value) };
}
return { kind: "text", text: value.trim().toLowerCase() };
}
/** Where on the action a {@link ScopesRequirement} could not be read, in words. */
function scopesFieldOf(
field: Extract<ScopesRequirement, { kind: "unreadable" }>["field"],
): string {
return field === "requirements"
? "requirements"
: field === "authorization"
? "authorization requirement"
: `authorization ${field}`;
}
/**
* The OAuth scopes an action needs, for the tool the gate checks.
*
* NEVER `requirements.met`. The two sit in the same object and behave oppositely: `met` is a
* per-person claim that answers TRUE FOR EVERYBODY when asked without a `user_id` (and this
* listing sends none), while `scopes` is a static property of the action that carries no identity.
* Reading `met` here would record every person as connected to everything, and nothing else would
* go red: the gate would pass, the call would be made, and the first sign would be somebody
* else's mailbox.
*
* AN UNREADABLE SCOPES BLOCK REFUSES THE LISTING; IT IS NEVER `[]`. `[]` on a listed tool is what
* the gate reads as "the connection is the grant", so answering it for a block this deployment
* could not read would let any connection run an action whose real scopes nobody read. See
* {@link requiredScopesOf}. The refusal names the shape, never the vendor's value.
*/
function scopesOf(tool: Record<string, unknown>, toolkit: string): string[] {
const read = requiredScopesOf(tool);
if (read.kind === "read") return read.scopes;
throw new Error(
`Arcade listed one of ${toolkit}'s actions with ${read.shape} where its ${scopesFieldOf(read.field)} belongs, and that is what says which permissions it needs. A shape this deployment cannot read is not "no permissions", so nothing was refreshed and the actions already recorded for this app are kept.`,
);
}
function inputSchemaOf(input: unknown): Record<string, unknown> {
const parameters = record(input)?.parameters;
const properties: Record<string, unknown> = {};
const required: string[] = [];
for (const raw of Array.isArray(parameters) ? parameters : []) {
const parameter = record(raw);
if (!parameter || typeof parameter.name !== "string") continue;
const valType = record(parameter.value_schema)?.val_type;
properties[parameter.name] = {
type: valType === "json" ? "object" : (valType ?? "string"),
description:
typeof parameter.description === "string" ? parameter.description : "",
};
if (parameter.required === true) required.push(parameter.name);
}
return { type: "object", properties, required };
}
/**
* Every action of one toolkit, read to the end.
*
* NO `user_id` IS SENT. A listing is not somebody's: it is what this deployment offers everybody.
*
* PAGINATION STOPS ON A SHORT PAGE, never on `total_count`. That field is optional; an earlier draft
* fell back to `?? tools.length` and so exited after one page. It is used only as a cross-check.
*/
export async function listTools(connection: {
url: string;
}): Promise<ArcadeListedTool[]> {
const toolkit = toolkitOf(connection.url);
if (!toolkit) {
throw new Error(
`${connection.url} does not name an Arcade toolkit, so nothing was asked what it offers. The url has to be arcade:// followed by a toolkit name; correct it on the Plugins page.`,
);
}
if (!installed) {
throw new Error(
`Arcade is not configured for this deployment, so nothing could be asked what ${toolkit} offers. The actions already recorded for this app are kept rather than cleared.`,
);
}
const raw: unknown[] = [];
let total: number | undefined;
let exhausted = true;
for (let page = 0; page < MAX_PAGES; page++) {
let answer: { items: unknown[]; total_count?: number };
try {
answer = await installed.listTools({
toolkit,
limit: PAGE_SIZE,
offset: raw.length,
});
} catch (error) {
/*
* A SENTENCE, NOT THE VENDOR'S OBJECT, as `composio.ts`'s listing does. `refreshTools` puts
* `error.message` on the admin page and into a model's context, and an SDK `APIError` builds
* its message from the whole response body: an unsanitised vendor payload. The original is
* kept as `cause` for a log.
*/
throw new Error(listingSentence(toolkit, error), { cause: error });
}
const items = (answer as { items?: unknown } | null)?.items;
if (!Array.isArray(items)) {
throw new Error(
`Arcade did not answer with an action list for ${toolkit}. Nothing was refreshed and the actions already recorded for this app are kept.`,
);
}
raw.push(...items);
// THE HIGHEST ANY PAGE REPORTED, NEVER THE LAST. An engine that truncates at 250 of 300 drops
// `total_count` from its short final page, and keeping the last value would erase the 300 page
// one reported and commit 250 actions as a complete listing. (`total_count` reaching here is
// already honest about absence: `createArcadeClient` omits the field when the vendor omitted
// it, because the SDK's page object coerces an absent total to `0`.)
if (typeof answer.total_count === "number") {
total =
total === undefined
? answer.total_count
: Math.max(total, answer.total_count);
}
if (items.length < PAGE_SIZE) {
exhausted = false;
break;
}
}
if (exhausted) {
throw new Error(
`Arcade's listing for ${toolkit} never ended after ${MAX_PAGES} pages, so it is not trusted to be a list of this app's actions. Nothing was refreshed and the actions already recorded for this app are kept.`,
);
}
if (total !== undefined && raw.length < total) {
throw new Error(
`Arcade listed ${raw.length} of ${total} actions for ${toolkit}, so the listing is incomplete. Nothing was refreshed and the actions already recorded for this app are kept.`,
);
}
return raw.flatMap((item) => {
const tool = record(item);
if (!tool || typeof tool.qualified_name !== "string") return [];
const offerable = offerableName(tool.qualified_name, toolkit);
if (offerable === null) return [];
return [
{
name: offerable,
/*
* WHAT THE VENDOR IS CALLED BY, kept beside the name this deployment records rather than in
* place of it. `execute` sends this and the refusal sentences in this file quote it; the
* model is offered `name`. See {@link ListedTool.vendorName}.
*/
vendorName: tool.qualified_name,
description:
typeof tool.description === "string" ? tool.description : "",
inputSchema: inputSchemaOf(tool.input),
...classify(tool.metadata),
scopes: scopesOf(tool, toolkit),
},
];
});
}
/**
* The part of an Arcade `qualified_name` this deployment records as the action's name, or null when
* the listing offers nothing that can be one.
*
* ARCADE QUALIFIES EVERY ACTION WITH ITS TOOLKIT — `Gmail.ListEmails` — and the toolkit is already
* the server id, so carrying the prefix would spell the app twice in every ref and every offered
* name. More to the point the dot is ILLEGAL in a model tool name (`^[a-zA-Z0-9_-]+$`), which is
* the defect this function exists to close: recorded whole, the qualified name went into
* `mcp__arcade-Gmail__Gmail.ListEmails` and the model API refused the entire request, every tool in
* it, on the first granted Arcade action.
*
* ONLY THE VENDOR'S OWN PREFIX IS REMOVED, and only when the remainder stands on its own. Anything
* else — a differently-qualified name, a second dot, a character no tool name may carry — is left
* for the guard in `storableTools`, which leaves that one action out and names it on the app's page
* while the rest of the toolkit is recorded, because a listing this does not recognise is not
* something to repair by guessing. That guard is the safety net this function relies on: whatever
* passes through here unrepaired never reaches a model. Dropped here rather than skipped there for
* the one case the vendor's own schema permits and this deployment can do nothing with: an empty
* remainder.
*/
function offerableName(qualifiedName: string, toolkit: string): string | null {
const prefix = `${toolkit}.`;
const bare = qualifiedName.toLowerCase().startsWith(prefix.toLowerCase())
? qualifiedName.slice(prefix.length)
: qualifiedName;
return bare.trim().length === 0 ? null : bare;
}
/** What this deployment says when Arcade's listing could not be read. Never the vendor's words. */
function listingSentence(toolkit: string, _error: unknown): string {
return `Arcade's action list for ${toolkit} could not be read, so nothing was refreshed and the actions already recorded for this app are kept.`;
}
/**
* A failure from Arcade, already normalized and cause-unwrapped by `./arcade-adapter`, so nothing
* here sees an SDK class. `name` is the RESPONSE BODY's `error.name`.
*/
export type ArcadeFailure = {
status: number | undefined;
name: string | undefined;
message: string | undefined;
};
/**
* A REFUSAL FROM ARCADE AS A REAL `Error`, CARRYING THIS DEPLOYMENT'S SENTENCE AND NOT THE VENDOR'S.
*
* TWO DEFECTS IN ONE CLASS, and both were measured rather than imagined.
*
* A BARE OBJECT IS NOT A REASON. `createArcadeClient`'s `execute` used to `throw` the normalized
* failure itself — a plain `{ status, name, message }`. `reasonWithoutStatement`, which is the one
* door every log line in `routes.ts` copies a reason through, answers `String(thrown)` for anything
* that is not an `Error`: the literal text `[object Object]`. So the single log line written at the
* moment a tool call failed carried no information whatsoever, and there was no stack beside it.
*
* AND THE VENDOR'S WORDS ARE DROPPED HERE, which is the half the type enforces. The SDK's `APIError`
* builds its own `message` as `${status} ${body.message ?? JSON.stringify(body)}`
* (`@arcadeai/arcadejs`, `core/error.js: makeMessage`), so an `APIError` allowed to escape the
* adapter puts the vendor's RESPONSE BODY into every reader that quotes a message — an admin page,
* a log line, a model's context, an audit row. On this vendor that body is not inert: the auth
* paths answer with an `authorization` whose `url` is a bearer capability and whose `context.token`
* is a live provider access token, and the adapter's `authorizations.status` already inverts this
* codebase's carry-the-vendor-error-as-`cause` convention for exactly that reason. This is the same
* refusal one layer out: the constructor keeps `status` and the body's `error.name` — the two
* MACHINE fields this deployment keys decisions on, in {@link isAuthorizationRequired} and in the
* route that decides whether a failed mint is definite — and drops the vendor's PROSE on the floor.
* Nothing that is not stored cannot be logged.
*
* `status` IS ALSO A TOP-LEVEL FIELD, because that is what an `APIError` presents and callers that
* read it off the thrown value go on working across this change.
*/
export class ArcadeFailureError extends Error {
readonly status: number | undefined;
readonly failure: ArcadeFailure;
constructor(sentence: string, failure: ArcadeFailure) {
super(sentence);
this.name = "ArcadeFailureError";
this.status = failure.status;
// THE ONE DOOR THE VENDOR'S PROSE DOES NOT COME THROUGH. Written here rather than at each
// construction site so that a later caller cannot pass it on by forgetting to.
this.failure = {
status: failure.status,
name: failure.name,
message: undefined,
};
}
}
/**
* KEYED ON THE BODY'S NAME, NEVER ON THE 403. A 403 is also what a revoked key, a disabled project
* and a rate limit look like; keyed on the status, this would tell somebody to authorize an action
* when the deployment's key is what is wrong.
*/
export function isAuthorizationRequired(failure: ArcadeFailure): boolean {
return failure.name === "tool_authorization_required";
}
/**
* The thrown value, READ AS A SHAPE rather than cast into one. `record` is a plain-object coercion
* that normalizes nothing and walks no `cause`, so a cast through it would let any object at all
* stand in for a normalized failure. Only a `name` string is required, since that is the one field
* `isAuthorizationRequired` keys on; the rest are read as-is or left undefined.
*
* {@link ArcadeFailureError} IS ASKED FIRST AND BY TYPE, because the shape reading cannot see it:
* an `Error`'s `name` is its CLASS name through the prototype chain, so a duck-typed read of one
* answers `"ArcadeFailureError"` for every refusal and the authorize prompt below would be
* unreachable — which is the same trap the adapter's own comment records for a raw `APIError`.
*/
function arcadeFailure(thrown: unknown): ArcadeFailure | null {
if (thrown instanceof ArcadeFailureError) return thrown.failure;
const raw = record(thrown);
if (!raw || typeof raw.name !== "string") return null;
return {
status: typeof raw.status === "number" ? raw.status : undefined,
name: raw.name,
message: typeof raw.message === "string" ? raw.message : undefined,
};
}
/**
* The cap every string this module puts in front of a model goes through, as `composio.ts`'s
* `cap()` does, with the same limit and the same marker.
*
* A tool result is read by a model AND copied into the audit row, so an unbounded one is somebody
* else's server deciding how much of our context window to spend and how large a durable record
* grows — and the text is attacker-influenceable, since it is whatever the mailbox, issue or
* document the action read happens to contain. Truncated visibly, never silently: `truncated` is
* the field that says it happened, and reporting `false` unconditionally made it a field that
* structurally could not.
*
* BOTH ANSWERS GO THROUGH IT. A refusal lands in a model's context exactly as a result does, and
* this file's refusals quote `toolName`, which is a `qualified_name` the vendor's listing supplied.
*/
function cap(text: string): { text: string; truncated: boolean } {
if (text.length <= MAX_RESULT_CHARS) return { text, truncated: false };
return {
text: `${cutAtCodeUnits(text, MAX_RESULT_CHARS)}\n\n[truncated]`,
truncated: true,
};
}
const failureResult = (text: string): McpCallResult => ({
...cap(text),
isError: true,
});
/**
* Call one Arcade action as the connection's actor.
*
* THE ACTION IN THE REFUSAL COMES FROM THE CALL SITE, never from the error: `APIError` in
* `@arcadeai/[email protected]` carries `status`, `headers` and `error` and nothing naming the tool.
*
* NO URL IS EVER IN THE SENTENCE, ON ANY PATH. The `authorization.url` is a bearer capability:
* whoever opens it attaches an account to the identity the flow was minted for. It is never
* returned to a model, logged, put in an error body or written to an audit row. The refusal names
* the Settings page, where the link is minted by an authenticated request whose actor is known.
*
* THE SUCCESS PATH IS COVERED BY THAT SAME PROMISE, and this is where it is easiest to break. A 200
* is not a safe envelope: `ExecuteToolResponse.output.authorization` is the SAME
* `AuthorizationResponse` the 403 carries, with the url and a `context.token` that is a LIVE OAUTH
* ACCESS TOKEN for the end user's account. `output.value` IS THE ONLY PART OF THE ENVELOPE THAT MAY
* CROSS INTO `text`; the envelope is never stringified whole, because `text` is returned to a model
* and copied into the audit row. An answer carrying an `authorization` at all is the refusal, not a
* result: it means the call was not run as an authorized actor.
*
* NOTHING THE VENDOR SAID IS REPEATED either: the ordinary failure is this deployment's sentence,
* and `output.error` is read only as a BOOLEAN — its `message`, `developer_message` and
* `stacktrace` are the vendor's words and stay out of `text`.
*/
export async function callTool(
connection: { url: string; actorId?: string },
toolName: string,
args: Record<string, unknown>,
): Promise<McpCallResult> {
if (!installed) {
return failureResult(
`Arcade is not configured for this deployment, so ${toolName} was not run.`,
);
}
if (!connection.actorId) {
return failureResult(
`${toolName} was not run: no account was named to run it as.`,
);
}
try {
const answer = await installed.execute({
tool_name: toolName,
input: args,
user_id: connection.actorId,
});
if (answer.output?.authorization) {
return failureResult(
`${toolName} has not been authorized on this account yet. Authorize it in Connections and ask again.`,
);
}
if (answer.success === false || answer.output?.error) {
return failureResult(`Arcade could not run ${toolName}.`);
}
const value = JSON.stringify(answer.output?.value ?? null, null, 2);
/*
* `JSON.stringify` ANSWERS `undefined` RATHER THAN THROWING for a value with no JSON form — a
* function, a symbol — and `output.value` is the vendor's field while the `unknown` saying
* anything may be there is ours. `??` does not catch it: a function is not nullish. Named here
* so the refusal is this deployment's sentence rather than a `text.length` TypeError raised
* inside {@link cap} and caught below as if Arcade had failed.
*/
if (value === undefined) {
return failureResult(
`${toolName} ran, but its answer has no JSON form, so there is nothing to show.`,
);
}
return { ...cap(value), isError: false };
} catch (thrown) {
const failure = arcadeFailure(thrown);
if (failure && isAuthorizationRequired(failure)) {
return failureResult(
`${toolName} has not been authorized on this account yet. Authorize it in Connections and ask again.`,
);
}
return failureResult(`Arcade could not run ${toolName}.`);
}
}