refactor(agent-runtime): own prompt loop facts

docs/architecture/agent-runtime-services-design.md

@@ -1,14 +1,11 @@
 # Agent Runtime SDK 与 Runtime Services 设计
 
 本文是 [`core-decomposition.md`](core-decomposition.md) 的开发设计文档，描述目标模块、
-接口、crate 内部结构和迁移保护。`bitfun-runtime-services` 已建立 typed service bundle、
-builder、provider registry、capability availability 和 fake provider 基础；`bitfun-agent-runtime`
-已创建并承接可独立构建的 scheduler/background delivery、thread goal runtime、
-subagent visibility / availability、round-boundary yield / injection state
-和 turn-outcome queue policy 纯决策；`bitfun-harness`
-已创建并承接 workflow descriptor、legacy route plan 和 provider registry contract。
-未迁移的 session manager、prompt loop、concrete agent registry loading、concrete scheduler lifecycle 和
-concrete workflow execution 不得被描述为已完成。
+接口、crate 内部结构和迁移保护。本文不作为 PR 进度记录；已完成项、待执行项、PR 范围和
+issue 状态由 [`core-decomposition-plan.md`](../plans/core-decomposition-plan.md)、
+[`core-decomposition-completed.md`](../plans/core-decomposition-completed.md) 和跟踪 issue 维护。
+
+除非发现目标分层、接口归属、行为边界或关键风险判断需要修正，后续 PR 不应修改本文。
 
 ## 1. 设计目标与边界
 
@@ -25,11 +22,11 @@ concrete workflow execution 不得被描述为已完成。
 bitfun-core-types
 bitfun-events
 bitfun-runtime-ports
-bitfun-runtime-services      # PR1 基础壳层
+bitfun-runtime-services      # typed service bundle / capability availability
 bitfun-agent-tools
 tool-runtime
-bitfun-agent-runtime         # 已创建，承接 scheduler/background、thread goal、registry visibility 与 round-boundary 决策
-bitfun-harness               # 已创建，当前承接 workflow descriptor / registry contract
+bitfun-agent-runtime         # agent kernel contracts and portable runtime decisions
+bitfun-harness               # workflow descriptor / provider / registry contracts
 bitfun-services-core
 bitfun-services-integrations
 bitfun-product-domains
@@ -94,11 +91,9 @@ bitfun-runtime-services
 目标 crate 创建或继续扩展准入：
 
 - 只有当 owner 边界、旧路径兼容、focused tests、依赖收益和 boundary check 都能同时落地时，才创建新的目标 crate。
-- `bitfun-runtime-services` 已按该准入建立基础壳层；继续扩展时仍必须保持 typed builder、本地 service、remote service 和 fake provider 三类注入路径可测试。
-- `bitfun-agent-runtime` 已通过 scheduler/background delivery、thread goal runtime、subagent visibility / availability
-  和 round-boundary 纯决策满足创建准入；继续扩展时仍必须保持旧路径 facade、focused tests 和 boundary check。
-- `bitfun-harness` 已按 Deep Review、DeepResearch、MiniApp 三个 legacy-facade provider
-  满足创建准入；继续扩展时仍必须保持 descriptor/registry、旧路径兼容、focused tests 和 boundary check。
+- `bitfun-runtime-services` 的扩展必须保持 typed builder、本地 service、remote service 和 fake provider 三类注入路径可测试。
+- `bitfun-agent-runtime` 的扩展必须保持旧路径 facade、focused tests 和 boundary check，且不得吸收 concrete service、product surface 或平台实现。
+- `bitfun-harness` 的扩展必须保持 descriptor / registry、旧路径兼容、focused tests 和 boundary check，且不得把 provider 注册误写成 concrete workflow execution。
 - 若目标 crate 只能承接单个 helper 或只能通过 `bitfun-core` 才能测试，继续留在迁移期 facade，不提前拆 crate。
 
 ## 2. 稳定接口与运行时服务
@@ -163,7 +158,7 @@ pub trait WorkspacePort: Send + Sync {
 
 ### 2.2 Runtime Services
 
-当前 crate：`bitfun-runtime-services`。
+目标 owner crate：`bitfun-runtime-services`。
 
 职责：
 
@@ -241,42 +236,31 @@ Remote ports 的边界：
 
 ### 3.1 Agent Runtime SDK
 
-当前 crate：`bitfun-agent-runtime`。
-
-当前已承接范围：
-
-- background delivery 状态决策：Processing 注入当前运行 turn；Missing / Idle / Error 提交 agent-session follow-up turn。
-- persisted thread goal 的 portable DTO、status、continuation plan 和 tool response contract 已在
-  `bitfun-runtime-ports`。
-- thread goal runtime 决策：turn token / wall-clock accounting、goal mutation、
-  continuation / budget-limit / objective-updated plan、tool response assembly
-  和 usage-limit / retry / skip-accounting policy。
-- subagent registry 决策：query scope、visibility policy、availability reason、
-  builtin / project / user override layering 和 frontend-facing availability facts。
-- scheduler round-boundary 决策：yield flag、round injection buffer、turn outcome status /
-  reply text / queue action。
+目标 owner crate：`bitfun-agent-runtime`。
 
-仍留在 `bitfun-core` 的范围：
-
-- concrete scheduler 生命周期、session manager、turn id 生成、submit 执行、prompt loop、
-  concrete agent definition loading、custom subagent file IO / config adapter、
-  thread goal metadata store、token subscriber、scheduler delivery adapter、
-  goal `Tool` handler、event delivery 和 post-turn hook。
-
-职责：
+目标职责：
 
 - session 生命周期。
 - dialog turn / model round 生命周期。
 - scheduler / queue / cancellation。
 - prompt loop 和 context assembly。
 - prompt cache 协调。
-- subagent registry 查询和 delegation policy。
+- agent definition registry、subagent registry 查询和 delegation policy。
 - fork context seeding。
 - tool call 调度。
 - permission 协调。
 - runtime events。
 - post-turn processor。
 
+迁移期约束：
+
+- `bitfun-agent-runtime` 只能依赖稳定契约、Tool Runtime、Runtime Services 接口和注入的 provider。
+- concrete scheduler 生命周期、session metadata store、token subscriber、event delivery、product `Tool`
+  handler、concrete prompt assembly、workspace / remote / config IO、custom subagent file IO 和平台 adapter
+  在行为等价未证明前不得下沉到 runtime kernel。
+- prompt、event、thread goal、scheduler 或 subagent 的纯事实可以先迁移，但每次迁移必须删除旧 owner
+  实现主体，保留旧路径兼容，并补 focused contract test 与 boundary check。
+
 建议内部模块：
 
 ```text
@@ -443,12 +427,20 @@ pub struct ToolExecutionContext {
 }
 ```
 
-当前已收敛范围：
+目标职责：
+
+- provider-neutral manifest、catalog、permission gate、execution admission、tool hook、execution result
+  presentation 和 result artifact policy。
+- `GetToolSpec` catalog、detail、assistant result 和 collapsed-tool unlock observation。
+- workspace service、path policy、runtime artifact reference、remote path containment 和 tool context facts 的
+  稳定 contract。
+
+迁移期约束：
 
-- deterministic execution admission gate、manifest / catalog / snapshot facade 和 `GetToolSpecTool` product adapter 已有独立 owner。
-- workspace file/shell service contract 已归入 `bitfun-runtime-ports`；core 保留旧路径 re-export 和 local / remote concrete adapter。
-  迁移期该 contract 保留既有 `anyhow::Result` 和 `CancellationToken`，不把错误分类或取消语义变更混入 owner 迁移。
-- collapsed unlock 的 `GetToolSpec` observation adapter 已归入 product runtime owner，execution engine 只消费已归一化的 unlock list。
+- core 可以保留旧路径 facade、concrete tool adapter、state update、registry lookup、confirmation、actual
+  execution 和 filesystem persistence，直到对应 owner 迁移有等价测试保护。
+- workspace file/shell contract 保留既有错误与取消语义；不得把错误分类、取消语义或产品 tool exposure
+  变更混入 owner 迁移。
 
 设计约束：
 
@@ -473,13 +465,13 @@ pub struct ToolExecutionContext {
 
 ### 3.3 Harness Layer
 
-当前 crate：`bitfun-harness`。
+目标 owner crate：`bitfun-harness`。
 
 职责：
 
-- 把 SDD、DeepReview、DeepResearch、MiniApp、function-agent 等工作流从 runtime kernel
-  中分离。当前只承接 workflow descriptor、route plan 和 provider registry。
-- 定义 workflow plan、step、policy、artifact、review gate、post-processor。具体执行在迁移前继续留在旧路径。
+- 把 SDD、DeepReview、DeepResearch、MiniApp、function-agent 等工作流从 runtime kernel 中分离。
+- 定义 workflow descriptor、route plan、provider registry、workflow plan、step、policy、artifact、
+  review gate 和 post-processor。
 - 通过 Agent Runtime SDK、Tool Runtime 和 service ports 编排。
 
 建议内部模块：
@@ -534,7 +526,8 @@ pub struct HarnessExecutionContext {
 - harness 不直接访问 concrete filesystem / Git / terminal。
 - 产品命令只映射到 harness capability，不把命令展示逻辑下沉。
 - 新 harness 通过 provider 注册，不改 Agent Runtime SDK 内核。
-- PR4 阶段的 legacy-facade provider 只生成 route plan，不执行 workflow；执行迁移必须在后续 PR 单独证明行为等价。
+- descriptor-only / legacy-facade provider 只能表达 route plan；不得被描述为 concrete workflow execution
+  已迁移。执行迁移必须单独证明行为等价。
 
 ## 4. 产品组装与扩展
 
@@ -829,7 +822,7 @@ pub trait BeforeToolExecution: Send + Sync {
 - hook 不得获取未声明的具体 service。
 - 修改 prompt / manifest / output 的 hook 必须有 snapshot 测试。
 
-## 5. 质量保护与完成定义
+## 5. 质量保护与目标态判定
 
 ### 5.1 鲁棒性设计
 
@@ -906,7 +899,7 @@ Product 测试：
 - MCP dynamic tool catalog。
 - MiniApp 与 review workflow。
 
-### 5.4 完成定义
+### 5.4 目标态判定口径
 
 - `bitfun-agent-runtime` 能在不依赖 `bitfun-core` 的情况下构建 runtime kernel。
 - `bitfun-runtime-services` 提供 typed service injection，并由 boundary check 保护。

docs/architecture/core-decomposition.md

@@ -5,6 +5,9 @@
 [`core-decomposition-plan.md`](../plans/core-decomposition-plan.md)。详细接口、crate 内部模块和
 测试设计见 [`agent-runtime-services-design.md`](agent-runtime-services-design.md)。
 
+本文不作为 PR 进度记录。除目标分层、接口归属、行为边界或关键风险判断发生变化外，后续 PR
+不应修改本文；完成状态由 plan、completed 归档和跟踪 issue 维护。
+
 ## 1. 背景与目标
 
 BitFun 当前已经从 `bitfun-core` 中抽出了若干 owner crate，但 `bitfun-core` 仍承担兼容 facade、
@@ -241,32 +244,29 @@ Computer Use 等能力的组合边界。它负责定义一个产品能力需要
 
 工作流编排层（Harness Layer）承载多步骤工作流和策略编排，例如 SDD、Deep Review、DeepResearch、MiniApp 生成或更新流程。
 它可以调用 Agent Runtime SDK、Tool Runtime 和 Runtime Services，但不拥有 session manager 内部状态、
-具体 filesystem/Git/terminal manager 或产品 UI。`bitfun-harness` 已承接 workflow descriptor、legacy route plan
-和 provider registry contract；当前 Deep Review、DeepResearch、MiniApp 仍通过 legacy-facade provider
-指向既有 core/product 执行路径，concrete workflow execution 尚未外移。
+具体 filesystem/Git/terminal manager 或产品 UI。`bitfun-harness` 目标上承接 workflow descriptor、route
+plan 和 provider registry contract；descriptor-only / legacy-facade provider 只能表达 route，不代表
+concrete workflow execution 已迁移。
 
 ### 7.5 Agent 运行时 SDK（Agent Runtime SDK）
 
 Agent 运行时 SDK（Agent Runtime SDK）是可嵌入的 agent kernel，负责 session、turn、scheduler、prompt loop、subagent、
 background task、permission coordination 和 runtime events。它只依赖稳定契约、tool runtime 和注入的
-service ports，不感知 Desktop、CLI、Remote、ACP、Tauri 或 Web UI。当前主体仍在 `bitfun-core`，
-但 `bitfun-agent-runtime` 已承接可独立构建的 scheduler/background delivery 和 thread goal
-runtime 纯决策，并承接 subagent visibility / availability、round-boundary yield / injection state
-和 turn-outcome queue policy。concrete scheduler lifecycle、session manager、prompt loop、
-concrete agent definition loading、custom subagent file IO / config adapter、thread goal metadata store、
-token subscriber、scheduler delivery adapter、goal `Tool` handler、event delivery 和 post-turn hook
-仍由 core 执行。
+service ports，不感知 Desktop、CLI、Remote、ACP、Tauri 或 Web UI。`bitfun-agent-runtime` 目标上承接
+agent kernel 的稳定事实、纯决策和运行时 contract；concrete scheduler lifecycle、session manager、
+concrete prompt assembly、concrete agent definition loading、custom subagent file IO / config adapter、
+metadata store、token subscriber、scheduler delivery adapter、product `Tool` handler、event delivery 和
+post-turn hook 在行为等价未证明前不得下沉。
 
 ### 7.6 工具运行时（Tool Runtime）
 
 工具运行时（Tool Runtime）负责工具 manifest、catalog、permission gate、execution pipeline、tool hook 和结果归一化。
 它只消费 `ToolExecutionServices` 这类窄 service 视图，不直接创建 filesystem、Git、terminal、MCP 等具体实现。
 当前相关 crate 包括 `tool-runtime`、`bitfun-agent-tools`、`bitfun-tool-packs` 以及 `bitfun-core`
-中的 tool materialization 代码。deterministic execution admission gate 已由 `bitfun-agent-tools` 承接；
-`GetToolSpecTool` concrete adapter、manifest/catalog facade 和 snapshot wrapper 已收敛到 `bitfun-core` 的
-product runtime owner；collapsed unlock 的 GetToolSpec observation adapter 也由 product runtime owner 承接。
-workspace service contract 已归入 `bitfun-runtime-ports`，core 只保留旧路径 re-export 与 local / remote concrete
-adapter。`bitfun-core` 的 pipeline 仍负责状态更新、registry lookup、input validation、confirmation、实际执行和 hook。
+中的 tool materialization 代码。Tool Runtime 目标上承接 provider-neutral manifest、catalog、permission
+gate、execution admission、result presentation、artifact policy 和 `GetToolSpec` catalog / detail contract。
+core 可以保留 concrete tool adapter、state update、registry lookup、input validation、confirmation、
+actual execution、hook 和旧路径 facade，直到对应迁移有等价测试保护。
 
 ### 7.7 运行时服务层（Runtime Services）
 
@@ -275,8 +275,8 @@ filesystem、workspace、session store、Git、terminal、network、MCP catalog
 等端口，不执行产品命令，
 不作为无类型 service locator，也不创建平台实现。当前相关 crate 包括 `bitfun-runtime-ports`、
 `bitfun-runtime-services`、`bitfun-services-core`、`bitfun-services-integrations` 和 `bitfun-core` 中的 service 接线代码。
-其中 workspace file/shell service contract 已归入 `bitfun-runtime-ports`；`bitfun-core::agentic::workspace` 仅保留
-旧路径 re-export 和 local / remote concrete adapter。
+workspace file/shell、remote connection / projection、session store、Git、terminal、network 和 MCP catalog
+等接口应以 stable port 表达；core 可在迁移期保留旧路径 facade 和 concrete adapter。
 
 ### 7.8 具体实现层（Concrete Integrations）
 
@@ -295,8 +295,8 @@ SSH、relay、本地隧道、远端 OS 差异和认证方式属于具体 Remote
 稳定契约层提供跨层共享的数据结构和接口语言，包括 DTO、event、permission facts、artifact refs、identity
 和 port traits。它只描述事实和能力，不包含 IO、网络、进程、UI、runtime manager 或产品策略。当前相关
 crate 包括 `bitfun-core-types`、`bitfun-events` 和 `bitfun-runtime-ports`。
-当前 remote workspace facts、remote session metadata、remote workspace file projection DTO 和 remote workspace/projection
-host trait 已归入 `bitfun-runtime-ports`，`bitfun-services-integrations::remote_connect` 保留旧路径 re-export。
+remote workspace facts、remote session metadata、remote workspace file projection DTO 和 remote workspace/projection
+host trait 应归入稳定契约；integration crate 可保留旧路径 re-export 以维持兼容。
 
 ## 8. 接口与实现关系
 
@@ -338,7 +338,7 @@ flowchart TB
 | 注册器 / 组装点 | 所属目标层级 | 目标或迁移期模块 | 注册内容 |
 |---|---|---|---|
 | `ProductAssembler` / `ProductAssemblyPlan` | 产品组装层（Product Assembly） | 迁移期在 `bitfun-core` facade 或产品入口；目标可收敛为 assembly owner | `DeliveryProfile`、`CapabilitySet`、feature group、provider 选择 |
-| `RuntimeServicesBuilder` | 运行时服务层（Runtime Services） | `bitfun-runtime-services` PR1 基础壳层；迁移期连接 `bitfun-runtime-ports`、`bitfun-services-*` 和 `bitfun-core` service wiring | filesystem、workspace、session store、Git、terminal、network、MCP catalog、remote connection / workspace / projection port |
+| `RuntimeServicesBuilder` | 运行时服务层（Runtime Services） | `bitfun-runtime-services`；连接 `bitfun-runtime-ports`、`bitfun-services-*` 和迁移期 service wiring | filesystem、workspace、session store、Git、terminal、network、MCP catalog、remote connection / workspace / projection port |
 | `ToolRuntimeBuilder` | 工具运行时（Tool Runtime） | `tool-runtime`、`bitfun-agent-tools`、`bitfun-tool-packs` | tool provider、tool pack、manifest、permission gate、tool hook |
 | `HarnessRegistryBuilder` | 工作流编排层（Harness Layer） | `bitfun-harness`；迁移期由 `bitfun-core::agentic::harness` 注册 legacy-facade provider | SDD、Deep Review、DeepResearch、MiniApp 等 harness provider |
 | `AgentDefinitionRegistry` | Agent 运行时 SDK（Agent Runtime SDK） | 目标 `bitfun-agent-runtime`；迁移期在 `bitfun-core` agent definition 代码中 | agent、subagent、prompt module、skill definition |
@@ -367,7 +367,7 @@ flowchart TB
 | core 拆分后仍隐式绑定 Tauri | Tauri 只允许在 Desktop provider / adapter；向下层传递 typed port、DTO、event fact 和 capability availability |
 | 不同产品形态能力矩阵漂移 | Product Assembly 维护 capability matrix；减少或替换能力时补产品入口验证和 unsupported 行为测试 |
 | Tool、MCP、ACP 的 manifest、permission 或事件语义迁移后不等价 | 保留旧路径兼容 facade，增加 manifest snapshot、permission 决策和事件映射等价测试 |
-| Harness provider 只做注册但被误认为已经迁移执行语义 | PR4 阶段 provider 只生成 legacy route plan，execute 明确返回 unsupported；后续执行迁移必须单独证明行为等价 |
+| Harness provider 只做注册但被误认为已经迁移执行语义 | descriptor-only / legacy-facade provider 只能生成 route plan；执行迁移必须单独证明行为等价 |
 | `bitfun-core` 只是改名为新的巨型 runtime crate | 新 owner crate 必须有单一职责和最小依赖；产品能力、harness、service 实现不得继续堆入 agent kernel |
 | 目标 crate 先行创建但没有真实 owner | 只有 owner 边界、旧路径兼容、focused tests、依赖收益和 boundary check 同时成立时才创建 crate；否则继续留在 facade |