Fix code review issues in OrchestratorMixin

- Move _routeToAgent action from static schema to merged() hook so it
  is only registered when strategy === 'llm-router'
- Add agentName validation in _routeToAgent handler: throws if agent
  is not in discoverAgents() list
- Add description field to _routeToAgent action definition
- Add integration test for unknown agent name rejection

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: icebob-ai

src/orchestrator.mixin.ts

@@ -19,6 +19,36 @@ export default function OrchestratorMixin(_mixinOpts?: OrchestratorMixinOptions)
 	_mixinOpts = _.defaultsDeep(_mixinOpts, {});
 
 	const schema = {
+		merged(this: ServiceInstance, schema: Record<string, unknown>) {
+			const settings = schema.settings as Record<string, unknown> | undefined;
+			const agent = settings?.agent as Record<string, unknown> | undefined;
+			if (agent?.strategy === "llm-router") {
+				const actions = (schema.actions || {}) as Record<string, unknown>;
+				actions._routeToAgent = {
+					description: "Route a task to a discovered agent",
+					visibility: "protected",
+					params: {
+						agentName: { type: "string" },
+						task: { type: "string" }
+					},
+					async handler(this: ServiceInstance, ctx: ServiceInstance) {
+						const agents = this.discoverAgents();
+						if (
+							!agents.some(
+								(a: DiscoveredAgent) => a.name === ctx.params.agentName
+							)
+						) {
+							throw new Error(
+								`Agent not found: ${ctx.params.agentName}`
+							);
+						}
+						return this.delegateTo(ctx.params.agentName, ctx.params.task);
+					}
+				};
+				schema.actions = actions;
+			}
+		},
+
 		events: {
 			"$services.changed"(this: ServiceInstance) {
 				if (this.settings.agent?.strategy === "llm-router") {
@@ -126,19 +156,6 @@ export default function OrchestratorMixin(_mixinOpts?: OrchestratorMixinOptions)
 			}
 		},
 
-		actions: {
-			_routeToAgent: {
-				visibility: "private",
-				params: {
-					agentName: { type: "string" },
-					task: { type: "string" }
-				},
-				async handler(this: ServiceInstance, ctx: ServiceInstance) {
-					return this.delegateTo(ctx.params.agentName, ctx.params.task);
-				}
-			}
-		},
-
 		async started(this: ServiceInstance) {
 			if (this.settings.agent?.strategy === "llm-router") {
 				this._updateRouteToAgent();

test/integration/orchestrator.test.ts

@@ -389,6 +389,14 @@ describe("OrchestratorMixin E2E", () => {
 
 		expect(routeTool).toBeUndefined();
 
+		// Verify the _routeToAgent action is NOT registered on the service
+		await expect(
+			broker.call("orchestrator-5._routeToAgent", {
+				agentName: "test",
+				task: "test"
+			})
+		).rejects.toThrow();
+
 		await broker.destroyService(orchSvc);
 		await broker.destroyService(llmSvc);
 	});
@@ -464,4 +472,92 @@ describe("OrchestratorMixin E2E", () => {
 		await broker.destroyService(orchSvc);
 		await broker.destroyService(llmSvc);
 	});
+
+	it("should reject _routeToAgent call with unknown agent name", async () => {
+		const adapter = new FakeAdapter({
+			responses: [
+				{
+					content: null,
+					tool_calls: [
+						{
+							id: "call_bad_agent",
+							type: "function" as const,
+							function: {
+								name: "_routeToAgent",
+								arguments: JSON.stringify({
+									agentName: "non-existent-agent",
+									task: "Do something"
+								})
+							}
+						}
+					]
+				},
+				"Sorry, I could not find that agent."
+			]
+		});
+
+		const llmSvc = broker.createService({
+			name: "llm.orch7",
+			mixins: [LLMService()],
+			settings: { adapter }
+		});
+
+		const realAgent = broker.createService({
+			name: "real-agent",
+			mixins: [AgentMixin()],
+			settings: {
+				agent: {
+					llm: "llm.orch7",
+					description: "A real agent"
+				}
+			},
+			actions: {
+				doWork: {
+					description: "Do some work",
+					params: {},
+					async handler() {
+						return "done";
+					}
+				}
+			}
+		});
+
+		const orchSvc = broker.createService({
+			name: "orchestrator-7",
+			mixins: [OrchestratorMixin(), AgentMixin()],
+			settings: {
+				agent: {
+					llm: "llm.orch7",
+					description: "Validating orchestrator",
+					strategy: "llm-router"
+				}
+			},
+			actions: {}
+		});
+
+		await broker.waitForServices(["llm.orch7", "real-agent", "orchestrator-7"]);
+
+		// Trigger discovery
+		broker.broadcastLocal("$services.changed");
+
+		const result = await broker.call("orchestrator-7.run", {
+			task: "Route to unknown agent"
+		});
+
+		expect(result).toBe("Sorry, I could not find that agent.");
+
+		// Verify error was sent back as tool result
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const internalAdapter = (llmSvc as any)._adapter as FakeAdapter;
+		const secondCall = internalAdapter.calls[1];
+		const toolMsg = (secondCall.messages as { role: string; content: string }[]).find(
+			m => m.role === "tool"
+		);
+		expect(toolMsg).toBeDefined();
+		expect(toolMsg!.content).toContain("Agent not found: non-existent-agent");
+
+		await broker.destroyService(orchSvc);
+		await broker.destroyService(realAgent);
+		await broker.destroyService(llmSvc);
+	});
 });