fix(orchestration): start a remote chat worker only for a home that knows one

A new federated protocol version 5, sent only when the server advertises
orchestration.federation-chat-workers.v1, says the home understands a chat
worker. An older home gets a terminal, exactly as before, so its receipt
never calls a chat a terminal.
This commit is contained in:
Jinwoo-H
2026-11-09 03:28:35 -05:00
parent b399ba20cd
commit ba767ed682
5 changed files with 46 additions and 7 deletions
@@ -85,7 +85,7 @@ async function startedChatWorker() {
dispatchId: DISPATCH,
taskId: 'task_home',
taskSpec: 'Check the docs and report.',
protocolVersion: 4,
protocolVersion: 5,
worktree: 'id:workspace-1',
agent: 'codex'
})
@@ -281,7 +281,7 @@ describe('a chat worker that a coordinator on another computer starts here', ()
dispatchId: DISPATCH,
taskId: 'task_home',
taskSpec: 'Check the docs and report.',
protocolVersion: 4,
protocolVersion: 5,
worktree: 'new-top-level',
repo: 'id:repo',
agent: 'codex'
@@ -298,4 +298,27 @@ describe('a chat worker that a coordinator on another computer starts here', ()
await settleTurn(resolveStructuredWorkerIdentity(handle, db)!.sessionId, 0)
await expect(started).resolves.toMatchObject({ state: 'ready', mode: { mode: 'structured' } })
})
it('starts a terminal, as before, for a home too old to know a chat worker', async () => {
const createTerminal = vi
.spyOn(runtime, 'createTerminal')
.mockRejectedValue(new Error('terminal launch reached'))
await expect(
federation('orchestration.federationAttachStart', {
runId: 'run_home',
dispatchId: DISPATCH,
taskId: 'task_home',
taskSpec: 'Check the docs and report.',
protocolVersion: 4,
worktree: 'id:workspace-1',
agent: 'codex'
})
).resolves.toMatchObject({ state: 'failed', lastError: 'terminal launch reached' })
expect(createTerminal).toHaveBeenCalledWith(
'id:workspace-1',
expect.objectContaining({ startupAgent: 'codex' })
)
expect(sessionCreate.createStructuredAgentSessionForWorktree).not.toHaveBeenCalled()
})
})
@@ -36,6 +36,7 @@ import {
sendFederatedWorkerBrief,
type StructuredSession
} from './federated-worker-brief'
import { ORCHESTRATION_FEDERATION_CHAT_WORKERS_PROTOCOL_VERSION } from '../../../../../../shared/orchestration/orchestration-runtime-capabilities'
import { claimTerminalForRemoteAttach } from '../../../../orchestration/db/worker-dispatch/worker-terminal-claim'
export const ORCHESTRATION_FEDERATION_ATTACH_METHODS = [
@@ -107,10 +108,13 @@ export const ORCHESTRATION_FEDERATION_ATTACH_METHODS = [
let terminalHandle = params.terminal
let terminalCreation: RuntimeTerminalCreate | undefined
let structuredSession: StructuredSession | null = null
// This host decides chat or terminal from its own settings, as a local start does.
// This host decides chat or terminal from its own settings, as a local start does; a home too old
// to know a chat worker gets the terminal it expects.
let mode = decideWorkerStartMode({
params: { agent, terminal: params.terminal, worktree: params.worktree },
settings: readWorkerStartModeSettings(runtime)
settings: readWorkerStartModeSettings(runtime),
terminalOnly:
params.protocolVersion < ORCHESTRATION_FEDERATION_CHAT_WORKERS_PROTOCOL_VERSION
})
const setupSource = federatedSetupSource(params, createsWorktree)
let setup = initialFederatedSetup(params, createsWorktree, setupSource)
@@ -38,10 +38,12 @@ type WorkerStartModePlacement = {
export function decideWorkerStartMode(args: {
params: WorkerStartModePlacement
settings: AgentLaunchModeSettings | null | undefined
terminalOnly?: boolean
}): WorkerStartModeReceipt {
return decideAgentLaunchMode({
placement: args.params,
settings: args.settings,
terminalOnly: args.terminalOnly,
vocabulary: WORKER_START_VOCABULARY
})
}
@@ -37,9 +37,14 @@ export const ORCHESTRATION_ASK_RETURNS_AT_ONCE_RUNTIME_CAPABILITY =
/** A finished remote worker takes follow-ups here and can still mail and ask its Run home. */
export const ORCHESTRATION_FEDERATION_FOLLOW_UP_RUNTIME_CAPABILITY =
'orchestration.federation-follow-up.v1' as const
/** This server starts a remote worker as a chat when its own settings prefer chats and the home asks for it. */
export const ORCHESTRATION_FEDERATION_CHAT_WORKERS_RUNTIME_CAPABILITY =
'orchestration.federation-chat-workers.v1' as const
export const ORCHESTRATION_FEDERATION_CONTROL_MAIL_PROTOCOL_VERSION = 2 as const
export const ORCHESTRATION_FEDERATION_LIFECYCLE_SETTLEMENT_PROTOCOL_VERSION = 3 as const
export const ORCHESTRATION_FEDERATION_FOLLOW_UP_PROTOCOL_VERSION = 4 as const
/** The home understands a chat worker in the receipt; an older home always gets a terminal. */
export const ORCHESTRATION_FEDERATION_CHAT_WORKERS_PROTOCOL_VERSION = 5 as const
export const ORCHESTRATION_CONTRACT_VERSION = 1 as const
export const ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY = 'orchestration.contract.v1' as const
@@ -60,13 +65,14 @@ export const ORCHESTRATION_RUNTIME_CAPABILITIES = [
ORCHESTRATION_WORKER_TURN_STOP_REPORTS_RUNTIME_CAPABILITY,
ORCHESTRATION_ASK_RETURNS_AT_ONCE_RUNTIME_CAPABILITY,
ORCHESTRATION_FEDERATION_FOLLOW_UP_RUNTIME_CAPABILITY,
ORCHESTRATION_FEDERATION_CHAT_WORKERS_RUNTIME_CAPABILITY,
ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY
] as const
/** The newest federated protocol both sides speak; each version needs every earlier one's capability. */
export function federationProtocolVersionFor(
capabilities: readonly string[] | undefined
): 1 | 2 | 3 | 4 {
): 1 | 2 | 3 | 4 | 5 {
const ladder = [
[
ORCHESTRATION_FEDERATION_CONTROL_MAIL_RUNTIME_CAPABILITY,
@@ -79,9 +85,13 @@ export function federationProtocolVersionFor(
[
ORCHESTRATION_FEDERATION_FOLLOW_UP_RUNTIME_CAPABILITY,
ORCHESTRATION_FEDERATION_FOLLOW_UP_PROTOCOL_VERSION
],
[
ORCHESTRATION_FEDERATION_CHAT_WORKERS_RUNTIME_CAPABILITY,
ORCHESTRATION_FEDERATION_CHAT_WORKERS_PROTOCOL_VERSION
]
] as const
let version: 1 | 2 | 3 | 4 = 1
let version: 1 | 2 | 3 | 4 | 5 = 1
for (const [capability, next] of ladder) {
if (!capabilities?.includes(capability)) {
break
@@ -11,7 +11,7 @@ export const FederationAttachStartParams = z.object({
taskSpec: requiredString('Missing Task spec'),
/** Depth stamped by the Run home; omitted by older clients and defaults to 1. */
depth: z.number().int().min(1).optional(),
protocolVersion: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]),
protocolVersion: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4), z.literal(5)]),
worktree: requiredString('Missing remote worktree selector'),
name: OptionalString,
repo: OptionalString,