Route to the coworker somebody named, and stop building a Bot four ways

[jerelvelarde]

The problem

Four things in this deployment now build a Bot for a person: a chat request through
mountCopilotRuntime, a routine's headless turn through buildAgentFor, a hop delivered to another
Bot through agentFor, and whatever comes next. They have to build the same Bot, and today each
one is handed the same eleven collaborators positionally, in the same order, by hand. index.ts
already says so in a comment block in capitals — "they have to build the SAME Bot" — which is a
comment doing the work a type should do. One caller passing undefined where agentFetch goes is a
Bot that runs, answers, and quietly holds different tools or a different role from the one the person
is talking to. Nothing fails; the answer is just worse, and there is nothing to point at.

Choosing which coworker has the same shape of problem for a different reason. The model call, the
visibility rule, the preferred-coworker fallback and the channel.routed row are all written inside
a Hono handler, so nothing that is not an HTTP request can route. A routine cannot. A hop cannot.

And routing is paying for something it already knows. "ask Risk Analyst to review the Q3 filing"
names the coworker in the first four words, and the deployment sends the sentence to a model to be
told what the person already said — a model call and its latency on every such message, and
occasionally a different answer than the one asked for.

The approach

ActorAgentResolver binds the collaborators once. It is constructed at boot from the named
constants that already exist for this reason, and every surface asks it for a coworker instead of
re-assembling the wiring. resolveAgentsForActor gives the whole roster for a request;
resolveAgentForActor gives one, and passes the id down to resolveRuntimeAgents so the other Bots
are neither built nor asked what they hold. The roster is still read in full, so a coworker somebody
cannot see is still absent — that check does not move.

CoworkerRoutingService owns the decision, and the route owns the status codes. The service
returns selected, ambiguous or none; routing/routes.ts turns those into 200, 409 and 404. It
also re-applies canAccessAgent at its own boundary rather than trusting the store's SQL alone,
because a broader store implementation must not be able to leak a coworker into routing.

A name that matches exactly one coworker is honoured without a model call. Matching is against
the asking person's own roster, on NFKC-normalised names with Unicode token boundaries, so Riskier
does not match Risk. Suffix aliases are indexed too, and a longer alias that fully contains a
shorter one suppresses it — otherwise "Risk Analyst" would always read as ambiguous with a coworker
called "Analyst". Two coworkers that genuinely answer to one name is a 409 carrying both display
labels, not a guess, because silently redirecting a message somebody addressed by hand is the worst
answer available.

The cost is real. Name matching is string work on every untagged message, and it can be wrong in
the direction of refusing: a deployment with two coworkers whose names overlap will see 409s where it
used to see a model's pick. That is deliberate — the 409 names both, so the person resolves it in one
reply — but it is a behaviour change, not a pure addition, and it is in CHANGELOG.md as one.

A failed reachability read now stops the turn. Which systems a coworker can reach is weighed by
the router. Treating a failed read as "reaches nothing" is a false statement about the deployment
rather than an absence of one, and it quietly routed work away from the coworker that could do it.
CoworkerReachabilityUnavailableError refuses instead.

What is not covered

• Routing still runs per request. Nothing is cached, including the alias index, which is rebuilt from
  the roster on every untagged message.
• The duplicate-name label is the coworker's name plus its id in hex. It is unambiguous and it is not
  pretty. A friendlier disambiguator needs something the roster does not carry yet.
• resolveAgentForActor throws for a coworker the person cannot reach and the two existing callers
  both turn that into null. The distinction between "not registered" and "not yours" is not
  exposed, because neither caller should tell the difference to a person.
• No surface changed. The composer's own picker path, the response shape, and the audit payload are
  the same as before apart from the new named by the person asking reason.

Verification

Full suite on this branch, against a live PostgreSQL: 2094 pass, 0 fail, 23 skip, 2117 tests
across 172 files. main in the same environment runs 2084 across 170; the two new files are the
difference. bun run format:check, bun run lint, bun run typecheck and bun run build all clean. No schema change,
so drizzle-kit check and the unwritten-migration probe are untouched.

The recording drives CoworkerRoutingService against a real database, a real AgentProfileStore and
the real audit store. Only the intent model is a stand-in, and only so its calls can be counted — the
whole claim is that a named coworker never reaches it. It ends on the channel.routed rows, which
carry the reason and the candidates and never the message text.

• server/tests/routing-service.test.ts — the matching rules, one case per way a name can be
  ambiguous or contained; the visibility filter; the reachability refusal; and that the audit row is
  written exactly once and never carries the message.
• server/tests/agent-resolver.test.ts — that both entry points build through the same collaborators,
  and that asking for one coworker builds only that one.

[davidmckayv]

Verified and want this (named-coworker routing + the 4→1 resolver consolidation). Holding for a rebase: both #290 (index.ts/copilot.ts) and #309 (copilot.ts) landed after this branched and touch the same regions your ActorAgentResolver refactor consolidates. Please rebase onto current main so the resolver seam sits on top of #290's handoff wiring and #309's generative-UI middleware. CI verify was green pre-conflict. Thanks.

[Hotragn]

Read this closely because it rewrites routing/routes.ts, which I touched in #248, and I wanted to
check my field survived. It does — undecided is carried through routeDetailed and into the
channel.routed payload, and auditReason builds fallback: <cause> from it. Nothing was lost in
the move, which is the thing I most expected to find in a refactor this size.

The service extraction is the right shape. Four call sites building a Bot positionally from eleven
collaborators, with a capitalised comment doing a type's job, is exactly the kind of thing that goes
wrong quietly, and agent-resolver.ts fixes it in the only way that stays fixed.

One thing I would not merge as it stands.

Every suffix of a coworker's name becomes a standalone mention

buildAliasIndex adds the full normalized name and then every suffix of it, unconditionally:

addAlias(aliases, normalized, profile);
for (const suffix of suffixes(normalized)) addAlias(aliases, suffix, profile);

suffixes("risk analyst") is ["analyst"]. So on the example roster this repo ships:

Coworker	Aliases it registers
Risk Analyst	risk analyst, analyst
General Assistant	general assistant, assistant
Company Knowledge	company knowledge, knowledge

Those are ordinary English words, and hasTokenBoundaries will match them as whole tokens anywhere in
a sentence. So:

"I need some knowledge about the refund policy"

matches knowledge, and the result is kind: "selected", viaMention: true, with
reason: "named by the person asking".

Nobody named anybody. The person used a common noun, and the deployment records that they addressed a
coworker by name.

Two things follow, and the second is the one I care about:

The model is skipped, so nothing catches it. The whole value of the short-circuit is that a named
coworker is not a question — but this path is now reached by sentences that are very much a question,
with no confidence score and no fallback, because those only exist on the branch this one avoids.
"what does the agent field mean in this API" on a roster with a Travel Agent is the same shape.

The trail says something that is not true. channel.routed will carry
reason: "named by the person asking" and viaMention: true for a message that named nobody. That
row is the answer to "why did this go to Knowledge", and #134 already moved its wording once
specifically because an administrator reads it and the person who typed did not. A row asserting an
intent the person did not have is worse than one saying "inferred" — and it is now un-countable too,
since viaMention was the field that told inference from choice.

Ambiguity does not save it: two coworkers ending in analyst collide and go to ambiguous, but a
roster with exactly one ... Knowledge has no collision, so the single-coworker case is precisely
the one that silently wins.

What I would do

Any of these, and I have no strong preference between the first two:

• Require a suffix alias to be more than one token. suffixes("head of risk analysis") still
  gives of risk analysis and risk analysis, which are genuinely names people shorten to. Dropping
  the last single-token suffix removes analyst, assistant, knowledge and keeps everything that
  reads like a name.
• Only treat a suffix as a mention when it is addressed — preceded by @, or by ask/tell, or
  at the start of the message. The PR's own example, "ask Risk Analyst to review the Q3 filing", is
  addressed; "some knowledge about" is not.
• Or keep the match and stop calling it a mention. If a bare suffix should still route, it is an
  inference, so viaMention: false and a reason that says which alias matched. That keeps the trail
  honest even if the routing stays as it is.

The full-name match needs none of this — risk analyst appearing as whole tokens really is somebody
naming them, and that half is good.

Smaller notes, none blocking

• occurrencesOf advances by alias.length after a match, so overlapping occurrences are skipped. It
  cannot matter here, because an overlapping second occurrence has a word character before it and
  fails hasTokenBoundaries anyway — but it is worth a word, since the loop reads as though it means
  to find all of them.
• hasTokenBoundaries returns a nested ternary that computes "both sides are non-word". It is
  correct; (!before || !WORD.test(before)) && (!after || !WORD.test(after)) says the same thing and
  is one read rather than three.
• codePointCompare returns -1/1 for the prefix cases and a code-point difference otherwise,
  which is fine for a sort but means the magnitude is meaningless. Worth a line saying it is a
  comparator and not a distance, since the difference is tempting to reuse.

Happy to be wrong about the suffix case if the intent is that a bare knowledge should route there
— but then I would still argue it is not a mention, and the row should not say it was.

[Hotragn]

This has sat two and a half weeks with no review. Here is one, starting with the mechanical state because it decides whether the rest is worth your time, and then two things I would want changed — one of which is a hardening that has landed since you opened this and would be silently undone by a rebase.

It conflicts, and one of the conflicts is load-bearing

git merge-tree against main gives five:

File
CHANGELOG.md	trivial, the usual ## Unreleased collision
server/tests/copilot.test.ts	follows copilot.ts
server/tests/routing-routes.test.ts	follows routes.ts
server/src/copilot.ts	eight commits since, mostly #505 and #451
server/src/index.ts	eight commits since
server/src/routing/routes.ts	one commit, and it is the one to read

#548 capped the routing text. This PR deletes the file it capped

471d1a4 ("Cap routing text and harden routine dispatch and page-frame params", #548) landed in routing/routes.ts on 15 September:

// Unbounded text becomes the model prompt. Cap it so a multi-megabyte body cannot be used
// to force a timeout or OOM in the router.
if (text.length > 10000) {
  return context.json(
    { error: "A message of at most 10000 characters is required." },
    400,
  );
}

This PR takes 171 lines out of that file. I checked both new files rather than assuming:

• routing/routes.ts on this branch still has if (!text) return 400 and no length check.
• routing/service.ts has no length check either — grep for 10000 and for .length > finds only the duplicate-alias counting.

So a straight rebase resolves the conflict by taking your side of a file whose hardening arrived after you wrote it, and POST /api/route goes back to passing unbounded text to the model prompt. Nothing fails; the check is just gone, which is the worst way for a guard to disappear.

It needs a decision about where it lives now, not just a re-paste. The cap is about what reaches the model, and after this PR the thing that reaches the model is the service. My instinct is the service, so a routine or a hop routing through the same seam is capped too — the route is no longer the only caller, which is the whole point of the PR. But the route returning the 400 keeps status codes where you have deliberately put them. Either is defensible; dropping it is not.

viaMention now means two different things, and the trail cannot tell them apart

This is the part I would most want changed, and I should disclose that I wrote the channel.routed row's "say why, not only where" semantics in #248, so I am reviewing my own field.

On main that field has one meaning, and the docblock is explicit about it:

A person who named a coworker with @ has already decided, so nothing is inferred and no model is called. It is still recorded, with viaMention true and the person as the reason.

On this branch, two different paths produce the identical row. service.ts:311-323:

const namedId = input.agentId?.trim() || null;
if (namedId) { ... reason: "named by the person asking", viaMention: true }

and service.ts:249-257, reached from explicitNameRoute(input.text, roster):

if (profiles.size === 1) {
  return { ..., reason: "named by the person asking", viaMention: true };
}

The first is the person having decided. The second is this deployment's alias matcher finding a coworker's name somewhere in free text — NFKC-normalised, token-bounded, with suffix aliases and a containment-suppression rule. That is an inference. A good one, and I like the feature; the model call it saves is real. But it is not the person deciding, and the row says it was.

It matters because the matcher can be wrong in a way an @ cannot. It scans the whole message, so "don't let Risk Analyst see this, send it to Legal" contains Risk Analyst. Depending on what else is on the roster that is either a 409 or a route to the coworker the person explicitly excluded — and the trail records viaMention: true, reason: "named by the person asking". Somebody reading that row later has no way to find out the deployment guessed, because the row it produces is byte-identical to one where the person pointed.

The fix is cheap and I think it makes the feature more defensible rather than less — a third value. Keep viaMention for @ only, and give the name match its own reason, something like "matched a coworker's name in the message", with its own flag if auditReason needs to branch. Then the field still answers "did a model decide this", the new one answers "did the person decide or did we", and the first operator who gets a surprising route can count them.

What I would keep

• Re-applying canAccessAgent at the service boundary (service.ts:307-309) rather than trusting the store's SQL is right, and the comment gives the correct reason. Two enforcements of one rule is not duplication when one of them is a query somebody might later widen.
• The diagnosis in the first section is the strongest part of this PR. "Eleven collaborators passed positionally, with a capitalised comment doing the work a type should do" is exactly the failure this repo keeps finding, and ActorAgentResolver is the right answer to it. copilot.ts losing 107 lines and routes.ts losing 171 is the shape a correct extraction has.

I have not run this: the conflicts mean I would be testing a merge I invented rather than the one you will write. Happy to look again after the rebase — and if you would rather I sent the text cap as a separate commit onto your branch once it is rebased, say so.