Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat(route): answer the window's "which agent does this belong to"

0xdiego25055465b9d52d
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 13892ad08..4f3923e47 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -108,7 +108,7 @@ import {
deriveTurnSummary,
syncSummaryPoolSessions,
} from './lib/summarize.js'
-import { setVoiceRouterDeviceConnected, setVoiceRouterSessions, shutdownVoiceRouter } from './lib/voiceRouter.js'
+import { routeVoiceTask, setVoiceRouterDeviceConnected, setVoiceRouterSessions, shutdownVoiceRouter, type RouterAgent } from './lib/voiceRouter.js'
import { tailFile } from './lib/sessions.js'
import { E2eeStore } from './lib/e2ee/store.js'
import { b64e } from './lib/e2ee/core.js'
@@ -2825,6 +2825,55 @@ async function runForeground(session: AuthSession): Promise<void> {
// Ordered, not set-wise: two tiles swapping places is the same set and a different ring.
if (deskChanged) void cableRef?.syncAgents()
},
+ // ⌘K in the window: a typed task, and which agent it belongs to.
+ //
+ // THE SAME ROUTER THE DIAL USES, given a second caller. routeVoiceTask has never cared that its input
+ // arrived as speech — the transcript is just text by the time it sees it — so this is not a port. What
+ // is new is the answer coming back to something that can SHOW it: the dial had to act on the pick,
+ // the window can ask.
+ //
+ // LOCAL AGENTS ONLY (owner's call). It is what keeps this fast: the dial's cross-machine route pays an
+ // RPC per remote agent to fetch recaps, and that is most of its latency. The cost is real and chosen —
+ // ⌘K cannot reach an agent on another computer, even while its pane is on screen.
+ onRouteTask: async (text) => {
+ const sessions = registry.advertised()
+ sessions.sort((a, b) => a.registeredAt - b.registeredAt || a.agentId.localeCompare(b.agentId))
+ const candidates: RouterAgent[] = sessions.map((session) => ({
+ id: session.agentId,
+ name: projectDisplayName(session),
+ engine: session.engine,
+ // The same three recaps the dial's router weighs. `recent` reads the mirror this daemon already
+ // keeps, so this costs nothing and cannot be stale in a way the rest of the app is not.
+ recentSummary: mirror.recent(session.sessionId || session.agentId, 3)
+ .map((turn) => turn.recap || turn.text || '')
+ .filter(Boolean)
+ .join(' · '),
+ }))
+ const decision = await routeVoiceTask(text, candidates)
+ const named = (id: string) => candidates.find((agent) => agent.id === id)
+ // The runners-up, for the window to offer when the pick is weak. Scored the same way the fallback
+ // matcher scores — name over recent — so the list the person reads is ordered by the same rule the
+ // router used, not by registry position.
+ const others = candidates
+ .filter((agent) => agent.id !== decision.agentId)
+ .slice(0, 2)
+ return {
+ agentId: decision.agentId,
+ name: named(decision.agentId)?.name ?? '',
+ confidence: decision.confidence,
+ reason: decision.reason,
+ candidates: [decision.agentId ? named(decision.agentId) : null, ...others]
+ .filter((agent): agent is RouterAgent => !!agent)
+ .map((agent) => ({ agentId: agent.id, name: agent.name, recent: (agent.recentSummary ?? '').slice(0, 120) })),
+ }
+ },
+ // Committed. Delivered through the SAME door as every other message — the web's, the dial's, a
+ // hook's — so queueing, retries and the per-engine slash-command adaptation are not re-implemented
+ // for the one caller that types instead of speaking.
+ onRouteSend: (agentId, text) => {
+ console.log(`[route] ⌘K → ${sid(agentId)} · bytes=${Buffer.byteLength(text, 'utf8')}`)
+ backend.onMessage?.(agentId, text)
+ },
machineId: backend.machineId,
backend,
relayPool,
diff --git a/cli/src/localWsServer.spec.ts b/cli/src/localWsServer.spec.ts
index e666d7cfd..329174985 100644
--- a/cli/src/localWsServer.spec.ts
+++ b/cli/src/localWsServer.spec.ts
@@ -171,6 +171,99 @@ describe('local CLI WebSocket', () => {
ws.close()
})
+ it('answers a routed task on the id it was asked with, and sends nothing', async () => {
+ const backend = new FakeBackend()
+ const asked: string[] = []
+ server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
+ local = attachLocalWsServer(server, {
+ machineId,
+ backend,
+ onRouteTask: async (text) => {
+ asked.push(text)
+ return {
+ agentId: 'a1', name: 'auth-api', confidence: 0.86, reason: 'name matches',
+ candidates: [{ agentId: 'a1', name: 'auth-api', recent: 'token rotation' }],
+ }
+ },
+ })
+ await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
+ const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
+
+ const ws = new WebSocket(url)
+ await onceOpen(ws)
+ const connected = onceMessage(ws)
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
+ await connected
+
+ const answered = onceMessage(ws)
+ ws.send(JSON.stringify({ type: 'route_task', payload: { requestId: 'q-7', text: ' fix the retry ' } }))
+ const reply = await answered // onceMessage already parses
+ // The requestId comes back UNTOUCHED — it is the window's own rpc id, and the only thing tying this
+ // answer to the spinner it is holding open.
+ expect(reply.type).toBe('route_result')
+ expect(reply.payload).toMatchObject({ requestId: 'q-7', agentId: 'a1', name: 'auth-api', confidence: 0.86 })
+ expect(asked).toEqual(['fix the retry'])
+ // Asking is not sending. Nothing reached the machine.
+ expect(backend.frames.map((frame) => frame.type)).toEqual([])
+ ws.close()
+ })
+
+ it('still answers when there is nothing to answer with', async () => {
+ // The window holds a spinner on the id it asked with, so silence is the one reply it cannot recover
+ // from — an empty task and a router that throws must both come back as frames.
+ const backend = new FakeBackend()
+ server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
+ local = attachLocalWsServer(server, {
+ machineId,
+ backend,
+ onRouteTask: async () => { throw new Error('router unavailable') },
+ })
+ await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
+ const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
+
+ const ws = new WebSocket(url)
+ await onceOpen(ws)
+ const connected = onceMessage(ws)
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
+ await connected
+
+ const blank = onceMessage(ws)
+ ws.send(JSON.stringify({ type: 'route_task', payload: { requestId: 'q-empty', text: ' ' } }))
+ expect((await blank).payload).toMatchObject({ requestId: 'q-empty', agentId: '', reason: 'empty task' })
+
+ const failed = onceMessage(ws)
+ ws.send(JSON.stringify({ type: 'route_task', payload: { requestId: 'q-throw', text: 'anything' } }))
+ expect((await failed).payload).toMatchObject({ requestId: 'q-throw', agentId: '', reason: 'router unavailable' })
+ ws.close()
+ })
+
+ it('delivers a committed route, and keeps the frame off the wire', async () => {
+ const backend = new FakeBackend()
+ const sent: Array<{ agentId: string; text: string }> = []
+ server = http.createServer((_req, res) => { res.statusCode = 404; res.end() })
+ local = attachLocalWsServer(server, {
+ machineId,
+ backend,
+ onRouteSend: (agentId, text) => sent.push({ agentId, text }),
+ })
+ await new Promise<void>((resolve) => server!.listen(0, '127.0.0.1', resolve))
+ const url = `ws://127.0.0.1:${(server.address() as AddressInfo).port}/api/local-ws`
+
+ const ws = new WebSocket(url)
+ await onceOpen(ws)
+ const connected = onceMessage(ws)
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))
+ await connected
+
+ ws.send(JSON.stringify({ type: 'route_send', payload: { agentId: 'a2', text: 'do the thing' } }))
+ ws.send(JSON.stringify({ type: 'route_send', payload: { agentId: '', text: 'nobody' } }))
+ await new Promise((resolve) => setTimeout(resolve, 20))
+ // The half-formed one is dropped rather than delivered to whoever sorts first.
+ expect(sent).toEqual([{ agentId: 'a2', text: 'do the thing' }])
+ expect(backend.frames.map((frame) => frame.type)).toEqual([])
+ ws.close()
+ })
+
it('does not require a credential on the loopback transport', async () => {
const url = await start(new FakeBackend())
const ws = new WebSocket(url, ['legacy-client-label'])
diff --git a/cli/src/localWsServer.ts b/cli/src/localWsServer.ts
index ca3f17285..838fb5619 100644
--- a/cli/src/localWsServer.ts
+++ b/cli/src/localWsServer.ts
@@ -31,6 +31,33 @@ export interface LocalWsServerOptions {
onAppFocus?: (machineId: string, agentId: string) => void
/** Every agent the window currently has a tile for, across all its machines. */
onAppPanes?: (agentIds: string[]) => void
+ /**
+ * The window asked WHICH AGENT a typed task belongs to (⌘K). Answers, and sends NOTHING.
+ *
+ * Two frames rather than one, and the split is the design: the window decides whether the answer is
+ * good enough to act on. Fold them together with a `commit` flag and the confidence threshold moves in
+ * here, where nothing knows what the person is looking at.
+ */
+ onRouteTask?: (text: string) => Promise<RouteAnswer>
+ /** The window committed to an agent — deliver the task the way every other message is delivered. */
+ onRouteSend?: (agentId: string, text: string) => void
+}
+
+/** One candidate, as the window draws it in the picker. */
+export interface RouteCandidate {
+ agentId: string
+ name: string
+ /** What it was last doing — the line under the name when the window has to ask. */
+ recent: string
+}
+
+export interface RouteAnswer {
+ agentId: string
+ name: string
+ confidence: number
+ reason: string
+ /** The best few, most confident first. Only read when the window decides to ask. */
+ candidates: RouteCandidate[]
}
export interface LocalWsServer {
@@ -210,6 +237,42 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
return
}
}
+ // ⌘K: the only REQUEST/RESPONSE pair this socket serves. Everything else on it is one-way.
+ //
+ // It rides the app's OWN rpc convention — `payload.requestId` out, the same id back — which the
+ // window already implements end to end: the pending map, the timeout, the queue-across-reconnect
+ // and the logging are all there (ws_conn.dart `request()`). Inventing a second correlation field
+ // here would have meant a second, thinner copy of all of it on the side that already had one.
+ //
+ // Consumed here like app_focus: it describes a hand at this desk, not anything the machine could
+ // act on.
+ if (!isBinary && (options.onRouteTask || options.onRouteSend)) {
+ const asked = jsonFrame(raw)
+ if (asked?.type === 'route_task' && options.onRouteTask) {
+ const payload = asked.payload as Record<string, unknown> | undefined
+ const requestId = typeof payload?.requestId === 'string' ? payload.requestId : ''
+ const text = typeof payload?.text === 'string' ? payload.text.trim() : ''
+ // An answer ALWAYS goes back, even for a question we cannot serve: the window is holding a
+ // spinner open on this id, and silence is the one reply it cannot recover from.
+ let answer: RouteAnswer = { agentId: '', name: '', confidence: 0, reason: 'empty task', candidates: [] }
+ if (text) {
+ try {
+ answer = await options.onRouteTask(text)
+ } catch (err) {
+ answer = { agentId: '', name: '', confidence: 0, reason: (err as Error).message.slice(0, 120), candidates: [] }
+ }
+ }
+ sink.sendFrame({ type: 'route_result', payload: { requestId, ...answer } })
+ return
+ }
+ if (asked?.type === 'route_send' && options.onRouteSend) {
+ const payload = asked.payload as Record<string, unknown> | undefined
+ const agentId = typeof payload?.agentId === 'string' ? payload.agentId : ''
+ const text = typeof payload?.text === 'string' ? payload.text : ''
+ if (agentId && text) options.onRouteSend(agentId, text)
+ return
+ }
+ }
if (!isBinary && options.onAppFocus && boundMachineId) {
const moved = jsonFrame(raw)
const agentId = (moved?.payload as Record<string, unknown> | undefined)?.agentId