AGENT_ENGINE selects which agent loop runs a turn (default: langgraph)

[DavidNic11]

Third PR in the sequence from #194 (ADR 0036), following #196. Adds AGENT_ENGINE=langgraph|temporal.

Defaults to langgraph, so this changes no behaviour. Enabling the engine is always an explicit act.

The claim to check first

AgentGraphLike (invoke + stream) has been the Server's dependency all along, so this is a second implementation of an existing interface, not a refactor.

The evidence: 581 existing tests pass unchanged, and the only files touched under apps/ are config.ts (+3 values), index.ts (+1 branch picking which engine to construct), and the new engine/ directory. graph.ts is untouched.

Everything outside the loop is shared either way — the OpenAI facade, /invoke, identity resolution, RBAC, the credential store, the authorization pre-flight (0030/0031), both launchers, session pages. Only the loop moves. That split is the reviewability argument: the claim is about the loop, and the layers above it are where the last six weeks of work landed.

The substantive review is one file

apps/agent-orchestrator/src/engine/temporal-engine.ts. Three decisions in it, each documented at the top of the file:

It's an HTTP client, not an embedded Temporal client. The obvious implementation embeds @temporalio/client and does update-with-start here. Rejected in ascending order of importance: it's a substantial dependency for one call; the engine's Go gateway already implements this exact accept/poll contract, so a TypeScript reimplementation gives one protocol two definitions; and it would put Temporal credentials in the pod that already holds the Kubernetes identity. docs/orchestrator.md reasons explicitly about that pod's blast radius — keeping it unchanged is worth an extra in-cluster hop.

The sender login travels signed. It selects the caller's principal and therefore which stored credentials a run receives, so an internal hop is exactly as unsuited to trusting it unsigned as an external one. Reuses x-gateway-user-assertion (0030 §6) — the engine's Go verifier is byte-compatible with mintSenderAssertion, pinned on that side by vectors generated from this TypeScript, and round-tripped in a test here.

A route target is named, not re-derived. This process owns the IntegrationRoute registry and has already matched it, so the engine's /invoke gained optional forcedSkillId/forcedAgentId. Re-matching there would put routing policy in two places — what ADR 0024 rejected when it declined to let integration-gateway launch AgentRuns directly. The engine still re-resolves whatever is named under the caller's own roles.

Two real differences, recorded not papered over

A streaming caller on this engine gets its answer but no per-node narration. Those lines describe LangGraph node transitions, which don't exist there.

persistSession writes nothing for this engine, because the workflow holds that state — which is the entire point. It merges rather than replaces, so an all-undefined outcome is a no-op rather than a clobber. That's also why the flag is process-wide rather than per-request: the two engines keep conversation state in different places, so alternating mid-conversation would lose whichever one it left.

A turn that outlives the poll budget is reported as a resumable pause, not a failure. The record is the workflow rather than this process's memory, so the answer stays collectable — the shape ADR 0033 settled on, now true by construction.

Tests

9 new tests for the engine client, covering each decision above plus the failure modes: a failed turn reported as an error rather than an empty result, pending caller tool calls surviving the hop (0035's second terminal shape), the assertion refused when unsigned, and an unreachable engine throwing rather than silently degrading.

Locally: typecheck clean, 581 + 9 tests pass, engine module green.

🤖 Generated with Claude Code

https://claude.ai/code/session_018Uj1SJ41DJJ8woZM7fd3DQ

[imaustink]

🚢