Add bounded engine-thread action queue

CHANGELOG.md

@@ -2,7 +2,9 @@
 
 ## Unreleased
 
-No changes yet.
+- Add `QueuedGameActionHandler`, a bounded engine-thread action handoff with FIFO pumping,
+  queued cancellation, active-action settlement, shutdown cleanup, and main-thread recovery over
+  the existing durable action journal and receipt protocol.
 
 ## 0.3.0-alpha.2
 

README.md

@@ -123,7 +123,7 @@ Read [Architecture](docs/architecture.md) for the ownership and failure boundari
 | Image input | PNG/JPEG/WebP/GIF admission, immutable content-addressed storage, reference-only transcripts, capability preflight, tool-result images, and authorized server retrieval |
 | Extension API | Immutable builder; prompt/context/tool/skill/route/workflow/hook/provider/service registration; typed lifecycle events and channels; namespaced persistent state |
 | Official extensions | Tool policy and search, structured player questions/recommended replies, goals, host-verified ordered task plans with durable pause/resume, memory, artifacts, knowledge, delegation, tracing, and durable parallel workflow graphs |
-| World primitives | Durable actions, resumable workflows, memories, skills, signals, game-time schedules, actor mailboxes with batch read-only pending status |
+| World primitives | Durable actions, bounded engine-thread action handoff, resumable workflows, memories, skills, signals, game-time schedules, actor mailboxes with batch read-only pending status |
 | Models and auth | Bundled capability/context/reasoning/cost directory, dynamic refresh, API-key/environment/stored/OAuth/local auth, developer-hosted short-lived credential gateway |
 | External tools | Lazy on-demand search/describe/call by default; explicit direct exposure for small trusted catalogs |
 | Portable plugins | [Agent Plugins 1.0.0](docs/agent-plugins.md) `plugin.json`, immediate-child `SKILL.md` discovery, MCP stdio/Streamable HTTP, client namespaces, containment, and component-level failure isolation |

README.zh-CN.md

@@ -121,7 +121,7 @@ GameAgentRuntime
 | 图片输入 | PNG/JPEG/WebP/GIF 准入、不可变内容寻址存储、仅引用会话、模型能力预检、工具结果图片与授权服务端读取 |
 | 扩展 API | 不可变构建器；提示词/上下文/工具/Skills/路由/Workflow/Hooks/提供方/服务注册；类型化生命周期事件与通道；命名空间持久状态 |
 | 官方扩展 | 工具策略与搜索、玩家结构化提问/推荐回复、目标、支持持久暂停/恢复且由宿主校验证据的有序任务清单、记忆、产物、外部知识、委派、追踪和可持久并行工作流图 |
-| 世界原语 | 可恢复动作、可续跑 Workflow、记忆、Skills、信号、游戏时间调度、支持批量只读待处理状态的角色邮箱 |
+| 世界原语 | 可恢复动作、有界引擎线程动作交接、可续跑 Workflow、记忆、Skills、信号、游戏时间调度、支持批量只读待处理状态的角色邮箱 |
 | 模型与认证 | 内置模型能力/上下文/推理级别/成本目录、动态刷新、API Key/环境/存储/OAuth/本地认证、开发者托管短期凭证网关 |
 | 外部工具 | 默认按需搜索/描述/调用；小型可信目录可显式选择原生直连暴露 |
 | 可移植插件 | [Agent Plugins 1.0.0](docs/agent-plugins.md) `plugin.json`、直接子目录 `SKILL.md` 发现、MCP stdio/Streamable HTTP、客户端命名空间、路径限制与组件级故障隔离 |

docs/features.md

@@ -64,7 +64,7 @@ This page maps product needs to the smallest reusable OpenGameAgent primitive.
 | --- | --- |
 | Mutate game state through a typed tool | `GameActionTool` |
 | Avoid repeating uncertain writes | `DurableGameActionDispatcher`, `IGameActionJournal` |
-| Execute on engine main thread | implement `IGameActionHandler` by queueing into the engine, then await the receipt |
+| Execute on an engine-owned main thread | wrap the authoritative `IGameActionHandler` in `QueuedGameActionHandler`, then call `Pump` from the engine thread |
 | Store long-term NPC facts/events | `IGameMemoryStore`, `GameMemory` |
 | Apply custom semantic ranking | `IGameMemoryRanker`, `RankedGameMemoryStore` |
 | Add local or remote vector embeddings and hybrid recall | `IMemoryEmbeddingProvider`, `VectorMemoryStore` |

docs/getting-started.md

@@ -153,6 +153,29 @@ ValueTask<IReadOnlyList<AgentTool>> Tools(GameInput input, CancellationToken _)
 
 `IGameActionHandler.ExecuteAsync` must recheck visibility, permission, resources, expected revision, and all game rules. Return `Rejected` for a legal request that cannot commit. Implement `RecoverAsync` using the game's operation ledger or transaction log.
 
+When the model loop runs off the engine thread, wrap that authoritative handler in
+`QueuedGameActionHandler` and pump it from the engine thread. The durable dispatcher remains the
+only action journal; the queue is a bounded, process-local handoff:
+
+```csharp
+var engineActions = new QueuedGameActionHandler(
+    new AuthoritativeGameActionHandler(world),
+    maximumPendingActions: 256,
+    maximumActiveActions: 16);
+var dispatcher = new DurableGameActionDispatcher(actionJournal, engineActions);
+
+// Unity Update, Godot _Process, or the equivalent host-owned main-thread callback.
+engineActions.Pump(maximumWorkItems: 16);
+```
+
+The first `Pump` call binds the instance to that managed thread. Cancellation removes an action
+only while it is still queued. Once the host starts an action, caller timeout no longer cancels the
+mutation blindly; its receipt is allowed to settle. `Stop` rejects new work and faults queued work,
+while `DisposeAsync` additionally waits for already-started work. The wrapped authoritative handler
+must validate `GenerationId` against the currently loaded save/world generation because only the
+game knows which generation is active. Pending durable journal entries are recovered through the
+same pump after restart.
+
 ## Select routes
 
 The default route is intentionally simple: