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.
Send an untagged message to the coworker it is for (#122)
David McKay42af1b6cb20f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c2456167..e8bc3681 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -54,6 +54,14 @@ Sessions survive and nobody signs in again.a copy of a customer's corpus is not a thing OpenBot does.### Added+- **A message with no `@` goes to the coworker it is for.** Typing without naming anyone used to+ reach the default coworker; to get a specialist you had to `@` them. Now an untagged message is+ routed to the coworker whose purpose matches it, chosen against each coworker's own description by+ the deployment's own model, before the channel is pinned. It is named, not silent: the channel+ header is the coworker it went to, and a `channel.routed` row records the choice, the reason, and+ the candidates it chose between (never the message itself). `@` still wins as an explicit override+ and skips routing entirely. If the router is uncertain or unreachable, it falls back to the same+ default the composer always used, and says so, rather than misroute or drop.- **Releases are cut by a workflow, not by hand.** `Create release PR` bumps the version and promotes`## Unreleased` to a numbered section; merging the pull request it opens is what publishes. Mergingdiff --git a/app/src/lib/channels/route.ts b/app/src/lib/channels/route.tsnew file mode 100644index 00000000..5c3fc183--- /dev/null+++ b/app/src/lib/channels/route.ts@@ -0,0 +1,26 @@+import { client } from "@/lib/client";++/**+ * Which coworker an untagged message should go to.+ *+ * Called only when the composer draft names no one with `@`. The server reads the roster for the+ * person asking and picks by what each coworker is for, so this can only ever return a coworker they+ * are already allowed to reach. `fallback` is true when it is the default rather than an inferred+ * match, which the caller can say out loud. A thrown error here is not fatal: the caller falls back+ * to the default coworker, which is exactly what the server does too.+ */+export type RoutingDecision = {+ agentId: string;+ name: string;+ reason: string;+ fallback: boolean;+};++export async function routeMessage(text: string): Promise<RoutingDecision> {+ const response = await client("/api/route", {+ method: "POST",+ body: { text },+ fallback: "Could not choose a coworker.",+ });+ return (await response.json()) as RoutingDecision;+}diff --git a/app/src/routes/_authed/_app/index.tsx b/app/src/routes/_authed/_app/index.tsxindex e54b08a3..2bec34ca 100644--- a/app/src/routes/_authed/_app/index.tsx+++ b/app/src/routes/_authed/_app/index.tsx@@ -4,6 +4,7 @@ import { useState } from "react";import { AgentCard } from "@/components/agents/agent-card";import { Composer, toAgentOptions } from "@/components/channels/composer";import { agentListQueryOptions } from "@/lib/agents/queries";+import { routeMessage } from "@/lib/channels/route";import { useStartChannel } from "@/lib/channels/start";import { appConfig } from "@/lib/generated/application-config";@@ -36,12 +37,21 @@ function RouteComponent() {className="w-full max-w-2xl"disabled={!fallback}onSubmit={async (draft) => {- // A channel is pinned to one coworker for the life of its thread.- const agentId = draft.agentId ?? fallback?.id;- if (!agentId) return;-+ // A channel is pinned to one coworker for the life of its thread, so the coworker is+ // chosen now, before it is created. An `@` is an explicit choice and is honoured as-is.+ // With no `@`, the message is routed to the coworker it is for; if that routing cannot+ // run, it falls back to the same default the composer used to always use.setError(null);try {+ let agentId: string | undefined = draft.agentId ?? undefined;+ if (!agentId) {+ try {+ agentId = (await routeMessage(draft.text)).agentId;+ } catch {+ agentId = fallback?.id;+ }+ }+ if (!agentId) return;await start(agentId, draft.text);} catch (caught) {setError(@@ -58,7 +68,8 @@ function RouteComponent() {// Said out loud: a message that silently reaches somebody you did not choose is the// kind of surprise that costs trust the first time it happens.<p className="mt-2 w-full max-w-2xl text-xs text-muted-foreground text-center">- Goes to {fallback.name}. Type <code>@</code> to reach somebody else.+ Sent to the coworker it is for. Type <code>@</code> to choose one+ yourself.</p>) : null}{error ? (diff --git a/server/src/app.ts b/server/src/app.tsindex 0ccb1d4f..63025b6a 100644--- a/server/src/app.ts+++ b/server/src/app.ts@@ -5,6 +5,8 @@ import { authoriseAgentCall } from "./agents/callback-token";import type { BotAccessCheck } from "./agents/profile-policy";import type { AgentProfileStore } from "./agents/profile-store";import { createAgentRoutes } from "./agents/routes";+import { createRoutingRoutes } from "./routing/routes";+import type { IntentRouter } from "./routing/classify";import {type AuditReader,type AuditStore,@@ -147,6 +149,14 @@ export function createApp(* metadata in. See identity-provider-store.ts.*/identityProviders?: IdentityProviderStore,+ /**+ * Chooses which coworker an untagged message is for, before a channel is pinned to one.+ *+ * Passed in already built, like the copilot handler, so this module never imports the model+ * client. Absent leaves the composer's existing behaviour untouched: an untagged message goes to+ * the default coworker, which is exactly the failsafe the router itself falls back to.+ */+ intentRouter?: IntentRouter,) {const app = new Hono<{ Variables: AppVariables }>();@@ -675,6 +685,20 @@ export function createApp(auditStore,),);+ // Choosing a coworker for an untagged message needs the same permission-filtered roster the+ // agents routes read, so it is mounted here where that store is in scope. Only when a router was+ // configured; without one the composer keeps sending untagged messages to the default.+ if (intentRouter) {+ app.route(+ "/api/route",+ createRoutingRoutes(+ agentProfileStore,+ intentRouter,+ requireUser,+ auditStore,+ ),+ );+ }}if (channelStore) {diff --git a/server/src/audit.ts b/server/src/audit.tsindex 5d346208..8391f172 100644--- a/server/src/audit.ts+++ b/server/src/audit.ts@@ -40,6 +40,16 @@ export const auditEventTypes = ["connector.sync_succeeded","connector.sync_failed","knowledge.searched",+ /**+ * Which coworker an untagged message was routed to, and why.+ *+ * A channel is pinned to one coworker before its first turn, so when the person did not name one+ * with `@`, something chooses. This is that choice, made visible: the row names the coworker it+ * went to, whether it was an inferred match or the default it fell back to, and the coworkers it+ * chose between. The message itself is not here (the payload redaction drops it either way) — a+ * routing decision is a fact about where a conversation went, not a copy of what was said.+ */+ "channel.routed","agent.invoked",/*** A Bot's stream stopped producing anything and the turn was ended for it.diff --git a/server/src/index.ts b/server/src/index.tsindex f14d7278..a0f2bfdc 100644--- a/server/src/index.ts+++ b/server/src/index.ts@@ -1,3 +1,5 @@+import { createIntentRouter } from "./routing/classify";+import { createModelCompleter } from "./routing/model";import { serve } from "bun";import { mintRunAssertion } from "./agents/callback-token";import { createAgentProfileStore } from "./agents/profile-store";@@ -350,6 +352,20 @@ const stallGuard = createStallGuard({auditStore: bootAuditStore,});+const intentRouter = createIntentRouter({+ complete: createModelCompleter({+ model: tenantPackage.model,+ resolveApiKey: () =>+ resolveModelApiKey({+ encryptionKey: config.keyEncryptionKey,+ reader: credentialStore,+ provider: tenantPackage.model.provider,+ keyId: tenantPackage.model.credentialSecretRef,+ environment: process.env,+ }),+ }),+});+const app = createApp(config,auth,@@ -425,6 +441,8 @@ const app = createApp(// The enterprise identity providers registered here. Read as facts about the deployment rather// than through Better Auth's own listing, which answers per person. See identity-provider-store.ts.identityProviderStore,+ // Chooses the coworker for an untagged message, on the deployment's own model and key.+ intentRouter,);/**diff --git a/server/src/routing/classify.ts b/server/src/routing/classify.tsnew file mode 100644index 00000000..84377337--- /dev/null+++ b/server/src/routing/classify.ts@@ -0,0 +1,131 @@+/**+ * Choosing which coworker an untagged message is for.+ *+ * A channel is pinned to one coworker for the life of its thread, and the pin is set before the+ * first turn runs, so this decision happens at channel creation, not during a run. When the person+ * named a coworker with `@`, there is nothing to decide and this is never called. When they did not,+ * this reads the message against what each coworker is for and picks one.+ *+ * The model call is injected rather than made here, so the part that matters — what happens when the+ * answer is missing, malformed, or names a coworker that is not on the roster — is a plain function+ * with no network in the way. Every one of those failure paths lands on the deployment's default+ * coworker and says so; nothing here ever throws, because a router that throws would turn "we were+ * not sure who to ask" into "your message went nowhere".+ */++export type RoutingCandidate = {+ id: string;+ name: string;+ /** What this coworker is for. The one line an operator wrote to say when to reach them. */+ roleDescription: string;+};++export type RoutingDecision = {+ agentId: string;+ name: string;+ /** A sentence a person reads, naming why it went where it went. */+ reason: string;+ /** True when this is the default rather than an inferred match: an honest "we were not sure". */+ fallback: boolean;+};++/** Below this the match is a guess, and a guess should defer to the default rather than surprise. */+const MIN_CONFIDENCE = 0.6;++export function routingPrompt(+ text: string,+ candidates: readonly RoutingCandidate[],+): string {+ const roster = candidates+ .map((c) => `- id: ${c.id}\n name: ${c.name}\n for: ${c.roleDescription}`)+ .join("\n");+ return [+ "You route a person's message to the one coworker best suited to it.",+ "Here are the coworkers and what each is for:",+ roster,+ "",+ 'Reply with only JSON: {"agentId": "<one id from the list>", "reason": "<short, names the fit>", "confidence": <0..1>}.',+ "Pick the specialist whose purpose matches the message. If none clearly fits, use the most general coworker and give it a low confidence.",+ "",+ `Message: ${text}`,+ ].join("\n");+}++export function createIntentRouter(deps: {+ /** Runs the prompt and returns the model's raw text. May reject; the router absorbs it. */+ complete: (prompt: string) => Promise<string>;+}) {+ return {+ async route(+ text: string,+ candidates: readonly RoutingCandidate[],+ defaultId: string,+ ): Promise<RoutingDecision> {+ const byId = new Map(candidates.map((c) => [c.id, c]));+ const fallback = (reason: string): RoutingDecision => {+ const chosen = byId.get(defaultId) ?? candidates[0];+ return chosen+ ? { agentId: chosen.id, name: chosen.name, reason, fallback: true }+ : // No roster at all is a misconfiguration, not a routing outcome; surface the default id.+ { agentId: defaultId, name: defaultId, reason, fallback: true };+ };++ // Nothing to decide between: one coworker, or none but the default.+ if (candidates.length <= 1) {+ return fallback("the only coworker available");+ }++ let raw: string;+ try {+ raw = await this._complete(text, candidates);+ } catch {+ return fallback(+ "sent to your default while the router was unreachable",+ );+ }++ let parsed: { agentId?: unknown; reason?: unknown; confidence?: unknown };+ try {+ // The model is asked for bare JSON, but tolerate a fenced or padded answer.+ const match = raw.match(/\{[\s\S]*\}/);+ parsed = match ? JSON.parse(match[0]) : {};+ } catch {+ return fallback(+ "sent to your default; the router's answer did not parse",+ );+ }++ const id = typeof parsed.agentId === "string" ? parsed.agentId : "";+ const match = byId.get(id);+ if (!match) {+ // A returned id that is not on the roster is the dangerous case: never act on it.+ return fallback(+ "sent to your default; the router named no coworker on your roster",+ );+ }+ const confidence =+ typeof parsed.confidence === "number" ? parsed.confidence : 0;+ if (confidence < MIN_CONFIDENCE) {+ return fallback(+ "sent to your default; no specialist was a confident match",+ );+ }++ const reason =+ typeof parsed.reason === "string" && parsed.reason.trim()+ ? parsed.reason.trim()+ : `matches ${match.name}`;+ return { agentId: match.id, name: match.name, reason, fallback: false };+ },++ // Split out so the prompt-build + call is one seam the tests can leave alone.+ async _complete(+ text: string,+ candidates: readonly RoutingCandidate[],+ ): Promise<string> {+ return deps.complete(routingPrompt(text, candidates));+ },+ };+}++export type IntentRouter = ReturnType<typeof createIntentRouter>;diff --git a/server/src/routing/model.ts b/server/src/routing/model.tsnew file mode 100644index 00000000..fc6fa487--- /dev/null+++ b/server/src/routing/model.ts@@ -0,0 +1,44 @@+import type { RuntimeModel } from "../copilot";++/**+ * The one model call the router makes, kept apart from the routing logic so that logic stays a pure+ * function the tests drive without a network. This reuses the deployment's own model and key — the+ * same ones the built-in coworkers answer on — so a router is never a second thing to configure.+ *+ * It throws on a missing key or a bad response on purpose: the router treats a throw as "not sure"+ * and lands on the default, so failure here is a soft landing, not an error a person sees.+ */+export function createModelCompleter(deps: {+ model: RuntimeModel;+ resolveApiKey: () => Promise<string | null>;+}): (prompt: string) => Promise<string> {+ return async (prompt: string) => {+ const key = await deps.resolveApiKey();+ if (!key) throw new Error("no model key");+ const base =+ process.env.OPENAI_BASE_URL?.trim() || "https://api.openai.com";+ const response = await fetch(`${base}/v1/chat/completions`, {+ method: "POST",+ headers: {+ "content-type": "application/json",+ authorization: `Bearer ${key}`,+ },+ body: JSON.stringify({+ model: deps.model.defaultModel,+ temperature: 0,+ response_format: { type: "json_object" },+ messages: [{ role: "user", content: prompt }],+ }),+ signal: AbortSignal.timeout(10_000),+ });+ if (!response.ok)+ throw new Error(`router model answered ${response.status}`);+ const body = (await response.json()) as {+ choices?: { message?: { content?: unknown } }[];+ };+ const content = body.choices?.[0]?.message?.content;+ if (typeof content !== "string")+ throw new Error("router model returned no text");+ return content;+ };+}diff --git a/server/src/routing/routes.ts b/server/src/routing/routes.tsnew file mode 100644index 00000000..c884d4d1--- /dev/null+++ b/server/src/routing/routes.ts@@ -0,0 +1,77 @@+import { Hono } from "hono";+import type { MiddlewareHandler } from "hono";+import type { AuditStore } from "../audit";+import { recordAuditEvent } from "../audit";+import type { AppVariables } from "../auth/guards";+import type { AgentProfileStore } from "../agents/profile-store";+import type { IntentRouter, RoutingCandidate } from "./classify";++const DEV_ACTOR_EMAIL = "[email protected]";++/**+ * Decide which coworker an untagged message is for, before a channel is pinned to one.+ *+ * The roster is read for the person asking, so the router can only ever pick a coworker they are+ * already allowed to reach. The decision is recorded like every other one in the product: a+ * `channel.routed` row names where it went and why, and carries the candidate ids but never the+ * message itself, which the audit payload redaction would drop anyway.+ */+export function createRoutingRoutes(+ store: AgentProfileStore,+ router: IntentRouter,+ requireUser: MiddlewareHandler<{ Variables: AppVariables }>,+ auditStore?: AuditStore,+) {+ const routes = new Hono<{ Variables: AppVariables }>();++ routes.post("/", requireUser, async (context) => {+ const body = (await context.req.json().catch(() => null)) as {+ text?: unknown;+ } | null;+ const text = typeof body?.text === "string" ? body.text.trim() : "";+ if (!text) return context.json({ error: "A message is required." }, 400);++ const actor = context.var.actor;+ const roster = await store.list(actor, false);+ // The same default the composer shows: the first public coworker, else the first at all.+ const preferred =+ roster.find((a) => a.visibility === "public") ?? roster[0];+ if (!preferred) {+ return context.json({ error: "No coworker is available." }, 409);+ }+ const candidates: RoutingCandidate[] = roster.map((a) => ({+ id: a.id,+ name: a.name,+ roleDescription: a.roleDescription,+ }));++ const decision = await router.route(text, candidates, preferred.id);++ if (auditStore) {+ await recordAuditEvent(auditStore, {+ eventType: "channel.routed",+ targetType: "agent",+ targetId: decision.agentId,+ ...(actor?.id && actor.email !== DEV_ACTOR_EMAIL+ ? { actorUserId: actor.id }+ : {}),+ payload: {+ chosen: decision.agentId,+ reason: decision.reason,+ fallback: decision.fallback,+ viaMention: false,+ candidates: candidates.map((c) => c.id),+ },+ });+ }++ return context.json({+ agentId: decision.agentId,+ name: decision.name,+ reason: decision.reason,+ fallback: decision.fallback,+ });+ });++ return routes;+}diff --git a/server/tests/routing-classify.test.ts b/server/tests/routing-classify.test.tsnew file mode 100644index 00000000..ef93da24--- /dev/null+++ b/server/tests/routing-classify.test.ts@@ -0,0 +1,102 @@+import { describe, expect, test } from "bun:test";+import {+ createIntentRouter,+ type RoutingCandidate,+} from "../src/routing/classify";++const ROSTER: RoutingCandidate[] = [+ {+ id: "general-assistant",+ name: "General Assistant",+ roleDescription: "everyday work",+ },+ {+ id: "knowledge",+ name: "Knowledge",+ roleDescription: "company knowledge questions",+ },+ {+ id: "risk-analyst",+ name: "Risk Analyst",+ roleDescription: "transaction monitoring and fraud risk",+ },+];+const withAnswer = (answer: string) =>+ createIntentRouter({ complete: async () => answer });+const throwing = () =>+ createIntentRouter({+ complete: async () => {+ throw new Error("model down");+ },+ });++describe("routing a message with no @mention", () => {+ test("routes to the specialist the model picks, named, not a fallback", async () => {+ const r = await withAnswer(+ '{"agentId":"risk-analyst","reason":"fraud review","confidence":0.9}',+ ).route(+ "review this transaction for fraud risk",+ ROSTER,+ "general-assistant",+ );+ expect(r.agentId).toBe("risk-analyst");+ expect(r.name).toBe("Risk Analyst");+ expect(r.fallback).toBe(false);+ expect(r.reason).toContain("fraud");+ });++ test("falls back to the default, named, when the model is unreachable", async () => {+ const r = await throwing().route("anything", ROSTER, "general-assistant");+ expect(r.agentId).toBe("general-assistant");+ expect(r.fallback).toBe(true);+ expect(r.reason).toContain("unreachable");+ });++ test("falls back when the answer does not parse", async () => {+ const r = await withAnswer("I think the risk analyst?").route(+ "x",+ ROSTER,+ "general-assistant",+ );+ expect(r.agentId).toBe("general-assistant");+ expect(r.fallback).toBe(true);+ });++ test("NEVER acts on an id that is not on the roster", async () => {+ const r = await withAnswer(+ '{"agentId":"payroll-bot","reason":"payroll","confidence":0.99}',+ ).route("x", ROSTER, "general-assistant");+ expect(r.agentId).toBe("general-assistant");+ expect(r.fallback).toBe(true);+ expect(r.reason).toContain("no coworker on your roster");+ });++ test("defers to the default when confidence is low", async () => {+ const r = await withAnswer(+ '{"agentId":"risk-analyst","reason":"maybe","confidence":0.3}',+ ).route("hi", ROSTER, "general-assistant");+ expect(r.agentId).toBe("general-assistant");+ expect(r.fallback).toBe(true);+ });++ test("a fenced/padded JSON answer is still parsed", async () => {+ const r = await withAnswer(+ '```json\n{"agentId":"knowledge","reason":"policy lookup","confidence":0.8}\n```',+ ).route("what is our refund policy", ROSTER, "general-assistant");+ expect(r.agentId).toBe("knowledge");+ expect(r.fallback).toBe(false);+ });++ test("a single-coworker roster is a fallback, not a model call", async () => {+ let called = false;+ const r = await createIntentRouter({+ complete: async () => {+ called = true;+ return "{}";+ },+ }).route("x", [ROSTER[0]!], "general-assistant");+ expect(called).toBe(false);+ expect(r.agentId).toBe("general-assistant");+ expect(r.fallback).toBe(true);+ });+});