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 { canAccessAgent } from "../agents/profile-policy";
import type { AgentProfileStore } from "../agents/profile-store";
import type { AgentActor, AgentProfile } from "../agents/profile-types";
import type { AuditStore } from "../audit";
import { recordAuditEvent } from "../audit";
import type {
IntentRouter,
RoutingCandidate,
RoutingUndecided,
} from "./classify";
const PICKED_HARNESS_AGENT_ID = "picked-harness";
export function defaultRoutingProfile(
roster: readonly AgentProfile[],
): AgentProfile | undefined {
return (
roster.find((agent) => agent.id === PICKED_HARNESS_AGENT_ID) ??
roster.find((agent) => agent.visibility === "public") ??
roster[0]
);
}
export const MAX_ROUTING_TEXT_LENGTH = 10000;
export class CoworkerRoutingInputError extends Error {
constructor(
message = `A message of at most ${MAX_ROUTING_TEXT_LENGTH} characters is required.`,
) {
super(message);
this.name = "CoworkerRoutingInputError";
}
}
const DEV_ACTOR_EMAIL = "[email protected]";
const WORD_CHARACTER = /[\p{L}\p{N}\p{M}_]/u;
export type CoworkerRouteResult =
| {
kind: "selected";
agentId: string;
name: string;
reason: string;
fallback: boolean;
viaMention: boolean;
viaNameMatch?: true;
}
| { kind: "ambiguous"; names: string[] }
| { kind: "none" };
type RoutingActor = AgentActor & { email?: string };
export type CoworkerRoutingInput = {
actor: RoutingActor;
text: string;
/** An explicit picker selection from a surface such as the web composer. */
agentId?: string | null;
};
export type CoworkerRouteDetail = {
result: CoworkerRouteResult;
/** Kept for surfaces that have historically returned the model's fallback cause. */
undecided: RoutingUndecided | null;
};
export type CoworkerRoutingService = {
route(input: CoworkerRoutingInput): Promise<CoworkerRouteResult>;
};
export type HttpCoworkerRoutingService = CoworkerRoutingService & {
routeDetailed(input: CoworkerRoutingInput): Promise<CoworkerRouteDetail>;
};
export type CreateCoworkerRoutingServiceOptions = {
store: AgentProfileStore;
router: IntentRouter;
auditStore?: AuditStore;
reachableSystems?: (agentId: string) => Promise<readonly string[]>;
};
/** Normalize people-facing names before matching, without making matching fuzzy. */
export function normalizeCoworkerName(value: string): string {
return value.normalize("NFKC").toLowerCase().trim().replace(/\s+/gu, " ");
}
function hasTokenBoundaries(text: string, start: number, end: number): boolean {
const before = [...text.slice(0, start)].at(-1);
const after = [...text.slice(end)][0];
return !before || !WORD_CHARACTER.test(before)
? !after || !WORD_CHARACTER.test(after)
: false;
}
type AliasOccurrence = {
start: number;
end: number;
profiles: ReadonlyMap<string, AgentProfile>;
};
function occurrencesOf(
text: string,
alias: string,
profiles: ReadonlyMap<string, AgentProfile>,
): AliasOccurrence[] {
const occurrences: AliasOccurrence[] = [];
let start = text.indexOf(alias);
while (start >= 0) {
const end = start + alias.length;
if (hasTokenBoundaries(text, start, end)) {
occurrences.push({ start, end, profiles });
}
start = text.indexOf(alias, start + alias.length);
}
return occurrences;
}
function actorId(actor: RoutingActor): string | undefined {
return actor.id && actor.email !== DEV_ACTOR_EMAIL ? actor.id : undefined;
}
function displayName(name: string): string {
return name.normalize("NFKC").trim().replace(/\s+/gu, " ");
}
function utf8Hex(value: string): string {
return [...new TextEncoder().encode(value)]
.map((byte) => byte.toString(16).padStart(2, "0"))
.join("");
}
function codePointCompare(left: string, right: string): number {
const leftPoints = [...left];
const rightPoints = [...right];
for (let index = 0; index < leftPoints.length; index += 1) {
const leftPoint = leftPoints[index]?.codePointAt(0);
const rightPoint = rightPoints[index]?.codePointAt(0);
if (leftPoint === undefined) return -1;
if (rightPoint === undefined) return 1;
if (leftPoint !== rightPoint) return leftPoint - rightPoint;
}
return leftPoints.length - rightPoints.length;
}
type AliasIndex = {
aliases: Map<string, Map<string, AgentProfile>>;
labels: Map<string, string>;
};
function addAlias(
aliases: AliasIndex["aliases"],
alias: string,
profile: AgentProfile,
): void {
if (!alias) return;
const profiles = aliases.get(alias) ?? new Map<string, AgentProfile>();
profiles.set(profile.id, profile);
aliases.set(alias, profiles);
}
function buildAliasIndex(roster: readonly AgentProfile[]): AliasIndex {
const aliases = new Map<string, Map<string, AgentProfile>>();
const labels = new Map<string, string>();
for (const profile of roster) {
// Full names only. A trailing word of a name ("review", "notes", "analyst") is an ordinary word
// in a request, and matching it sent "review this contract" to whichever coworker ends in Review.
addAlias(aliases, normalizeCoworkerName(profile.name), profile);
}
// Keep encoded id aliases even when a later roster collision changes the displayed label.
// A previously offered label must become ambiguous rather than silently address another Bot.
for (const profile of roster) {
addAlias(
aliases,
normalizeCoworkerName(
`${displayName(profile.name)} (id ${utf8Hex(profile.id)})`,
),
profile,
);
}
// A generated numeric discriminator is also part of an encoded id label. If a natural alias
// reuses an old discriminator, merge the original id at the same span so containment cannot
// discard it and quietly route to the newly named coworker.
for (const profile of roster) {
const base = normalizeCoworkerName(
`${displayName(profile.name)} (id ${utf8Hex(profile.id)})`,
);
for (const alias of aliases.keys()) {
if (
alias.startsWith(base) &&
/^ \((?:[2-9]|[1-9]\d+)\)$/u.test(alias.slice(base.length))
) {
addAlias(aliases, alias, profile);
}
}
}
const reservedLabels = new Set(aliases.keys());
for (const profile of roster) {
const normalized = normalizeCoworkerName(profile.name);
const duplicates = aliases.get(normalized)?.size ?? 0;
let label = profile.name;
if (duplicates > 1) {
const base = `${displayName(profile.name)} (id ${utf8Hex(profile.id)})`;
label = base;
let discriminator = 2;
while (
reservedLabels.has(normalizeCoworkerName(label)) &&
!(
label === base && aliases.get(normalizeCoworkerName(base))?.size === 1
)
) {
label = `${base} (${discriminator++})`;
}
reservedLabels.add(normalizeCoworkerName(label));
}
labels.set(profile.id, label);
addAlias(aliases, normalized, profile);
if (duplicates > 1) {
addAlias(aliases, normalizeCoworkerName(label), profile);
}
}
return { aliases, labels };
}
type ExplicitOccurrence = {
start: number;
end: number;
profiles: Map<string, AgentProfile>;
};
/**
* Discard only aliases that a strictly longer explicit occurrence fully contains.
*
* Intervals are ordered by start, then widest first. A running maximum end therefore proves that a
* prior interval starts no later and reaches at least as far as the current one, which is exactly
* containment. Partial overlaps extend the maximum only for later contained intervals; they never
* suppress each other.
*/
function withoutContainedOccurrences(
occurrences: readonly AliasOccurrence[],
): ExplicitOccurrence[] {
const bySpan = new Map<string, ExplicitOccurrence>();
for (const occurrence of occurrences) {
const key = `${occurrence.start}:${occurrence.end}`;
const merged =
bySpan.get(key) ??
({
start: occurrence.start,
end: occurrence.end,
profiles: new Map<string, AgentProfile>(),
} satisfies ExplicitOccurrence);
for (const profile of occurrence.profiles.values()) {
merged.profiles.set(profile.id, profile);
}
bySpan.set(key, merged);
}
const sorted = [...bySpan.values()].sort(
(left, right) => left.start - right.start || right.end - left.end,
);
let maximumEnd = -1;
return sorted.filter((occurrence) => {
const contained = maximumEnd >= occurrence.end;
maximumEnd = Math.max(maximumEnd, occurrence.end);
return !contained;
});
}
function labelsFor(
profiles: Iterable<AgentProfile>,
labels: ReadonlyMap<string, string>,
): string[] {
return [...profiles]
.map((profile) => labels.get(profile.id) ?? profile.name)
.sort(codePointCompare);
}
/** "hey", "hi" or "hello" opening a message, then an optional `@`, before the name addressed. */
const OPENING_ADDRESS = /^(?:(?:hey|hi|hello)(?![\p{L}\p{N}\p{M}_])[\s,]*)?@?/u;
/** "ask" as a whole word, then an optional `@`, before the name addressed. */
const ASK_ADDRESS = /(?<![\p{L}\p{N}\p{M}_])ask\s+@?/gu;
/** A list of names addressed together: "ask Risk Analyst and Knowledge", "@Ann, @Bob". */
const LIST_CONTINUATION = /^(?:\s*,\s*|\s*&\s*|\s+(?:and|or)\s+)@?/u;
/**
* Keep only the names a message ADDRESSES, so a coworker is chosen without the model only when the
* person spoke to it: the message opens with its full name ("Risk Analyst, please…", after an
* optional greeting), names it with `@`, or asks it ("ask Risk Analyst to…"). A name mentioned in
* passing ("don't send this to Risk Analyst") is left to the model. Names listed straight after an
* addressed one are addressed too, so "ask Risk Analyst and Knowledge" is still a choice to make.
*/
function addressedOccurrences(
text: string,
occurrences: readonly AliasOccurrence[],
): AliasOccurrence[] {
const starts = new Set<number>();
starts.add(OPENING_ADDRESS.exec(text)?.[0].length ?? 0);
for (let at = text.indexOf("@"); at >= 0; at = text.indexOf("@", at + 1)) {
starts.add(at + 1);
}
for (const match of text.matchAll(ASK_ADDRESS)) {
starts.add((match.index ?? 0) + match[0].length);
}
const addressed: AliasOccurrence[] = [];
const sorted = [...occurrences].sort(
(left, right) => left.start - right.start || right.end - left.end,
);
for (const occurrence of sorted) {
// A name that starts inside an addressed one and runs past it ("ask Ann Marie Curie" with Ann
// Marie and Marie Curie) is addressed too, so overlapping names stay a choice, not a guess.
const overlapsAddressed = addressed.some(
(prior) =>
occurrence.start > prior.start &&
occurrence.start < prior.end &&
occurrence.end > prior.end,
);
if (!starts.has(occurrence.start) && !overlapsAddressed) continue;
addressed.push(occurrence);
const continuation = LIST_CONTINUATION.exec(text.slice(occurrence.end));
if (continuation) starts.add(occurrence.end + continuation[0].length);
}
return addressed;
}
function explicitNameRoute(
text: string,
roster: readonly AgentProfile[],
): CoworkerRouteResult | null {
const normalizedText = normalizeCoworkerName(text);
const { aliases, labels } = buildAliasIndex(roster);
const occurrences = [...aliases.entries()].flatMap(([alias, profiles]) =>
occurrencesOf(normalizedText, alias, profiles),
);
const explicitOccurrences = withoutContainedOccurrences(
addressedOccurrences(normalizedText, occurrences),
);
const profiles = new Map<string, AgentProfile>();
for (const occurrence of explicitOccurrences) {
for (const profile of occurrence.profiles.values()) {
profiles.set(profile.id, profile);
}
}
if (profiles.size === 1) {
const chosen = profiles.values().next().value as AgentProfile;
return {
kind: "selected",
agentId: chosen.id,
name: chosen.name,
reason: "matched a coworker’s name in the message",
fallback: false,
viaMention: false,
viaNameMatch: true,
};
}
if (profiles.size > 1) {
return { kind: "ambiguous", names: labelsFor(profiles.values(), labels) };
}
return null;
}
function auditReason(
selected: Extract<CoworkerRouteResult, { kind: "selected" }>,
undecided: RoutingUndecided | null,
): string {
if (selected.viaNameMatch) return selected.reason;
if (selected.viaMention) return "named by the person asking";
if (selected.fallback)
return undecided ? `fallback: ${undecided}` : "fallback";
return "intent match";
}
export function createCoworkerRoutingService(
options: CreateCoworkerRoutingServiceOptions,
): HttpCoworkerRoutingService {
async function record(
actor: RoutingActor,
selected: Extract<CoworkerRouteResult, { kind: "selected" }>,
candidates: readonly string[],
undecided: RoutingUndecided | null,
): Promise<void> {
if (!options.auditStore) return;
await recordAuditEvent(options.auditStore, {
eventType: "channel.routed",
targetType: "agent",
targetId: selected.agentId,
...(actorId(actor) ? { actorUserId: actorId(actor) } : {}),
payload: {
chosen: selected.agentId,
reason: auditReason(selected, undecided),
fallback: selected.fallback,
viaMention: selected.viaMention,
viaNameMatch: selected.viaNameMatch === true,
candidates,
undecided,
},
});
}
async function routeDetailed(
input: CoworkerRoutingInput,
): Promise<CoworkerRouteDetail> {
if (!input.text.trim())
throw new CoworkerRoutingInputError("A message is required.");
if (input.text.length > MAX_ROUTING_TEXT_LENGTH) {
throw new CoworkerRoutingInputError();
}
// The store applies this same policy in SQL; keep this canonical policy check at the service
// boundary so a broader store implementation cannot leak a coworker into routing.
const roster = (await options.store.list(input.actor, false)).filter(
(profile) => canAccessAgent(input.actor, profile),
);
const namedId = input.agentId?.trim() || null;
if (namedId) {
const chosen = roster.find(({ id }) => id === namedId);
if (!chosen) return { result: { kind: "none" }, undecided: null };
const result: Extract<CoworkerRouteResult, { kind: "selected" }> = {
kind: "selected",
agentId: chosen.id,
name: chosen.name,
reason: "named by the person asking",
fallback: false,
viaMention: true,
};
await record(input.actor, result, [chosen.id], null);
return { result, undecided: null };
}
if (roster.length === 0)
return { result: { kind: "none" }, undecided: null };
const explicit = explicitNameRoute(input.text, roster);
if (explicit) {
if (explicit.kind === "selected") {
await record(input.actor, explicit, [explicit.agentId], null);
}
return { result: explicit, undecided: null };
}
const preferred = defaultRoutingProfile(roster);
if (!preferred) return { result: { kind: "none" }, undecided: null };
const candidates: RoutingCandidate[] = await Promise.all(
roster.map(async (profile) => ({
id: profile.id,
name: profile.name,
roleDescription: profile.roleDescription,
/*
* Never allowed to break routing. A connector store that is slow or unhappy must not turn
* "who is this for" into an error, so a failure here is the same as holding nothing: the
* router falls back to matching on purpose alone, which is what it did before.
*/
...(options.reachableSystems
? {
reaches: await options
.reachableSystems(profile.id)
.catch(() => [] as readonly string[]),
}
: {}),
})),
);
const decision = await options.router.route(
input.text,
candidates,
preferred.id,
);
const result: Extract<CoworkerRouteResult, { kind: "selected" }> = {
kind: "selected",
agentId: decision.agentId,
name: decision.name,
reason: decision.reason,
fallback: decision.fallback,
viaMention: false,
};
await record(
input.actor,
result,
candidates.map(({ id }) => id),
decision.undecided,
);
return { result, undecided: decision.undecided };
}
return {
async route(input) {
return (await routeDetailed(input)).result;
},
routeDetailed,
};
}