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.
/**
* Team Bots: one Bot, published by its owner, used by teammates in chats of their own.
*
* WHO SEES IT. `teamBotAccess` is the one rule, added to the same SQL gate that already admits public
* Bots and a person's own (`profile-store.ts` `accessFilter`, `runtime-agents.ts`), so the roster, the
* runtime, handoffs and groups all see a Team Bot exactly where its publication says. No publication
* row, no access: unpublishing is one delete.
*
* PRIVATE CHATS. A teammate's conversation is an ordinary channel of their own, and channels are
* membership-scoped, so the owner cannot read it and it cannot read theirs. Nothing here changes that.
*
* WHOSE ACCOUNTS. A Team Bot reaches a connected app as its OWNER when the owner has connected it,
* the same for everyone — for an app an ADMINISTRATOR gave it. An app the owner gave it themselves
* (`plugin_grants.granted_as = owner`) always runs on the asking teammate's own account. A teammate's OWN account on a server the owner has not connected is used
* only with their consent: Allow once, Always allow for this Bot, or Skip. Everything else about the
* call (grant, policy, approvals, audit) is still decided as the teammate who is asking.
*/
import { and, eq, inArray, isNull, or, sql } from "drizzle-orm";
import { capabilityRefusal } from "../admin/capabilities";
import { enterpriseControls } from "../admin/controls";
import type { AgentActor } from "../agents/profile-types";
import type { Database } from "../db/client";
import { agents, users } from "../db/schema/core";
import { agentProfiles } from "../db/schema/coworker";
import { pluginGrants } from "../db/schema/plugins";
import {
teamBotAssignments,
teamBotAudience,
teamBotConsentDefaults,
teamBotConsents,
teamBotPublications,
} from "../db/schema/team-bots";
import { PluginRefusedError } from "../plugins/store";
import {
assignedCondition,
describedForTeam,
PLACEHOLDER_BOT_NAMES,
teamBotAccess,
} from "./access";
export { teamBotAccess } from "./access";
/** Prefix a consent refusal carries, so a chat can draw the card instead of the sentence. */
export const TEAM_BOT_CONSENT_MARKER = "[team-bot-consent]";
export class TeamBotRefusedError extends Error {
constructor(message: string) {
super(message);
this.name = "TeamBotRefusedError";
}
}
/** The person may not publish Team Bots at all: an administrator turned the switch off. */
export class TeamBotForbiddenError extends Error {
constructor(message: string) {
super(message);
this.name = "TeamBotForbiddenError";
}
}
export class TeamBotNotFoundError extends Error {
constructor() {
super("That Team Bot was not found.");
this.name = "TeamBotNotFoundError";
}
}
export type TeamBotSummary = {
id: string;
name: string;
title: string;
roleDescription: string;
ownerUserId: string | null;
audience: "team" | "people";
publishedAt: string;
assigned: boolean;
};
export type TeamBotConsentDecision =
| "allow_once"
| "allow_always"
| "allow_all_team_bots"
| "skip";
/** One consent card a run raised: which Team Bot, which of the person's own accounts, and why. */
export type TeamBotConsentAsk = {
botId: string;
serverId: string;
message: string;
};
/** Which servers a person has connected an account on, as the plugin store records it. */
export type ConnectionReader = (userId: string) => Promise<Set<string>>;
export function createTeamBots(options: {
database: Database;
/** Every server this person has their own account connected on (OAuth or brokered). */
connectedServers: ConnectionReader;
}) {
const { database, connectedServers } = options;
/**
* Cards raised while a server-run turn was listening for them, keyed by person and Bot. A browser
* chat draws the card from the tool result itself; a group turn has no browser, so it collects
* them here and puts the card in the shared transcript.
*/
const listening = new Map<string, TeamBotConsentAsk[]>();
async function publication(botId: string) {
const [row] = await database
.select({
agentId: teamBotPublications.agentId,
audience: teamBotPublications.audience,
ownerUserId: agentProfiles.ownerUserId,
})
.from(teamBotPublications)
.innerJoin(
agentProfiles,
eq(agentProfiles.agentId, teamBotPublications.agentId),
)
.where(
and(
eq(teamBotPublications.agentId, botId),
isNull(agentProfiles.deletedAt),
),
)
.limit(1);
return row ?? null;
}
/** The Bot as its owner, for owner-only acts; administrators may unpublish and assign. */
async function owned(actor: AgentActor, botId: string, allowAdmin: boolean) {
const [row] = await database
.select({
id: agents.id,
name: agents.name,
roleDescription: agentProfiles.roleDescription,
ownerUserId: agentProfiles.ownerUserId,
})
.from(agents)
.innerJoin(agentProfiles, eq(agentProfiles.agentId, agents.id))
.where(and(eq(agents.id, botId), isNull(agentProfiles.deletedAt)))
.limit(1);
if (!row) throw new TeamBotNotFoundError();
if (row.ownerUserId !== actor.id && !(allowAdmin && actor.role === "admin"))
throw new TeamBotNotFoundError();
return row;
}
return {
teamBotAccess,
/**
* Whose account a Team Bot's call to `ref` goes out on, for the person asking.
*
* The asker, for anything that is not a Team Bot or is theirs, and for a server nobody has a
* personal account on (a shared credential reaches the same place whoever asks). The owner, where
* the owner connected it. The asker's own account only with a standing or one-time consent;
* without one the call is refused with the card's marker, and nothing is sent.
*
* NEVER THE OWNER'S FOR A GRANT THE OWNER MADE. Where the owner gave the Bot this action of one of
* their own apps (`granted_as = owner`), the owner's connection is not asked about: the call goes
* on as though the owner had none, which is the asker's own account — with their consent, or
* refused to connect. An owner giving their Bot their Gmail decided about their own mailbox for
* their own use; publishing the Bot afterwards must not turn that into every teammate's access to
* it. Only an administrator's grant can put a Team Bot on its owner's account.
*/
credentialActorFor(actorId: string, botId: string) {
return async (ref: string): Promise<string> => {
const published = await publication(botId);
const owner = published?.ownerUserId;
if (!owner || owner === actorId) return actorId;
const serverId = ref.split("/")[0] ?? "";
const [grant] = await database
.select({ grantedAs: pluginGrants.grantedAs })
.from(pluginGrants)
.where(
and(
eq(pluginGrants.kind, "mcp"),
eq(pluginGrants.ref, ref),
eq(pluginGrants.agentId, botId),
),
)
.limit(1);
if (
grant?.grantedAs !== "owner" &&
(await connectedServers(owner)).has(serverId)
)
return owner;
if (!(await connectedServers(actorId)).has(serverId)) return actorId;
const [consent] = await database
.select({ decision: teamBotConsents.decision })
.from(teamBotConsents)
.where(
and(
eq(teamBotConsents.userId, actorId),
eq(teamBotConsents.agentId, botId),
eq(teamBotConsents.serverId, serverId),
),
)
.limit(1);
if (consent?.decision === "always") return actorId;
const [everyBot] = await database
.select({ serverId: teamBotConsentDefaults.serverId })
.from(teamBotConsentDefaults)
.where(
and(
eq(teamBotConsentDefaults.userId, actorId),
eq(teamBotConsentDefaults.serverId, serverId),
),
)
.limit(1);
if (everyBot) return actorId;
if (consent?.decision === "once") {
// Spent by exactly one call: whichever call deletes it is the one that may go.
const spent = await database
.delete(teamBotConsents)
.where(
and(
eq(teamBotConsents.userId, actorId),
eq(teamBotConsents.agentId, botId),
eq(teamBotConsents.serverId, serverId),
eq(teamBotConsents.decision, "once"),
),
)
.returning({ serverId: teamBotConsents.serverId });
if (spent.length) return actorId;
}
const message = `This Team Bot wants to use your own ${serverId} account. Choose Allow once, Always allow, or Skip, then ask again.`;
listening
.get(`${actorId}\n${botId}`)
?.push({ botId, serverId, message });
throw new PluginRefusedError(
`${TEAM_BOT_CONSENT_MARKER}${JSON.stringify({ botId, serverId })} ${message}`,
null,
);
};
},
/**
* Listen for consent cards this person's turns with this Bot raise, until the returned function
* is called; it returns them once each.
*/
listenForConsent(
actorId: string,
botId: string,
): () => TeamBotConsentAsk[] {
const key = `${actorId}\n${botId}`;
const asks: TeamBotConsentAsk[] = [];
listening.set(key, asks);
return () => {
if (listening.get(key) === asks) listening.delete(key);
return asks.filter(
(ask, index) =>
asks.findIndex((other) => other.serverId === ask.serverId) ===
index,
);
};
},
/** Record a teammate's answer to a consent card. Skip clears any earlier answer. */
async consent(
actor: AgentActor,
botId: string,
serverId: string,
decision: TeamBotConsentDecision,
) {
const scope = and(
eq(teamBotConsents.userId, actor.id),
eq(teamBotConsents.agentId, botId),
eq(teamBotConsents.serverId, serverId),
);
if (decision === "skip") {
await database.delete(teamBotConsents).where(scope);
return;
}
if (!(await publication(botId))) throw new TeamBotNotFoundError();
if (decision === "allow_all_team_bots") {
await database
.insert(teamBotConsentDefaults)
.values({ userId: actor.id, serverId })
.onConflictDoNothing();
return;
}
const value = decision === "allow_always" ? "always" : "once";
await database
.insert(teamBotConsents)
.values({ userId: actor.id, agentId: botId, serverId, decision: value })
.onConflictDoUpdate({
target: [
teamBotConsents.userId,
teamBotConsents.agentId,
teamBotConsents.serverId,
],
set: { decision: value, updatedAt: new Date() },
});
},
/** Settings: forget every consent this person has given any Team Bot. */
async clearConsents(actor: AgentActor) {
await database
.delete(teamBotConsents)
.where(eq(teamBotConsents.userId, actor.id));
await database
.delete(teamBotConsentDefaults)
.where(eq(teamBotConsentDefaults.userId, actor.id));
},
async publish(
actor: AgentActor,
botId: string,
input: {
audience: "team" | "people";
emails: string[];
groups: string[];
},
) {
// The "Team Bots" switch, here rather than only at the HTTP gate, so every caller meets it.
// Fails closed when the controls cannot be read.
const controls = enterpriseControls();
if (controls) {
const allowed = await controls
.capabilityFor(actor.id, "teamBots")
.catch(() => false);
if (!allowed)
throw new TeamBotForbiddenError(capabilityRefusal("teamBots"));
}
const bot = await owned(actor, botId, false);
// A teammate cannot tell an undescribed Bot from any other, so it is not published.
if (
!bot.roleDescription.trim() ||
(PLACEHOLDER_BOT_NAMES as readonly string[]).includes(
bot.name.trim().toLowerCase(),
)
)
throw new TeamBotRefusedError(
"Give this Bot a name and a description before publishing it to your team.",
);
const emails = [
...new Set(input.emails.map((email) => email.trim().toLowerCase())),
].filter(Boolean);
const people = emails.length
? await database
.select({ id: users.id, email: users.email })
.from(users)
.where(inArray(sql`lower(${users.email})`, emails))
: [];
const missing = emails.filter(
(email) => !people.some((row) => row.email.toLowerCase() === email),
);
if (missing.length)
throw new TeamBotRefusedError(
`Nobody has signed in here as ${missing.join(", ")}.`,
);
const groups = [
...new Set(input.groups.map((group) => group.trim())),
].filter(Boolean);
if (input.audience === "people" && !people.length && !groups.length)
throw new TeamBotRefusedError(
"Name at least one person or group, or publish to the whole team.",
);
await database.transaction(async (tx) => {
await tx
.insert(teamBotPublications)
.values({
agentId: botId,
publishedBy: actor.id,
audience: input.audience,
})
.onConflictDoUpdate({
target: teamBotPublications.agentId,
set: { audience: input.audience, publishedBy: actor.id },
});
await tx
.delete(teamBotAudience)
.where(eq(teamBotAudience.agentId, botId));
const rows = [
...people.map((person) => ({
agentId: botId,
kind: "user" as const,
value: person.id,
})),
...groups.map((group) => ({
agentId: botId,
kind: "group" as const,
value: group,
})),
];
if (input.audience === "people" && rows.length)
await tx.insert(teamBotAudience).values(rows);
});
},
/** Teammates lose access until it is published again. Assignments wait, inert. */
async unpublish(actor: AgentActor, botId: string) {
await owned(actor, botId, true);
await database
.delete(teamBotPublications)
.where(eq(teamBotPublications.agentId, botId));
},
async assign(actor: AgentActor, botId: string, groupName: string) {
if (actor.role !== "admin")
throw new TeamBotRefusedError("Only an admin can assign Team Bots.");
if (!(await publication(botId)))
throw new TeamBotRefusedError("Publish this Bot before assigning it.");
const group = groupName.trim();
if (!group) throw new TeamBotRefusedError("Name a group, or * for all.");
await database
.insert(teamBotAssignments)
.values({ agentId: botId, groupName: group, assignedBy: actor.id })
.onConflictDoNothing();
},
async unassign(actor: AgentActor, botId: string, groupName: string) {
if (actor.role !== "admin")
throw new TeamBotRefusedError("Only an admin can assign Team Bots.");
await database
.delete(teamBotAssignments)
.where(
and(
eq(teamBotAssignments.agentId, botId),
eq(teamBotAssignments.groupName, groupName),
),
);
},
/** Whether this is a Team Bot somebody else published, where this person's accounts need their consent. */
async publishedByAnother(actorId: string, botId: string): Promise<boolean> {
const owner = (await publication(botId))?.ownerUserId;
return Boolean(owner) && owner !== actorId;
},
/** Whether this Bot is in this person's sidebar by assignment, which they cannot hide. */
async isAssignedTo(actorId: string, botId: string): Promise<boolean> {
const [row] = await database
.select({ agentId: teamBotPublications.agentId })
.from(teamBotPublications)
.where(
and(
eq(teamBotPublications.agentId, botId),
assignedCondition(actorId),
),
)
.limit(1);
return Boolean(row);
},
/** The Team Bots this person may use, their own publications, and each one's settings. */
async list(actor: AgentActor) {
const rows = await database
.select({
id: agents.id,
name: agents.name,
title: agentProfiles.title,
roleDescription: agentProfiles.roleDescription,
ownerUserId: agentProfiles.ownerUserId,
audience: teamBotPublications.audience,
publishedAt: teamBotPublications.publishedAt,
assigned: sql<boolean>`${assignedCondition(actor.id)}`,
described: sql<boolean>`${describedForTeam}`,
})
.from(teamBotPublications)
.innerJoin(agents, eq(agents.id, teamBotPublications.agentId))
.innerJoin(agentProfiles, eq(agentProfiles.agentId, agents.id))
.where(
and(
isNull(agentProfiles.deletedAt),
actor.role === "admin"
? undefined
: or(
eq(agentProfiles.ownerUserId, actor.id),
teamBotAccess(actor.id, teamBotPublications.agentId),
),
),
)
.orderBy(agents.name);
const ids = rows.map((row) => row.id);
const [audience, assignments] = ids.length
? await Promise.all([
database
.select({
agentId: teamBotAudience.agentId,
kind: teamBotAudience.kind,
value: teamBotAudience.value,
email: users.email,
})
.from(teamBotAudience)
.leftJoin(
users,
and(
eq(teamBotAudience.kind, "user"),
eq(users.id, teamBotAudience.value),
),
)
.where(inArray(teamBotAudience.agentId, ids)),
database
.select()
.from(teamBotAssignments)
.where(inArray(teamBotAssignments.agentId, ids)),
])
: [[], []];
return rows.map((row) => {
const manages = row.ownerUserId === actor.id || actor.role === "admin";
return {
id: row.id,
name: row.name,
title: row.title,
roleDescription: row.roleDescription,
mine: row.ownerUserId === actor.id,
audience: row.audience,
publishedAt: row.publishedAt.toISOString(),
assigned: Boolean(row.assigned),
/** False while its name or description would leave teammates unable to tell it apart. */
visibleToTeam: Boolean(row.described),
// Who it reaches is the owner's and administrators' business, not every teammate's.
...(manages
? {
people: audience
.filter((a) => a.agentId === row.id && a.kind === "user")
.map((a) => a.email ?? a.value),
groups: audience
.filter((a) => a.agentId === row.id && a.kind === "group")
.map((a) => a.value),
assignments: assignments
.filter((a) => a.agentId === row.id)
.map((a) => a.groupName),
}
: {}),
};
});
},
/** The owner's own Bots that could be published, for the publish list. */
async publishable(actor: AgentActor) {
return database
.select({
id: agents.id,
name: agents.name,
title: agentProfiles.title,
})
.from(agents)
.innerJoin(agentProfiles, eq(agentProfiles.agentId, agents.id))
.leftJoin(
teamBotPublications,
eq(teamBotPublications.agentId, agents.id),
)
.where(
and(
eq(agentProfiles.ownerUserId, actor.id),
isNull(agentProfiles.deletedAt),
isNull(teamBotPublications.agentId),
),
)
.orderBy(agents.name);
},
};
}
export type TeamBots = ReturnType<typeof createTeamBots>;