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.
import type { BrokerApp, BrokerRefusalError } from "../broker";
import { LISTING_LIMIT } from "../composio";
import {
type AccountRow,
appOf,
askVendor,
type CheckedAuthConfig,
everyRowOf,
type Listing,
pageOf,
readableConfigs,
type VendorAccountStatus,
type VendorToolkit,
} from "../composio-vendor";
import { type ComposioVendor, madeHere } from "./model";
/**
* What the Composio client's methods share: the vendor it calls, the clock, and the listings every
* group asks through. Made once per client by `buildComposioClient`.
*/
export function createClientContext(
vendor: ComposioVendor,
now: () => number = Date.now,
) {
/**
* This person's accounts for this app, in whichever states the ASKING question is about.
*
* ONE LISTING WITH THE STATUSES AS ITS ARGUMENT, rather than one listing both callers share.
* They shared one until it turned out that the shared answer was wrong for one of them: see
* {@link CONNECTED} and {@link REVOCABLE} for why "is this person connected" and "what is there
* to revoke" are different questions. What they do share is everything a drift between them
* would come from — the breadth of `accountType`, the limit, and the fact that both ask about one
* person and one app — so the difference between them is exactly the list of statuses and is
* visible at both call sites.
*
* AND SO ARE THE OTHER TWO THINGS THE TWO QUESTIONS DO NOT SHARE, for the same reason the
* statuses are. `configs` is which authorization configs the answer is about — every one of them
* for the three that only READ (the gate, `grantsFor` and `accountName`), and only this
* deployment's for the withdrawal, because the withdrawal ACTS on what it finds. `enough` is when the rows in hand already settle the question, which is true of
* a boolean the moment one row arrives and never true of a set of accounts to end. Both are
* written at the call sites below, beside the statuses, so that the whole of the difference
* between the two questions is one argument list a reader can compare.
*/
const accountsFor = async (
userId: string,
toolkit: string,
statuses: VendorAccountStatus[],
asked: {
configs?: string[];
enough?: (rows: AccountRow[]) => boolean;
} = {},
): Promise<AccountRow[]> => {
/*
* EVERY PAGE UNLESS THE CALLER SAYS OTHERWISE, READ HERE RATHER THAN AT EITHER CALLER, so that
* the two questions cannot drift on the one thing they do share. A truncated listing is the
* wrong answer to both of them for the same reason: `false` claims somebody has no account for
* an app when nobody looked at all of them, and a withdrawal that saw one page ends fewer
* grants than it reports. What a caller may say is that it has ENOUGH — see {@link everyRowOf}
* — which is not truncation: it is a question that has been answered.
*
* THE ROWS GO BACK AS ROWS, WHICH IS NARROWER THAN WHAT THIS USED TO HAND OVER. It read every
* id here, and the two callers do not want the same thing: `isConnected` is a COUNT — the id is
* nothing it reads — so taking ids on its behalf turned an account Composio described without
* one into a thrown refusal against a person who is, in fact, connected. Reading the ids is the
* withdrawal's business, and it is done there, where a row that cannot be named is something to
* report alongside the grants that were ended rather than something to stop them.
*/
const rows = await everyRowOf(
{
noun: `this person's ${toolkit} accounts`,
consequence:
"neither whether they are connected nor what there is to withdraw could be read",
},
(cursor) =>
askVendor(
{
outcome: `this person's ${toolkit} accounts were not read`,
app: toolkit,
},
() =>
vendor.connectedAccounts.list({
userIds: [userId],
toolkitSlugs: [toolkit],
/*
* COPIED, BECAUSE WHAT THE CALLERS PASS IN IS {@link CONNECTED} OR {@link REVOCABLE}
* ITSELF. Every other list in this body is built here — `[userId]`, `[toolkit]`, and
* `asked.configs`, which is a fresh `map` — and this one was the adapter's own
* module-level constant handed straight over the seam to the vendor's package. A
* recipient that sorts, de-duplicates or appends to the array it was given would not
* spoil one listing; it would rewrite the constant for the life of the process, after
* which `isConnected` — the gate `./access` asks before running somebody's action —
* and the withdrawal's own filter would both be asking a question nobody wrote down,
* in the next request rather than this one. It is the same reasoning {@link copyOf}
* applies to the catalogue rows, with no expiry to bound it.
*/
statuses: [...statuses],
accountType: "ALL",
// Spread for the reason the cursor is: an explicit `undefined` reaches the vendor's
// `parse` as a key, and "about every config" is said by not naming any.
...(asked.configs === undefined
? {}
: { authConfigIds: asked.configs }),
limit: LISTING_LIMIT,
...(cursor === undefined ? {} : { cursor }),
}),
),
asked.enough,
);
return rows;
};
/**
* Every auth config Composio holds for one app, ours and anybody else's alike, in one order.
*
* THE LISTING IS SCOPED TO THE PROJECT AND NOT TO THIS DEPLOYMENT, which is the correction. An
* auth config is scoped to the project the API key belongs to — so nothing here is hidden from
* this listing, and that was read as "everything it returns is ours". It is not: an operator with
* the same project open in Composio's dashboard can create configs for the same app by hand, for
* purposes this deployment knows nothing about. {@link madeHere} is the only thing that tells the
* two apart, and every caller below is about an object one of them must not touch.
*
* THE UNCLAIMED ROWS ARE RETURNED RATHER THAN DROPPED HERE, which is the part that moved. The
* filter used to live on the way out, so "no configs at all" and "configs, none of them ours"
* reached every caller as the same empty array — and telling those two apart is the whole of what
* {@link ComposioBroker.deleteAuthConfig} was missing, and then of what
* {@link ComposioBroker.revoke} was missing a wave later, on the same distinction, one function
* away. The `ours` filter is still offered, beside rather than instead of the rest, because a
* caller that can only see its own configs is a caller that cannot notice the other two states.
*
* SORTED SO THAT TWO CALLERS AGREE. The vendor's order is not documented, and the whole failure
* being fixed here is two calls resolving different rows; a total order on the id makes the
* choice this file makes a stable one, whoever asks and whenever.
*
* BY CODE UNIT RATHER THAN BY `localeCompare`, WHICH IS THE WHOLE POINT OF THE SORT RATHER THAN A
* QUIBBLE WITH IT. `localeCompare` called with no locale collates in the HOST's, and the hosts
* are not one host: "ac_B" comes before "ac_a" by code unit and after it under an English
* collation, and the two callers this order exists to keep in step — a person pressing Connect
* and an administrator pressing Remove — need not be answered by the same process, the same
* container or the same build of ICU. An order that two machines can disagree about is not an
* order two callers agree on. `<` is the same total order everywhere, which is the only property
* asked of it here.
*
* THREE PARTS RATHER THAN A LIST, AND THAT IS A GUARD AGAINST THIS FILE'S OWN HISTORY. Each of
* the four callers below has to answer three different questions about one listing — what is
* ours, what is standing that is not, and what could not be read at all — and every defect this
* function has been corrected for was one caller answering one of them while its neighbour, one
* function away, answered it differently or not at all. A shape that hands over only `ours`
* lets a caller not notice the other two; this one cannot be destructured without saying so.
*/
const configsFor = async (
toolkit: string,
): Promise<{
/** Every readable row, ours and anybody else's alike, deduplicated and in one order. */
held: CheckedAuthConfig[];
/** The subset of `held` carrying {@link CONFIG_SUFFIX}, which is what this deployment claims. */
ours: CheckedAuthConfig[];
/** One refusal per row that could be sorted into neither, which is never nothing. */
unreadable: BrokerRefusalError[];
}> => {
/*
* EVERY PAGE, BECAUSE A CONFIG ON THE SECOND ONE IS STILL OURS. Read one page and the two
* callers below are wrong in the two opposite directions {@link madeHere} describes:
* `ensureAuthConfig` finds none and creates the second config it exists to prevent, and
* `deleteAuthConfig` leaves one standing, reports a clean removal, and lets `removeServer`
* delete the app's row over the top of a live grant.
*/
const rows = await everyRowOf(
{
noun: `this deployment's authorization configs for ${toolkit}`,
consequence:
"whether one exists is not something this deployment can tell",
},
(cursor) =>
askVendor(
{
outcome: `this deployment's authorization configs for ${toolkit} were not read`,
app: toolkit,
},
() =>
vendor.authConfigs.list({
toolkit,
limit: LISTING_LIMIT,
showDisabled: true,
...(cursor === undefined ? {} : { cursor }),
}),
),
);
/*
* CHECKED BEFORE THE FILTER AND NOT AFTER IT, which is the order the whole guard turns on. The
* filter's question IS the name, so a row checked only once it had been kept would be a row
* sorted by a field nobody had read — see {@link madeHere} for what each of the two guesses
* costs. Every row therefore passes {@link readableConfigs} first, including the ones that turn
* out to belong to an operator's own dashboard work.
*/
const { configs, unreadable } = readableConfigs(rows, toolkit);
const held = configs.sort((one, other) =>
one.id < other.id ? -1 : one.id > other.id ? 1 : 0,
);
return { held, ours: held.filter(madeHere), unreadable };
};
/**
* Ask for every one of them and answer with what refused, rather than stopping at the first.
*
* A THROW MID-LOOP ABANDONS GRANTS THAT ARE STILL LIVE. Both callers below are deleting a set of
* things that each independently hold somebody's access, and an exception out of the second of
* five leaves three untouched and unmentioned — while the caller is told only about the one that
* failed, so nothing in the answer says the loop did not finish. Attempting all of them makes the
* failure a statement about a set: this many were asked for and this many refused.
*
* SERIALLY RATHER THAN TOGETHER, for the same reason every other call here goes out one at a
* time: the vendor rate-limits, and a person with several accounts is not a reason to open
* several connections. The order is the listing's, which is sorted.
*
* EVERY REFUSAL IS ANSWERED AND NOT ONLY THE FIRST. What the callers do with this list is throw a
* COUNT — "two of three were withdrawn and the rest refused" — because a count is what a reader
* can act on, which makes the reasons the only place the detail lives. Returning them all is what
* lets {@link everyRefusal} put all of them on the failure the caller raises; the previous version
* collected them and both callers then read `refused[0]`, so the second and third reason existed
* for the length of one expression and were then dropped.
*
* EVERY FAILURE IS A REFUSAL HERE, AND THE CLASSIFICATION THAT USED TO SIT IN THIS LOOP HAS MOVED
* ONE LAYER DOWN. There was an `isOurFault` test in the catch that re-threw a `TypeError`, a
* `ReferenceError` or a `RangeError` rather than counting it, on the premise that those are what
* a program's own mistake looks like and are never "a thing Composio can reply". The premise is
* false — see the `TypeError` row in {@link vendorRefusal} for the five vendor shapes that raise
* exactly that from inside `@composio/core`'s own transformers — so its effect was inverted: a
* vendor fault escaped the loop as a bug of ours, abandoning every account after it unasked, and
* the person was handed a crash instead of a sentence.
*
* IT MOVED RATHER THAN BEING RETUNED because this loop cannot make the distinction and
* {@link askVendor} can. Every `ask` below is one `await vendor.*` wrapped by that function, so
* whether a fault came from inside the vendor's code is a fact about the call stack there, where
* here it could only ever have been guessed at from an error class.
*/
const askForEach = async <T>(
items: T[],
ask: (item: T) => Promise<unknown>,
): Promise<unknown[]> => {
const refused: unknown[] = [];
for (const item of items) {
try {
await ask(item);
} catch (error) {
refused.push(error);
}
}
return refused;
};
/**
* The catalogue as the vendor answers it, EVERY PAGE OF IT, mapped to the rows a person picks from.
*
* IT USED TO BE ONE PAGE AND A REFUSAL, AND THAT REFUSAL IS THE BUG THIS FUNCTION WAS FIXED FOR.
* It asked for {@link LISTING_LIMIT} rows, met exactly that many, and threw — because a full page
* and a truncated one are the same array and it believed no second request could tell them apart.
* Composio publishes more than {@link LISTING_LIMIT} toolkits, so the condition was true on every
* call and the app picker showed an operator nothing at all, with a sentence explaining why a
* partial directory would be worse. The reasoning was right and the premise was false: the raw
* client has a cursor for this listing and always did. See {@link ComposioVendor} and
* {@link everyRowOf}.
*
* SORTED BY USAGE, AND NO SEARCH TERM — see {@link ComposioVendor}, where both are argued now
* that neither is holding a finite page together.
*
* THROWN FROM INSIDE THE FETCH, WHICH IS WHAT KEEPS A FAILURE OUT OF THE CACHE. Every refusal
* below — a cursor that cannot be followed, a page that is not a page, a row that cannot be read
* — rejects the promise `listApps` holds, and `listApps` drops an entry whose request rejected.
* A fragment committed here would be a fragment served for ten minutes to BOTH callers: an
* administrator searching for an app past the cut is told nothing matched, and the enable route,
* which checks a slug against this same directory, tells them a real app is not one Composio
* lists.
*/
const fetchDirectory = async (): Promise<BrokerApp[]> => {
const listing: Listing = {
noun: "Composio's app catalogue",
consequence: "the directory was not shown",
};
const toolkits = await everyRowOf<VendorToolkit>(listing, (cursor) =>
pageOf(listing, () =>
askVendor(
{ outcome: "the app catalogue was not read", app: null },
() =>
vendor.toolkits.list({
limit: LISTING_LIMIT,
sort_by: "usage",
// Spread rather than an explicit undefined, for the reason `everyRowOf` gives: a
// `cursor: undefined` is a key on the wire, and "the first page" is said by omission.
...(cursor === undefined ? {} : { cursor }),
}),
),
),
);
/*
* Each absence becomes the value that reads honestly on an administrator's screen, and each
* PRESENT field that is not what it is declared to be becomes a refusal — see {@link appOf},
* where both halves of that and every sentence live. An empty description shows as no
* description; a null logo is the field's documented way of saying the vendor published none,
* which renders as a gap rather than as a broken image.
*
* The categories are the DISPLAY names rather than the slugs, because this list is read by a
* person choosing an app and "Productivity" is what they are choosing by.
*
* A MISSING COUNT BECOMES ZERO, WHICH IS THE ONE IMPERFECT ANSWER HERE. `actionCount` is a
* number and the shape offers no way to say "not published", so a toolkit that publishes no
* count reads as an app with no actions. It is the conservative direction — it understates
* the size of a change rather than overstating it — and Composio publishes a count for every
* toolkit measured, so this is a guard against the vendor rather than a routine case. A count
* that arrives as something other than a number is the different case and is refused.
*/
return toolkits.map(appOf);
};
return {
vendor,
now,
accountsFor,
configsFor,
askForEach,
fetchDirectory,
};
}
export type ClientContext = ReturnType<typeof createClientContext>;