Add automatic execution routing

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+- Add bounded hybrid automatic routing across the shared runtime, Godot, and
+  Unity integrations: obvious dialogue uses durable one-turn Direct execution,
+  while actionable, structured, long, or ambiguous input retains Agent
+  capability.
+- Preserve explicit path and capability requirements as authoritative, consult
+  an optional classifier only for ambiguous text, and fall back conservatively
+  on classifier failure or timeout.
+- Add route-selected provider and inference profiles with independent per-run
+  override precedence.
+
 ## 0.2.0-alpha.1
 
 - Add bilingual English-first project documentation, contributor governance,

README.md

@@ -46,7 +46,9 @@ an assistant, or a group decision without forcing games into one data model.
 - Durable streaming model/tool loops with retries, route fallback, stale-stream
   fencing, crash recovery, and explicit reconciliation of uncertain writes.
 - Stateless completion plus durable `Direct`, full `Agent`, and fixed
-  `Workflow` execution paths with bounded deterministic routing.
+  `Workflow` paths with bounded hybrid routing: obvious dialogue stays fast,
+  actionable or structured input retains Agent capabilities, and declared
+  requirements always win.
 - Typed observations and structured tool results; natural language is optional.
 - Immutable tool and skill snapshots with bounded progressive disclosure.
 - Strict tool input validation, deterministic conflict scopes, parallel reads,

README.zh-CN.md

@@ -39,7 +39,8 @@ OpenGameAgent 接收类型化游戏上下文，运行流式模型/工具循环
 - 可持久化的流式模型/工具循环，支持重试、路由回退、过期流隔离、崩溃恢复和不确定写入
   的显式对账。
 - 无状态补全，以及可持久化的 `Direct`、完整 `Agent` 和固定 `Workflow` 执行路径；
-  路由有确定且有界的决策过程。
+  采用有界混合自动路由，明确的短对话保持快速，动作或结构化输入保留 Agent 能力，
+  显式能力要求始终优先。
 - 类型化观察和结构化工具结果；自然语言只是可选输入之一。
 - 不可变工具与 Skill 快照，以及有界的渐进式披露。
 - 严格的工具输入校验、确定性冲突域、并行只读、冲突写入串行化和引擎主线程派发。

docs/architecture.md

@@ -59,8 +59,11 @@ The execution surfaces are deliberately distinct. Stateless completion avoids
 session and journal overhead for isolated model calls. Durable direct execution
 keeps context, memory, accounting, and recovery but performs one tool-free model
 turn. Agent execution owns the bounded tool loop. Workflow execution owns a
-fixed recoverable graph around Agent steps. Routing therefore optimizes latency
-without allowing a cheap path to silently omit required capabilities.
+fixed recoverable graph around Agent steps. The default hybrid router classifies
+obvious dialogue locally, escalates actionable, structured, long, or ambiguous
+input, and consults an optional classifier only for ambiguous text. Routing
+therefore optimizes latency without adding a classification call to every
+request or allowing a cheap path to silently omit required capabilities.
 
 Game-semantic coordinates remain engine-neutral. Named clocks, timelines,
 save/state revisions, entity incarnations, observer perspective, spatial scope,

docs/execution-and-extension-reference.md

@@ -20,22 +20,37 @@ tool call. `Direct` is not stateless: it uses the same durable input, context,
 memory, provider resilience, accounting, and recovery contracts as `Agent`, but
 exposes no tools or skills and ends after one provider response.
 
-### Deterministic routing
+### Hybrid automatic routing
 
 `RoutedExecutionRuntime` accepts an `ExecutionRouteRequest`. The default
-`DeterministicExecutionRoutePolicy` selects:
+`AutomaticExecutionRoutePolicy` first applies immutable requirements:
 
 - `Workflow` when `ExecutionRequirements.Workflow` or `ParallelActors` is
   present; multi-actor work must use a workflow that coordinates participants;
 - `Agent` for tools, skills, durable effects, or multiple model turns;
-- `Direct` when none of those capabilities is required.
+- `Direct` remains the minimum path when none of those capabilities is
+  required.
+
+It then combines the bounded structured `Signal` with the latest normalized
+user input. Short scalar dialogue stays on `Direct`; actionable terms,
+structured or multipart input, and long input select `Agent`. Intermediate text
+is ambiguous and conservatively selects `Agent` unless an optional
+`IAutomaticExecutionClassifier` returns a valid, sufficiently confident
+decision. Obvious cases never pay for a classifier call. A workflow hint may
+select `Workflow` only when a workflow payload is present.
+
+The same policy can attach a `DirectModelProfile` or `AgentModelProfile` with
+provider-route and inference defaults. Explicit `Inference` and
+`RoutePreference` values on the durable run win independently, so automatic
+selection never replaces a caller override.
 
 An explicit path is validated against the requirements. A custom
 `IExecutionRoutePolicy` receives an optional bounded structured `Signal`.
-Policy execution is concurrency-limited and timed out. A failed, timed-out, or
-invalid custom policy uses the least-capable deterministic path that satisfies
-the immutable requirements: `Direct` for none, `Agent` for Agent capabilities,
-and `Workflow` for workflow requirements. Configure it with
+Policy execution is concurrency-limited and timed out. The automatic policy
+uses its local conservative result when its optional classifier fails or times
+out. Other failed, timed-out, or invalid custom policies use the least-capable
+deterministic path that satisfies immutable requirements. Configure the built-in
+policy with `WithAutomaticExecutionRouting(...)`, or replace it through
 `WithExecutionRoutePolicy(...)`.
 
 A workflow route additionally requires an `IRoutedWorkflowRuntime`. The

docs/how-to-route-and-supervise-agents.md

@@ -45,10 +45,46 @@ var outcome = await built.Execution.RunAsync(
     }, cancellationToken);
 ```
 
-The default policy chooses `Agent` for this request. For a durable one-turn
-conversation, set `Requirements = ExecutionRequirements.None`; it chooses
-`Direct`. Use `ExplicitPath` only when the caller already knows the path and can
-supply compatible requirements.
+The default policy chooses `Agent` for this request because declared
+requirements always win. When requirements are absent, it also reads the
+bounded `Signal` and latest normalized user input: a short dialogue can use
+`Direct`, while actionable, structured, long, or ambiguous work uses `Agent`.
+Use `ExplicitPath` only when the caller already knows the path and can supply
+compatible requirements.
+
+Configure automatic model tiers once at composition time:
+
+```csharp
+builder.WithAutomaticExecutionRouting(
+    new AutomaticExecutionRoutingOptions
+    {
+        DirectModelProfile = new ExecutionRouteModelProfile
+        {
+            Inference = new ModelInferenceOptions
+            {
+                ReasoningEnabled = false,
+                ReasoningEffort = ModelReasoningEfforts.None
+            },
+            RoutePreference = new ProviderRoutePreference
+            {
+                ProviderIds = new[] { "fast-dialogue" },
+                AllowUnlistedFallback = true
+            }
+        },
+        AgentModelProfile = new ExecutionRouteModelProfile
+        {
+            RoutePreference = new ProviderRoutePreference
+            {
+                ProviderIds = new[] { "capable-agent" },
+                AllowUnlistedFallback = true
+            }
+        }
+    });
+```
+
+Provider IDs are application configuration identities, not model-name guesses.
+The runtime cannot infer which configured route is cheaper or faster. Explicit
+per-run inference or provider preferences override the selected profile.
 
 For a fixed orchestration, compile and register workflows, then attach the
 routed workflow runtime:
@@ -82,10 +118,10 @@ builder.WithExecutionRoutePolicy(
 ```
 
 Do not ask a model merely to choose between `Direct` and `Agent` for every
-request. Prefer deterministic requirements first. A custom policy failure
-falls back from immutable requirements: capability-free work uses `Direct`,
-Agent capabilities use `Agent`, and workflow requirements use `Workflow`.
-Required tools or durability are therefore never skipped.
+request. The built-in router resolves obvious inputs locally and invokes an
+optional classifier only for ambiguous text. Prefer deterministic requirements
+first. Classifier failure or timeout falls back to the conservative local
+result; required tools or durability are never skipped.
 
 ## Run bounded child Agents
 

docs/runtime-capability-model.md

@@ -53,10 +53,12 @@ The runtime exposes four execution shapes:
 | Agent | Yes | Bounded loop | Yes | stateful NPC or world action |
 | Workflow | Yes | Declared | Per stage | deterministic orchestration |
 
-The deterministic router selects the least-capable shape that satisfies the
-request. A simple line of dialogue therefore does not need to enter a complex
-tool loop. Games can supply a bounded custom routing policy; invalid or timed-out
-decisions fall back to the least-capable valid route.
+The automatic router first enforces declared capability requirements, then
+combines a bounded structured signal with the latest user input. Obvious
+dialogue uses Direct without entering a tool loop; actionable, structured,
+long, or ambiguous work retains Agent capability. Games can configure model
+profiles, add a classifier for ambiguous text, or replace the policy. Invalid
+or timed-out custom policies still fall back to the least-capable valid route.
 
 ## Game-native runtime primitives
 

engines/godot/addons/game_agent_runtime/README.md

@@ -88,7 +88,10 @@ GDScript callers may use the Variant-compatible methods on the Autoload:
 ```gdscript
 var request_id := GameAgent.start_agent_run(run_dictionary, observations)
 var routed_id := GameAgent.start_routed_run(
-    route_dictionary,
+    {
+        "operation_kind": "npc-input",
+        "signal": { "input": player_input },
+    },
     run_dictionary,
     observations,
     options,
@@ -102,7 +105,7 @@ var completion_id := GameAgent.start_completion({
 
 Available GDScript operations include starting and resuming durable runs,
 choosing Direct or Agent execution plus inference/provider-route options through
-`start_agent_run_with_options`, deterministic Direct/Agent/Workflow routing,
+`start_agent_run_with_options`, hybrid automatic Direct/Agent/Workflow routing,
 stateless completion, starting and cancelling child Agent runs, starting
 multi-actor batches, resuming or abandoning a participant, and posting cancel,
 interrupt, steer, or follow-up controls. Inputs are converted to strict protocol
@@ -301,9 +304,11 @@ responsible for conflicts in authoritative state.
 
 ## Routing and child Agents
 
-The built backend exposes stateless completion, durable Direct/Agent routing,
-configured workflows, and bounded child supervision from the same in-process
-runtime. Child completion uses the normal run-completed/run-failed signal path;
+The built backend exposes stateless completion, durable hybrid Direct/Agent
+routing, configured workflows, and bounded child supervision from the same
+in-process runtime. Route signals may carry arbitrary bounded `input`; the
+runtime also inspects the latest normalized user message. Child completion uses
+the normal run-completed/run-failed signal path;
 validated root/parent/depth lineage is stored in the child run extensions. The
 game must still stage concurrent results and resolve them against authoritative
 state rather than applying them in network-completion order.

engines/unity/com.gameagent.runtime.unity/Documentation~/index.md

@@ -37,7 +37,8 @@ operation identifiers, and receipts stay in engine-neutral assemblies.
 With a `BuiltUnityAgentRuntimeBackend`, the host exposes:
 
 - `RunAsync` for normal durable Agent work;
-- `RunRoutedAsync` for durable Direct/Agent/Workflow selection;
+- `RunRoutedAsync` for bounded hybrid automatic Direct/Agent/Workflow
+  selection from structured signals and the latest normalized user input;
 - `CompleteAsync` for stateless single-provider-turn work;
 - `RunChildAsync` and `CancelChildren` for bounded delegation.
 - optional `SubmitGenerationAsync`, `RefreshGenerationAsync`,

engines/unity/com.gameagent.runtime.unity/README.md

@@ -130,8 +130,11 @@ integration checklist.
 
 The built runtime backend also exposes `RunRoutedAsync`, `CompleteAsync`,
 `RunChildAsync`, and `CancelChildren` through `UnityAgentRuntimeHost`. These use
-the shared durable routing, per-operation inference/provider selection, and
-bounded child-lineage contracts rather than Unity-specific Agent behavior.
+the shared hybrid automatic routing, per-operation inference/provider
+selection, and bounded child-lineage contracts rather than Unity-specific
+Agent behavior. Obvious dialogue stays on the one-turn Direct path; actionable
+or structured input retains Agent capabilities, and explicit requirements or
+per-run model choices always win.
 Use the `RunChildAsync(AgentRun, ...)` overload when the parent was restored
 from durable storage or delegation continues after supervisor cache eviction;
 the string overload is intended for roots or currently supervised parents.