xiaoxixi
ac201a3949
- AgentCatalog/definitions with strict Markdown frontmatter, delegation graph, fail-closed tool scoping, and signal contracts - structured cancellation (AgentError::Cancelled/TimedOut) across provider streams, tool batches, and sleep; /stop drives the same terminal state - schema v6 run/group/inbox persistence with execution-ID conditional transitions and completion-slot reservations - ExecutionGate separating run quota from provider/tool step permits - background completion inbox with hidden-trigger continuation turns, fairness scheduling, lease release, dead-lettering, and activation recovery - typed TurnMailbox with two-phase steer admission and atomic consumption at turn commit; /stop releases admitted steer events back to pending - emit_signal tool with contract-enforced rate/dedupe/severity/size limits - WS run/event projection (GetAgentRuns, AgentRunUpdated, AgentEventUpdated), /api/agent-runs* management endpoints, /api/tasks union, WebUI run tree and signal cards - ChannelContext.durable_private persisted for continuation delivery reuse Version 1.7.0
1114 lines
60 KiB
Markdown
1114 lines
60 KiB
Markdown
# PicoBot 子 Agent 编排实施细节与可实施性审查
|
||
|
||
> 状态：实施基线（2026-08）。
|
||
>
|
||
> 本文以 [`SUB_AGENT_ORCHESTRATION_DESIGN.md`](SUB_AGENT_ORCHESTRATION_DESIGN.md) 为产品与架构规范，以 [`SUB_AGENT_ORCHESTRATION_REVIEW.md`](SUB_AGENT_ORCHESTRATION_REVIEW.md) 和 [`SUB_AGENT_ORCHESTRATION_REVIEW_RESPONSE.md`](SUB_AGENT_ORCHESTRATION_REVIEW_RESPONSE.md) 为评审记录，并逐项对照当前代码给出可以直接拆分为开发任务的实现方案。
|
||
>
|
||
> 本文不是“代码已经实现”的声明。实现完成前，运行时事实仍以当前代码、测试和 [`ARCHITECTURE.md`](ARCHITECTURE.md) 为准。
|
||
|
||
> 实施进度（2026-08）：Phase 1 已落地具名 Definition/Catalog、不同 Provider profile、工具/Skill fail-closed 裁剪、显式 `AgentExecutionContext`、父子委托边与 ancestry 校验、canonical `foreground/background` schema 以及批量 foreground 并发。旧 general background 仅作为兼容路径保留。Phase 2A 已落地结构化取消：`AgentError::Cancelled/TimedOut`、CancellationToken 贯穿 root Turn、Provider 连接/stream、并行与串行工具批次以及 sleep；`/stop` 保留 oneshot 兼容桥接并同时取消 Turn token，协作式与强制路径提交同一 Cancelled 终态；树级 `max_runs_per_tree` 由共享原子计数在 foreground 委托接纳时强制。Phase 2B 已落地 durable foreground 编排：schema v6（`agent_run_groups`/`agent_runs`/`agent_session_state`/`agent_inbox_events` 与 messages/sessions 扩展列）在单一迁移事务中原子创建；Storage 领域 API（接纳、running/waiting_children 条件转换、execution-ID 条件 terminal commit、plan item 原子领取/完成、游标分页）；`ExecutionGate` 分离 run quota 与 provider/tool step gate（global→session 顺序获取、弱引用键控回收、取消可中断等待），root Turn 步骤同样占用 step gate；`AgentCoordinator` 持久化全部具名 foreground run（单任务不建 group、批量建 group 并按请求顺序返回）、父 run `waiting_children` 转换、迟到结果丢弃与树位置授权；`agent_task` 工具提供 scoped get/list/get_result/cancel。foreground 不占用 run quota，嵌套 foreground 在并发上限为 1 时不死锁。Phase 3 已落地 durable inbox 与 queue continuation：具名 background 单任务经 Coordinator 接纳（completion slot 预留 → 持久化 queued → TaskSupervisor 托管 runner → terminal commit 原子转换 reservation 为 completion 事件 → notifier wake），spawn 拒绝执行补偿事务；`agent_inbox_events`/`agent_session_state` 容量条件更新与 claim/lease/admit/release/supersede/dead-letter API；`AgentInboxNotifier`（弱引用 late-bound wake）与 Session 双 lane worker（user mpsc + inbox watch 合并 wake），公平调度按 `max_user_turn_burst_before_inbox` 与 `max_inbox_wait_secs` 强制 continuation；continuation Turn 使用 hidden trigger、只读工具集，`commit_continuation_turn` 同事务提交 hidden trigger + assistant/tool/usage + event consume，失败显式 release lease；`client_visibility`/`turn_origin` 贯穿 ChatMessage/MessageMeta/协议 DTO，客户端历史查询默认过滤 hidden，`message_count` 只统计可见用户输入；activation recovery 收敛旧代 run（interrupted + failure completion）、过期 lease、group counter 与容量计数；`/stop`/archive/delete 走 `cancel_session`（suppress_continuation 写 consumed completion）并 dead-letter。background completion 不再直接通知 Channel。Phase 3 审查修复：worker 通过 `next_pending_due_at` 定时器在 release backoff 到期后重新 claim（不再依赖 wake）；达到 `max_inbox_delivery_attempts` 的事件在正常运行中即 dead-letter 而非无限重试；`recover_on_activation` 对含 due 事件的在内存 session 发送合并 wake；修正 MIN 聚合无行时 NULL 被解码为 0 导致 worker 空转的缺陷（`oldest_pending_due`/`next_pending_due_at` 用 `Option<Option<i64>>` 显式解码）。Phase 4 已落地 emit_signal 与 steer：Agent Definition frontmatter 新增 `signal:` 块（`SignalContract`：delivery queue/steer、总数/字节/间隔/burst/severity allowlist/dedupe 冷却窗/JSON 深度，全部由工具与 Coordinator 强制，模型只提供 key/severity/summary/details/dedupe_key）；`EmitSignalTool` 仅在带 contract 的 run 注册（fail-closed），`insert_agent_signal` 支持同冷却窗 dedupe（返回原 event + deduplicated）；Coordinator `emit_signal` 校验 run 活跃与 execution ID、容量条件插入、投影+notifier wake，取消 run 时未消费 signal 自动 supersede；SteeringMailbox 泛化为来源感知 TurnMailbox（user lane 32/64KiB 与 agent lane 8/32KiB 独立容量，`TurnInput{source,delivery,durable_event_id,lease_token}`，agent steer 投影为 hidden user 消息保留 source 元数据）；steer 两阶段 admission（claim → mailbox 预留 → DB admit(turn_id) → 同 Turn/generation 激活），任何失败 release lease 并 wake queue lane；`/stop`/generation 变更时已 admit 的 steer 事件按 lease token 条件释放回 pending（绝不静默丢弃），用户 Turn commit 与 steer 事件 consume 同事务（`persist_turn_batch_with_steer_consumption`）。Phase 3 收尾已落地：`ChannelContext.durable_private`（Feishu 仅 thread/root/chat_type 进入）持久化到 `sessions.delivery_context` 并被 continuation 投递复用；WS 协议 `GetAgentRuns`/`GetAgentRun` 与 `SessionAgentRuns`/`AgentRunUpdated`/`AgentEventUpdated`（有界 `AgentRunView`/`AgentEventView`，不暴露 budget/contract/delivery context/execution id）；`AgentProjectionHub` broadcast（复用 plan-change 模式，lag 由客户端 GetAgentRuns 校准）；HTTP `/api/agent-runs*`（列表游标分页/详情/events/cancel）+ `/api/tasks` legacy/new union；WebUI TasksPage 后台 tab 渲染 run tree（group 折叠、agent 标签、深度缩进），ChatPage 显示 continuation 标签与 Signal 卡片（投影事件，不插入 history）。Phase 5 尚未完成：wake-aware sleep 与工具中断策略。
|
||
|
||
## 1. 审查结论
|
||
|
||
结论为：**设计可实施，没有需要推翻总体方案的阻断项，但必须按依赖顺序实施，不能在当前 `SubAgentManager` 上直接追加 durable inbox 或 steer signal。**
|
||
|
||
当前代码已经提供以下可复用基础：
|
||
|
||
- `AgentLoop` 已经是跨 Turn 无状态执行器，工具执行统一经过 `ToolExecutionContext` 和 `ToolOutputProcessor`。
|
||
- Session 已有单 worker、用户输入有界队列、活动 Turn steering、generation/state version 和 persistence lock。
|
||
- `TurnController`、`DeliveryCoordinator` 已建立“持久化成功后才 Completed”的边界。
|
||
- Storage 已有单事务迁移、批量消息与 usage 原子提交模式。
|
||
- `TaskSupervisor`、`RuntimeAdmission` 和 Gateway 候选运行代已经提供重载与有界关闭框架。
|
||
- WorkManager 已有 `execution_id` 条件更新和计划变更广播。
|
||
- WebSocket 已有 request/event 路由与断线后全量校准的现成模式。
|
||
|
||
必须先解决的结构性差距如下：
|
||
|
||
| 领域 | 当前实现 | 实施要求 | 风险等级 |
|
||
|------|----------|----------|----------|
|
||
| Agent 身份 | 一个共享 Provider 的临时子 Agent | 不可变 AgentCatalog、具名 definition、显式 caller/run context | 高 |
|
||
| 委托生命周期 | `inline/background/parallel` 混合建模 | `foreground/background` 与批量并发正交 | 中 |
|
||
| 取消 | Session 在 AgentLoop 外 drop future | CancellationToken 贯穿 Provider stream、工具批次和 child tree | 高 |
|
||
| 并发 | background run 持有一个 Semaphore permit | run admission 与 provider/tool step permit 分离 | 高 |
|
||
| 结果投递 | background 终态直接发 Channel | SQLite inbox 为事实源，Session wake 仅为加速器 | 高 |
|
||
| steering | mailbox 只接受用户 ChatMessage | 来源感知 TurnInput、durable admission 和可靠 queue fallback | 高 |
|
||
| continuation | 用户任务在模型调用前落库 | hidden trigger 与 assistant/tool/usage/event consume 同事务提交 | 高 |
|
||
| history | 所有 role=user 都作为用户消息 | internal replay 读 hidden，客户端默认过滤 hidden | 高 |
|
||
| Channel context | `reply_to` 与 opaque `private` 未区分稳定性 | Channel 显式提供 `durable_private`，核心不得猜 key | 高 |
|
||
| 重载恢复 | 候选代创建完整 SessionManager | Catalog 在 prepare 校验，run/inbox 恢复只能 activation 后执行 | 高 |
|
||
| 客户端 | `/api/tasks` 只读旧 `background_tasks` | 新 run/event 投影、revision、旧表 union 过渡 | 中 |
|
||
|
||
实现的关键路径为：
|
||
|
||
```text
|
||
Catalog/Tool policy
|
||
↓
|
||
AgentLoop cancellation + execution gate
|
||
↓
|
||
Run/group durable lifecycle
|
||
↓
|
||
Inbox state/capacity + Session wake + queue continuation
|
||
↓
|
||
Typed TurnMailbox + emit_signal/steer
|
||
↓
|
||
Wake-aware sleep + UI/legacy cleanup
|
||
```
|
||
|
||
Phase 3 依赖前面全部基础。若跳过 cancellation、持久化状态机或 hidden message 分层，结果会在 `/stop`、reload、SQLite 失败或进程重启时出现无法修复的丢失与重复。
|
||
|
||
## 2. 实施中固定的架构决策
|
||
|
||
以下决策在编码前固定，不留给各模块自行解释：
|
||
|
||
1. Root Agent 是运行时身份，不创建虚假的 root run。`ToolExecutionContext.agent=None` 表示 Root；child 必须携带完整 `AgentExecutionContext`。
|
||
2. `foreground/background` 只描述调用方是否等待。批量是否并发由 `tasks[]` 和调度器决定；不再存在 canonical `parallel` 模式。
|
||
3. 每个 Agent Run 都落 `agent_runs`，包括 foreground。这样截断结果、失败审计和 `agent_task.get_result` 对两种模式一致。
|
||
4. Background 接纳时预留 completion slot。signal 可以因 inbox 满而失败，已经接纳的 run completion 不得因容量耗尽而丢失。
|
||
5. SQLite 是 run、event、容量计数和消费状态的唯一事实源。watch/broadcast/内存 map 只负责降低延迟或缓存投影。
|
||
6. queue continuation 不伪造 `InboundMessage`。它通过 Session 内部 typed task 启动，并在成功时原子保存 hidden trigger、可见结果和 event consumption。
|
||
7. `steer` 不取消 Provider 或普通工具；它只在安全边界注入。`/stop` 和显式 cancel 才触发 cancellation token。
|
||
8. 候选运行代只解析和校验 Catalog，不扫描或修改数据库运行状态。恢复动作仅在新代 activation 后执行。
|
||
9. 新工具默认 `RootOnly`。只有经过逐项审计的工具可以标记 `Delegatable`；runtime control 工具由 Coordinator 注入。
|
||
10. session 归档/删除、run 取消、event supersede 和 dead-letter 都保留审计事实，不通过物理删除表达状态变化。
|
||
|
||
## 3. 目标运行时组件与依赖装配
|
||
|
||
### 3.1 GatewayState 新增成员
|
||
|
||
建议增加：
|
||
|
||
```rust
|
||
pub struct GatewayState {
|
||
// existing fields ...
|
||
agent_catalog: Arc<AgentCatalog>,
|
||
agent_coordinator: Arc<AgentCoordinator>,
|
||
agent_result_router: Arc<AgentResultRouter>,
|
||
agent_projection_hub: Arc<AgentProjectionHub>,
|
||
}
|
||
```
|
||
|
||
装配顺序必须明确：
|
||
|
||
```text
|
||
Config + registered built-in tools + SkillsLoader
|
||
→ parse/validate AgentCatalog
|
||
→ create AgentProjectionHub
|
||
→ create late-bound AgentInboxNotifier
|
||
→ create AgentCoordinator(Storage, Catalog, ProviderFactory, tools, Supervisor, Admission)
|
||
→ create SessionManager(..., notifier)
|
||
→ bind notifier to Weak<SessionManager wake interface>
|
||
→ create AgentResultRouter(Storage, notifier, projection hub)
|
||
```
|
||
|
||
`AgentInboxNotifier` 使用 late-bound weak target 解决 Coordinator/SessionManager 的环形依赖：
|
||
|
||
```rust
|
||
#[async_trait]
|
||
pub trait AgentInboxWakeTarget: Send + Sync {
|
||
async fn wake_agent_inbox(&self, session_id: &str, revision: i64);
|
||
}
|
||
|
||
pub struct AgentInboxNotifier {
|
||
target: RwLock<Weak<dyn AgentInboxWakeTarget>>,
|
||
}
|
||
```
|
||
|
||
事件提交后 notifier 失败不回滚事务；周期扫描会重新唤醒。SessionManager 也不能反向持有强 `Arc<AgentCoordinator>` 形成释放环。
|
||
|
||
### 3.2 prepare 与 activation 分离
|
||
|
||
`GatewayState::from_config()` 是候选运行代准备阶段，只允许：
|
||
|
||
- 解析配置和 Agent Markdown。
|
||
- 校验 Provider profile、工具、skill 和委托图。
|
||
- 创建无外部副作用的内存对象。
|
||
- 运行 Storage schema migration。
|
||
|
||
`start_message_processing()` 成为 activation 边界，按顺序执行：
|
||
|
||
1. 连接 MCP；第一版 Agent Definition 不允许引用 MCP 工具，因此此步不改变已经校验完成的 Catalog。
|
||
2. 启动 Session worker/router、projection relay 和 inbox recovery scanner。
|
||
3. 调用 `AgentCoordinator::recover_on_activation(runtime_generation)`，收敛旧代 queued/running/waiting runs。
|
||
4. 扫描 pending/expired leases，修复 `agent_session_state` 计数并发出合并式 wake。
|
||
5. 最后打开新代的 Agent run admission。
|
||
|
||
为避免候选代构造期间与旧代同时修改 run 状态，Coordinator 初始处于 closed 状态，activation 成功后才 `open()`。
|
||
|
||
## 4. 配置与 Agent Definition
|
||
|
||
### 4.1 配置类型
|
||
|
||
在 `src/config/mod.rs` 增加：
|
||
|
||
```rust
|
||
#[derive(Debug, Clone, Deserialize, Serialize)]
|
||
#[serde(default, deny_unknown_fields)]
|
||
pub struct AgentOrchestrationConfig {
|
||
pub enabled: bool,
|
||
pub definitions_dir: String,
|
||
pub root_delegates: Vec<String>,
|
||
pub max_tree_depth: u16,
|
||
pub max_runs_per_tree: usize,
|
||
pub max_concurrent_runs: usize,
|
||
pub max_concurrent_runs_per_session: usize,
|
||
pub max_concurrent_provider_steps: usize,
|
||
pub max_concurrent_provider_steps_per_session: usize,
|
||
pub max_concurrent_tool_steps: usize,
|
||
pub max_concurrent_tool_steps_per_session: usize,
|
||
pub max_pending_inbox_events_per_session: usize,
|
||
pub inbox_event_ttl_hours: u64,
|
||
pub max_inbox_delivery_attempts: u32,
|
||
pub max_user_turn_burst_before_inbox: usize,
|
||
pub max_inbox_wait_secs: u64,
|
||
}
|
||
```
|
||
|
||
`Config` 增加 `#[serde(default)] pub agent_orchestration: AgentOrchestrationConfig`。所有默认值必须保持现有配置可加载。旧 `gateway.max_concurrent_background_tasks` 在迁移期只控制 legacy adapter；新实现不复用该字段表达三类不同配额。
|
||
|
||
配置校验需要拒绝 0 容量、session 上限大于 global 上限、TTL/timeout 超过硬上限，以及 definitions 目录越界。配置示例、README 和运行时 config reference 在功能合并时同步更新。
|
||
|
||
热重载允许把 inbox 上限降低到当前占用以下：已有 pending 和 reservation 仍受保护，不删除也不拒绝其 completion；新 background 接纳和 signal 在计数回落到新上限前返回 capacity exceeded。
|
||
|
||
### 4.2 Markdown parser
|
||
|
||
新增 `serde_yaml` 依赖，禁止用现有 Skill frontmatter 的宽松字符串 parser 解析安全配置。建议类型：
|
||
|
||
```rust
|
||
#[derive(Deserialize)]
|
||
#[serde(deny_unknown_fields)]
|
||
struct AgentFrontmatter {
|
||
id: AgentId,
|
||
description: String,
|
||
llm_profile: String,
|
||
#[serde(default)] tools: Vec<String>,
|
||
#[serde(default)] delegates: Vec<AgentId>,
|
||
#[serde(default)] skills: Vec<String>,
|
||
#[serde(default)] limits: AgentLimits,
|
||
}
|
||
```
|
||
|
||
加载算法：
|
||
|
||
1. canonicalize definitions root，确认它是受信任目录。
|
||
2. 只读取 root 第一层的 `*.md`，按文件名排序，保证错误顺序和 hash 稳定。
|
||
3. 对每个文件先用 metadata 检查上限，再做有界读取；拒绝非 UTF-8、越界 symlink 和非普通文件。
|
||
4. frontmatter 必须以第一行 `---` 开始并有独立结束 `---`；正文为空、重复 key、未知 key 均报错。
|
||
5. `id` 使用 `[a-z][a-z0-9_-]{0,63}`，拒绝大小写折叠冲突和保留名。
|
||
6. 对规范化 frontmatter JSON 与原始 role body 计算 SHA-256 `definition_hash`。
|
||
7. 第一遍建立 ID map，第二遍解析 delegate target、Provider、工具和 skill 引用。
|
||
|
||
Catalog 最终类型不可变：
|
||
|
||
```rust
|
||
pub struct AgentCatalog {
|
||
definitions: BTreeMap<AgentId, Arc<AgentDefinition>>,
|
||
root_delegates: BTreeSet<AgentId>,
|
||
runtime_generation: u64,
|
||
}
|
||
```
|
||
|
||
第一版 Catalog 只接受候选代准备阶段已经注册的 built-in 工具。现有 MCP 连接只允许在 activation 发生，为维持候选代无外部副作用和“引用错误拒绝整代”的不变量，MCP 工具不得出现在 Agent Definition；未来只有在 MCP 提供可离线校验的 tool manifest 后才能开放。
|
||
|
||
### 4.3 legacy general
|
||
|
||
当 orchestration 未配置或旧调用没有 `target` 时，兼容层提供代码内置 `general` definition：
|
||
|
||
- Provider 使用当前 root agent profile。
|
||
- 工具只取旧 default list 与 `Delegatable` 的交集。
|
||
- 不能继续 delegate，不能 emit signal。
|
||
- 保留旧 transient browser scope 的兼容行为并返回弃用提示。
|
||
|
||
显式配置的具名 Agent 永远不继承该例外。
|
||
|
||
## 5. ToolRegistry 与执行上下文改造
|
||
|
||
### 5.1 Tool 元数据
|
||
|
||
在 `Tool` trait 增加默认安全元数据：
|
||
|
||
```rust
|
||
fn delegation_policy(&self) -> DelegationPolicy {
|
||
DelegationPolicy::RootOnly
|
||
}
|
||
|
||
fn input_interrupt_policy(&self) -> InputInterruptPolicy {
|
||
InputInterruptPolicy::Never
|
||
}
|
||
```
|
||
|
||
`DelegationPolicy` 为 `RootOnly | Delegatable | RuntimeInjected`；`InputInterruptPolicy` 为 `Never | WakeOnly | CancelSafe`。二者不能从 Markdown 覆盖。
|
||
|
||
第一轮审计建议：
|
||
|
||
| 工具类型 | 初始策略 | 说明 |
|
||
|----------|----------|------|
|
||
| file/content search、file read | Delegatable | 仍受现有进程文件权限约束，不代表硬 sandbox |
|
||
| browser 普通动作 | Delegatable | 具名 run 使用独立 transient resource scope |
|
||
| `get_skill` | RuntimeInjected wrapper | 只能读取 definition 的 skill allowlist |
|
||
| HTTP request | RootOnly | 当前实现支持写方法；以后可增加 delegated GET-only wrapper |
|
||
| bash、file write/edit | RootOnly | 需单独威胁建模后才开放 |
|
||
| send_message、todo、cron、reload、browser_profiles、管理工具 | RootOnly | 有外部或全局状态副作用 |
|
||
| delegate、agent_task、emit_signal | RuntimeInjected | 依据 caller context 动态注入 |
|
||
| sleep | Delegatable + WakeOnly | child 无 TurnWakeupHandle，只响应 timer/cancel |
|
||
|
||
`ToolRegistry` 增加只读构建方法，不在共享 registry 上删除工具：
|
||
|
||
```rust
|
||
pub fn scoped_for_agent(
|
||
&self,
|
||
definition: &AgentDefinition,
|
||
runtime_tools: Vec<Arc<dyn Tool>>,
|
||
) -> Result<Arc<ToolRegistry>, AgentCatalogError>;
|
||
```
|
||
|
||
### 5.2 ToolExecutionContext
|
||
|
||
目标类型：
|
||
|
||
```rust
|
||
#[derive(Clone)]
|
||
pub struct ToolExecutionContext {
|
||
pub session_id: Option<String>,
|
||
pub turn_id: Option<String>,
|
||
pub agent: Option<Arc<AgentExecutionContext>>,
|
||
pub cancellation: CancellationToken,
|
||
pub execution_gate: Option<Arc<ExecutionGate>>,
|
||
pub turn_wakeup: Option<TurnWakeupHandle>,
|
||
pub resource_scope_id: Option<String>,
|
||
pub turn_origin: TurnOrigin,
|
||
}
|
||
```
|
||
|
||
Root interactive context 的 `agent=None`；Coordinator 只允许在 session/turn 身份完整时把它解释成 ROOT。缺少两者的 context 不能调用 delegate。child 的 `agent=Some`，其中 run、parent、ancestry、budget 和 signal contract 是授权事实。
|
||
|
||
不要再依赖 `DELEGATE_CONTEXT` task-local 作授权。它可以暂时保留为旧 adapter 桥接，但所有新工具必须从 `ToolExecutionContext` 读取身份。
|
||
|
||
## 6. AgentLoop：取消、许可与 typed input
|
||
|
||
### 6.1 CancellationContext
|
||
|
||
给 AgentLoop 的所有 process 入口增加 `AgentLoopExecution`：
|
||
|
||
```rust
|
||
pub struct AgentLoopExecution {
|
||
pub cancellation: CancellationToken,
|
||
pub gate: Arc<ExecutionGate>,
|
||
pub tool_context: ToolExecutionContext,
|
||
}
|
||
```
|
||
|
||
Provider 请求必须在获取 provider-step permit 后执行：
|
||
|
||
```rust
|
||
let _permit = execution.gate.acquire_provider(&execution.cancellation).await?;
|
||
let response = tokio::select! {
|
||
_ = execution.cancellation.cancelled() => Err(AgentError::Cancelled),
|
||
result = self.stream_completion(...) => result,
|
||
};
|
||
```
|
||
|
||
普通工具调用同样取得 tool-step permit。runtime-control 工具不取得普通 tool permit，防止父 run 等 child 时占住唯一许可。工具 future 被取消只表示 PicoBot 不再等待；对 bash、HTTP 写入等外部副作用不能宣称已回滚，因此迟到结果必须被 execution ID 条件提交挡住。
|
||
|
||
工具批次当前使用 `join_all`。改造后每项 future 自行获取 permit，批次仍可并发；取消时等待一个很短的 cooperative grace，然后由外层 task abort。`AgentError` 增加结构化 `Cancelled` 和 `TimedOut`，不要用字符串判断终态。
|
||
|
||
### 6.2 ExecutionGate
|
||
|
||
配额分成两组：
|
||
|
||
- `RunQuota`：统计 queued/running/waiting_children 的非终态 run，直到 terminal commit 才释放。
|
||
- `StepGate`：provider/tool 步骤执行期间持有，步骤结束立即释放。
|
||
|
||
permit 固定按 global → session → agent 顺序获取；失败或取消逆序释放。为了避免动态 semaphore 缓存泄漏，session/agent gate 使用带弱引用的 keyed registry，并在没有 run/permit 时清理。
|
||
|
||
Root Turn 不是 Agent Run，不占 run quota，但它的 Provider/tool 步骤占 global/session step gate，这样 background run 不会绕过整个 Gateway 的资源上限。
|
||
|
||
### 6.3 waiting_children
|
||
|
||
`delegate` foreground 执行前创建 `WaitingChildrenGuard`：
|
||
|
||
1. child 接纳成功后，条件更新 parent `running → waiting_children`。
|
||
2. 等待期间父没有 provider/tool step permit。
|
||
3. 全部 child 终态、父取消或错误退出时 guard 尝试 `waiting_children → running`；父已经 terminal 时不覆盖。
|
||
4. 父取消递归取消未终态 foreground descendants；background run 归 root session token 所有，不因创建它的 Turn 正常结束而取消。
|
||
|
||
### 6.4 typed Turn input
|
||
|
||
Phase 4 将 `SteeringMailbox<ChatMessage>` 替换为 `TurnMailbox<TurnInput>`。在此之前 Phase 2A 只做 cancellation，不改变用户 steering 行为，降低一次改动的回归面。
|
||
|
||
`AgentLoop::append_steering_messages` 不再强制构造 user source；改为由 serializer 把 typed source 转成 Provider-compatible role，同时保留 durable source metadata。Agent event envelope 明确标注为不可信数据，不能改变 system/tool 权限。
|
||
|
||
## 7. AgentCoordinator API 与状态机
|
||
|
||
建议公开最小接口：
|
||
|
||
```rust
|
||
pub struct DelegateRequest {
|
||
pub mode: ExecutionMode,
|
||
pub tasks: Vec<DelegateTask>,
|
||
pub completion_policy: CompletionPolicy,
|
||
pub idempotency_key: Option<String>,
|
||
}
|
||
|
||
impl AgentCoordinator {
|
||
pub async fn delegate(&self, caller: CallerContext, request: DelegateRequest)
|
||
-> Result<DelegateResponse, AgentCoordinatorError>;
|
||
pub async fn get_run(&self, caller: CallerContext, run_id: &RunId) -> Result<AgentRunView, _>;
|
||
pub async fn list_runs(&self, caller: CallerContext, query: AgentRunQuery) -> Result<_, _>;
|
||
pub async fn get_result(&self, caller: CallerContext, run_id: &RunId) -> Result<_, _>;
|
||
pub async fn cancel_run(&self, caller: CallerContext, run_id: &RunId) -> Result<_, _>;
|
||
pub async fn emit_signal(&self, context: &AgentExecutionContext, signal: SignalInput)
|
||
-> Result<SignalAccepted, _>;
|
||
pub async fn cancel_session(&self, session_id: &str, reason: CancelReason) -> Result<(), _>;
|
||
pub async fn recover_on_activation(&self, generation: u64) -> Result<RecoveryReport, _>;
|
||
}
|
||
```
|
||
|
||
### 7.1 Background 接纳顺序
|
||
|
||
严格顺序：
|
||
|
||
1. 从 context 解析 caller，校验 root session、委托边、ancestry、depth 和 budget。
|
||
2. 解析全部 target definition，派生 deadline、token/run reservation 和 delivery contract。
|
||
3. 取得 RuntimeAdmission activity guard 和内存 run quota reservation；尚未写库前任何失败均直接释放。
|
||
4. Storage 事务条件增加 completion reservation、领取 plan item、插入 group/run queued 记录。
|
||
5. 把 cancellation token 和 execution ID 注册到 Coordinator active map。
|
||
6. 通过 `TaskSupervisor::spawn_graceful` 接纳 runner。
|
||
7. spawn 被拒绝时执行补偿事务：queued → cancelled、释放 completion reservation、回滚/阻塞已领取 plan item；不得向模型返回可用 run ID。
|
||
8. spawn 成功后返回 run/group ID。
|
||
|
||
第一版在步骤 1 强制 `background caller == ROOT`；child 只能 foreground 委托。该限制属于 Coordinator policy，不仅是 delegate schema 提示。以后开放 nested background 时仍必须把 run 归属到原 root session，并重新审查取消所有权和 completion reservation。
|
||
|
||
SQLite commit 与 task spawn 无法成为同一原子操作。崩溃发生在步骤 4 与 6 之间时，会留下旧 generation 的 queued run；activation recovery 必须将其收敛为 `interrupted` 并生成预留过的 completion，不能无限保持 queued。
|
||
|
||
ActivityGuard 必须移动进已接纳的 background runner，直到 terminal transaction 完成后才 drop；不能在 `delegate` 返回时提前释放。Runner 等待 run quota/provider permit 时同样受 deadline 和 cancellation 约束，排队时间计入 run timeout。
|
||
|
||
### 7.2 Foreground 执行
|
||
|
||
Foreground 同样先持久化 run，但不预留 inbox slot，也不创建 completion event。单任务直接 await；批量使用 `FuturesUnordered` 并保存原 request index，最终按请求顺序组装结果。每个 child 有独立取消 token；父取消时全部 token 同时取消。
|
||
|
||
完整结果先写 `agent_runs.result`，tool result 只返回有界 projection。这样无论是否截断，`agent_task.get_result` 都能读取相同事实。
|
||
|
||
### 7.3 terminal commit
|
||
|
||
Runner 只返回 `AgentTerminalOutcome`，不能自己发 Channel 或更新 WorkManager：
|
||
|
||
```rust
|
||
pub enum AgentTerminalOutcome {
|
||
Completed { result: String, usage: Usage, tool_calls: u32, iterations: u32 },
|
||
Failed { error: AgentRunError, usage: Option<Usage> },
|
||
TimedOut { deadline_at: i64 },
|
||
Cancelled { reason: CancelReason },
|
||
Interrupted { reason: String },
|
||
}
|
||
```
|
||
|
||
Coordinator 用 `(run_id, execution_id, runtime_generation, nonterminal status)` 条件提交。只有更新行数为 1 的赢家可以：
|
||
|
||
- 写终态和完整 result/error。
|
||
- 更新 group terminal counter。
|
||
- 转换或释放 completion reservation。
|
||
- 插入 run/group inbox event。
|
||
- 更新绑定的 task item。
|
||
- 递增 session agent revision。
|
||
|
||
迟到结果返回 `StaleExecution` 并丢弃，不改变已保存终态。
|
||
|
||
Coordinator 还需启动一个由 TaskSupervisor 管理、观察 shutdown token 的 deadline reaper。正常 runner 使用 `timeout_at(deadline)`；reaper 负责没有活跃内存 task 的 queued run 和 group deadline，分批条件终态化未完成 children，再走同一个 terminal transaction，不能维护第二套完成逻辑。
|
||
|
||
## 8. Storage schema v6
|
||
|
||
实现时把 `SCHEMA_VERSION` 从 5 升到 6。表创建、旧列增加、索引和 `PRAGMA user_version=6` 必须在当前 `migrate_schema()` 的同一事务中完成。下面的 `ALTER TABLE` 表达目标列；实际代码必须同时更新 fresh-schema 的 `CREATE TABLE`，迁移时沿用现有 `PRAGMA table_info` 检查，仅对缺失列执行 ALTER，不能在 fresh database 上重复加列。
|
||
|
||
SQLite 使用 INTEGER 表示布尔值；应用层枚举仍用 Rust enum，读到未知值要报 corruption，不能静默当成 completed。
|
||
|
||
### 8.1 session 与 message 扩展
|
||
|
||
```sql
|
||
ALTER TABLE sessions ADD COLUMN delivery_context TEXT;
|
||
ALTER TABLE sessions ADD COLUMN delivery_context_updated_at INTEGER;
|
||
|
||
ALTER TABLE messages
|
||
ADD COLUMN client_visibility TEXT NOT NULL DEFAULT 'visible';
|
||
ALTER TABLE messages
|
||
ADD COLUMN turn_origin TEXT NOT NULL DEFAULT 'user';
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_messages_session_visibility_seq
|
||
ON messages(session_id, client_visibility, seq);
|
||
```
|
||
|
||
`delivery_context` 只序列化 `ChannelContext.durable_private`。现有 `reply_to` 和 `private` 永不写入该字段。
|
||
|
||
### 8.2 agent_session_state
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS agent_session_state (
|
||
root_session_id TEXT PRIMARY KEY,
|
||
revision INTEGER NOT NULL DEFAULT 0,
|
||
pending_event_count INTEGER NOT NULL DEFAULT 0,
|
||
reserved_completion_slots INTEGER NOT NULL DEFAULT 0,
|
||
updated_at INTEGER NOT NULL,
|
||
CHECK (revision >= 0),
|
||
CHECK (pending_event_count >= 0),
|
||
CHECK (reserved_completion_slots >= 0)
|
||
);
|
||
```
|
||
|
||
这是 inbox 容量和客户端 revision 的权威计数行。每个改变客户端 run/group/event 投影的事务只分配一个新 revision，并把同一 revision 写回本事务改变的所有行；仅内部读取不递增。所有容量增加操作使用条件更新：
|
||
|
||
```sql
|
||
UPDATE agent_session_state
|
||
SET reserved_completion_slots = reserved_completion_slots + ?,
|
||
revision = revision + 1,
|
||
updated_at = ?
|
||
WHERE root_session_id = ?
|
||
AND pending_event_count + reserved_completion_slots + ? <= ?
|
||
RETURNING revision;
|
||
```
|
||
|
||
若 session 尚无行，先 `INSERT ... ON CONFLICT DO NOTHING`，仍在同一写事务中执行条件更新。
|
||
|
||
### 8.3 agent_run_groups
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS agent_run_groups (
|
||
id TEXT PRIMARY KEY,
|
||
root_session_id TEXT NOT NULL,
|
||
caller_run_id TEXT,
|
||
caller_scope_id TEXT NOT NULL,
|
||
idempotency_key TEXT,
|
||
mode TEXT NOT NULL,
|
||
completion_policy TEXT NOT NULL,
|
||
expected_runs INTEGER NOT NULL,
|
||
terminal_runs INTEGER NOT NULL DEFAULT 0,
|
||
abnormal_runs INTEGER NOT NULL DEFAULT 0,
|
||
completion_slot_reserved INTEGER NOT NULL DEFAULT 0,
|
||
completion_delivery TEXT,
|
||
failure_delivery TEXT,
|
||
deadline_at INTEGER NOT NULL,
|
||
status TEXT NOT NULL,
|
||
runtime_generation INTEGER NOT NULL,
|
||
revision INTEGER NOT NULL,
|
||
created_at INTEGER NOT NULL,
|
||
updated_at INTEGER NOT NULL,
|
||
finished_at INTEGER,
|
||
CHECK (mode IN ('foreground', 'background')),
|
||
CHECK (completion_policy IN ('all', 'each')),
|
||
CHECK (status IN ('queued', 'running', 'completed', 'partial', 'failed',
|
||
'timed_out', 'cancelled', 'interrupted')),
|
||
CHECK (expected_runs > 0),
|
||
CHECK (terminal_runs >= 0 AND terminal_runs <= expected_runs),
|
||
CHECK (completion_slot_reserved IN (0, 1))
|
||
);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_agent_groups_session_created
|
||
ON agent_run_groups(root_session_id, created_at DESC);
|
||
|
||
CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_groups_idempotency
|
||
ON agent_run_groups(root_session_id, caller_scope_id, idempotency_key)
|
||
WHERE idempotency_key IS NOT NULL;
|
||
```
|
||
|
||
批量请求把 request idempotency key 写在 group，所有 child run 的 `idempotency_key` 为 NULL；单任务请求不创建只含一个 child 的 group，key 直接写在 run。这样 retry 能返回原 group/run，又不会让同一批 children 触发唯一索引冲突。
|
||
|
||
### 8.4 agent_runs
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS agent_runs (
|
||
id TEXT PRIMARY KEY,
|
||
group_id TEXT,
|
||
root_session_id TEXT NOT NULL,
|
||
root_turn_id TEXT,
|
||
parent_run_id TEXT,
|
||
caller_agent_id TEXT NOT NULL,
|
||
caller_scope_id TEXT NOT NULL,
|
||
idempotency_key TEXT,
|
||
agent_id TEXT NOT NULL,
|
||
definition_hash TEXT NOT NULL,
|
||
provider_profile TEXT NOT NULL,
|
||
provider_name TEXT NOT NULL,
|
||
model_id TEXT NOT NULL,
|
||
mode TEXT NOT NULL,
|
||
depth INTEGER NOT NULL,
|
||
plan_item_id TEXT,
|
||
execution_id TEXT NOT NULL,
|
||
task TEXT NOT NULL,
|
||
context_json TEXT,
|
||
budget_json TEXT NOT NULL,
|
||
signal_contract_json TEXT,
|
||
signal_delivery TEXT,
|
||
completion_delivery TEXT,
|
||
failure_delivery TEXT,
|
||
status TEXT NOT NULL,
|
||
result TEXT,
|
||
error TEXT,
|
||
prompt_tokens INTEGER,
|
||
completion_tokens INTEGER,
|
||
cost REAL,
|
||
tool_calls_count INTEGER NOT NULL DEFAULT 0,
|
||
iterations INTEGER NOT NULL DEFAULT 0,
|
||
runtime_generation INTEGER NOT NULL,
|
||
attempt INTEGER NOT NULL DEFAULT 1,
|
||
completion_slot_reserved INTEGER NOT NULL DEFAULT 0,
|
||
deadline_at INTEGER NOT NULL,
|
||
revision INTEGER NOT NULL,
|
||
started_at INTEGER,
|
||
finished_at INTEGER,
|
||
created_at INTEGER NOT NULL,
|
||
updated_at INTEGER NOT NULL,
|
||
CHECK (mode IN ('foreground', 'background')),
|
||
CHECK (status IN ('queued', 'running', 'waiting_children', 'completed',
|
||
'failed', 'timed_out', 'cancelled', 'interrupted')),
|
||
CHECK (depth >= 1),
|
||
CHECK (completion_slot_reserved IN (0, 1)),
|
||
FOREIGN KEY (group_id) REFERENCES agent_run_groups(id) ON DELETE RESTRICT,
|
||
FOREIGN KEY (parent_run_id) REFERENCES agent_runs(id) ON DELETE RESTRICT
|
||
);
|
||
|
||
CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_runs_execution
|
||
ON agent_runs(execution_id);
|
||
|
||
CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_runs_idempotency
|
||
ON agent_runs(root_session_id, caller_scope_id, idempotency_key)
|
||
WHERE idempotency_key IS NOT NULL;
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_agent_runs_session_created
|
||
ON agent_runs(root_session_id, created_at DESC);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_agent_runs_parent
|
||
ON agent_runs(parent_run_id, created_at);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_agent_runs_recovery
|
||
ON agent_runs(runtime_generation, status, deadline_at);
|
||
```
|
||
|
||
Session 使用软删除，agent 表不对 `root_session_id` 建级联外键；生命周期由 `cancel_session` 和恢复扫描显式收敛。
|
||
|
||
### 8.5 agent_inbox_events
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS agent_inbox_events (
|
||
id TEXT PRIMARY KEY,
|
||
root_session_id TEXT NOT NULL,
|
||
scope_kind TEXT NOT NULL,
|
||
scope_id TEXT NOT NULL,
|
||
run_id TEXT,
|
||
group_id TEXT,
|
||
event_type TEXT NOT NULL,
|
||
event_key TEXT NOT NULL,
|
||
delivery TEXT NOT NULL,
|
||
requires_continuation INTEGER NOT NULL DEFAULT 1,
|
||
severity TEXT,
|
||
payload_json TEXT NOT NULL,
|
||
status TEXT NOT NULL,
|
||
attempt_count INTEGER NOT NULL DEFAULT 0,
|
||
lease_token TEXT,
|
||
lease_until INTEGER,
|
||
next_attempt_at INTEGER,
|
||
admitted_turn_id TEXT,
|
||
last_error TEXT,
|
||
revision INTEGER NOT NULL,
|
||
created_at INTEGER NOT NULL,
|
||
consumed_at INTEGER,
|
||
superseded_at INTEGER,
|
||
dead_lettered_at INTEGER,
|
||
fallback_notified_at INTEGER,
|
||
fallback_suppressed_reason TEXT,
|
||
CHECK (scope_kind IN ('run', 'group')),
|
||
CHECK (event_type IN ('signal', 'completion', 'group_completion')),
|
||
CHECK (delivery IN ('queue', 'steer')),
|
||
CHECK (requires_continuation IN (0, 1)),
|
||
CHECK (status IN ('pending', 'leased', 'admitted', 'consumed',
|
||
'superseded', 'dead_letter')),
|
||
CHECK (
|
||
(scope_kind = 'run' AND run_id IS NOT NULL AND group_id IS NULL
|
||
AND scope_id = run_id) OR
|
||
(scope_kind = 'group' AND group_id IS NOT NULL AND run_id IS NULL
|
||
AND scope_id = group_id)
|
||
),
|
||
UNIQUE(scope_kind, scope_id, event_type, event_key),
|
||
FOREIGN KEY (run_id) REFERENCES agent_runs(id) ON DELETE RESTRICT,
|
||
FOREIGN KEY (group_id) REFERENCES agent_run_groups(id) ON DELETE RESTRICT
|
||
);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_agent_inbox_claim
|
||
ON agent_inbox_events(root_session_id, status, next_attempt_at, created_at);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_agent_inbox_lease
|
||
ON agent_inbox_events(status, lease_until);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_agent_inbox_revision
|
||
ON agent_inbox_events(root_session_id, revision);
|
||
```
|
||
|
||
run/group 外键使用 RESTRICT。清理默认只清理大正文或归档整组记录；若未来需要物理删除，必须先按明确保留策略删除 terminal inbox event，再删除 run/group，不能留下失去审计来源的事件。
|
||
|
||
### 8.6 事务 API
|
||
|
||
不要把 SQL 分散在 Coordinator、Router 和 WorkManager。Storage 增加领域 API：
|
||
|
||
```rust
|
||
accept_agent_group(request) -> AcceptedGroup
|
||
mark_agent_run_running(run_id, execution_id)
|
||
mark_agent_run_waiting_children(run_id, execution_id, expected_status)
|
||
commit_agent_terminal(run_id, execution_id, outcome) -> TerminalCommit
|
||
insert_agent_signal(run_id, execution_id, signal) -> EventCommit
|
||
claim_inbox_batch(session_id, now, lease) -> InboxLease
|
||
admit_inbox_event(event_id, lease_token, turn_id)
|
||
release_inbox_lease(event_ids, lease_token, retry)
|
||
commit_continuation_turn(batch) -> CommittedTurnDelta
|
||
recover_agent_state(active_generation, now) -> RecoveryReport
|
||
```
|
||
|
||
`commit_agent_terminal` 在一个事务内更新 run/group、容量计数、event、plan item 和 revision。提交后 Coordinator 调用 `WorkManager::refresh_after_external_commit()` 刷新 cache 并广播；WorkManager 不再为这条路径另开事务。
|
||
|
||
## 9. Agent Inbox、唤醒与公平调度
|
||
|
||
### 9.1 Session worker 接收面
|
||
|
||
Session 增加：
|
||
|
||
```rust
|
||
agent_tx: Option<mpsc::Sender<UserAgentTask>>,
|
||
agent_inbox_wake: watch::Sender<i64>,
|
||
consecutive_user_turns: usize,
|
||
```
|
||
|
||
把 worker 创建逻辑抽为 `ensure_agent_worker_locked()`，用户 enqueue 与 `wake_agent_inbox()` 共用。worker 同时持有 user receiver 和 wake receiver：
|
||
|
||
```rust
|
||
tokio::select! {
|
||
biased;
|
||
user = task_rx.recv(), if should_take_user => { ... }
|
||
changed = inbox_wake.changed() => { ... }
|
||
}
|
||
```
|
||
|
||
不能仅靠 `biased` 实现公平。每个 Turn 结束后查询最老 due pending event；满足以下任一条件时下一项必须是 continuation：
|
||
|
||
- `consecutive_user_turns >= max_user_turn_burst_before_inbox`；
|
||
- oldest pending age >= `max_inbox_wait_secs`。
|
||
|
||
watch value 是最新 durable revision，只合并 wake，不携带 payload。worker 收到 wake 后从 SQLite claim；发送方从不等待 Session user mpsc 容量。
|
||
|
||
### 9.2 queue continuation
|
||
|
||
claim batch 必须有大小与总字节上限，例如 8 events/32 KiB envelope。`completion_policy=each` 可在 300–500ms 内 debounce 已经 pending 的 siblings，但不能等待未终态 sibling。
|
||
|
||
执行过程：
|
||
|
||
1. Storage 把 due events `pending → leased`，返回 lease token。
|
||
2. worker 构造 `AgentTaskSource::BackgroundAgentResults` 和 hidden trigger，但暂不落 messages。
|
||
3. root Agent 使用只读 continuation ToolRegistry 执行。默认允许内容读取、检索和 scoped `agent_task.get/get_result`，不允许 send_message、todo、写文件、delegate 或其他外部副作用。
|
||
4. 成功后 `commit_continuation_turn` 原子插入 hidden trigger、tool/assistant messages、usage，并把同 token events `leased/admitted → consumed`。
|
||
5. commit 后更新 Session 内存、Turn Completed、projection 和 Channel delivery。
|
||
6. 执行失败、取消或 stale generation 时 `InboxLeaseGuard` 显式 release 到 pending 并写 `next_attempt_at`。
|
||
|
||
这一流程与当前“先持久化用户消息再调用模型”不同，必须走独立分支。不能先写 hidden trigger，否则失败重试会在 history 中累积无 assistant 配对的内部输入。
|
||
|
||
### 9.3 hidden history
|
||
|
||
`ChatMessage` 和 `MessageMeta` 增加：
|
||
|
||
```rust
|
||
pub client_visibility: ClientVisibility,
|
||
pub turn_origin: TurnOrigin,
|
||
```
|
||
|
||
默认构造器生成 `Visible/User`。需要拆分查询：
|
||
|
||
- `load_messages_for_replay(session_id)`：visible + hidden。
|
||
- `load_visible_messages(session_id, ...)`：WebSocket/HTTP/管理历史。
|
||
- `persist_message_batch_inner()`：支持两字段并保持向后兼容默认值。
|
||
- `CommittedTurnDelta`：过滤 hidden，并携带 turn origin。
|
||
|
||
Session 的 `message_count` 只统计 visible external user input；`total_message_count` 和压缩/token 估算统计全部 replay messages。自动标题只由 visible user input 触发。
|
||
|
||
### 9.4 steer admission
|
||
|
||
Router 的两阶段流程必须由测试锁定：
|
||
|
||
```text
|
||
pending --claim(token)--> leased
|
||
leased --reserve current Turn--> memory reservation (not drainable)
|
||
leased --DB admit(token, turn)--> admitted
|
||
admitted --activate same turn/generation--> drainable TurnInput
|
||
```
|
||
|
||
任何失败都取消 reservation，并以 token 把 event 恢复 pending。若 active Turn 已关闭、mailbox 满或 generation 改变，直接释放 lease并 wake queue；这就是可靠 steer→queue fallback。
|
||
|
||
TurnMailbox 分 user lane 与 agent lane 容量，最终按 session sequence 合并排空。durable agent reservation 在 DB admit 前不能被 AgentLoop 看见；`/stop` 关闭 mailbox 时返回尚未提交的 event IDs/tokens，由 SessionManager 立即 release。
|
||
|
||
## 10. emit_signal 与 completion 投影
|
||
|
||
`EmitSignalTool` 只注册到携带 background signal contract 的 runner。foreground run、Root 或没有 contract 的 child 看不到该工具。
|
||
|
||
`emit_signal` 流程：
|
||
|
||
1. 从 AgentExecutionContext 取得唯一 root session、run、execution ID 和 delivery。
|
||
2. 校验 run 仍为 running/waiting_children 且 execution ID 匹配。
|
||
3. 校验 severity、JSON 深度、summary/details 字节、信号总数、burst、最小间隔和 dedupe window。
|
||
4. 条件增加 session pending count；容量必须扣除 reserved completion slots。
|
||
5. 插入 event 和新 revision；commit 后发布 projection + wake。
|
||
6. 返回 accepted event ID。事件已存在时返回同一 ID 和 `deduplicated=true`。
|
||
|
||
Completion 永远由 Coordinator 生成。`completion_policy=all` 时每个 run terminal outcome 只存在于 `agent_runs`，不生成 per-run inbox completion；最后一个 terminal child 或 group deadline 的事务赢家生成唯一 group completion。group 有任一 failed/timed_out/interrupted/cancelled 时使用 `failure_delivery`，否则使用 `completion_delivery`。
|
||
|
||
显式 `agent_task.cancel` 可以把该 run 尚未消费的普通 signal 更新为 `superseded` 并减少 pending count；completion 事实不能 supersede。
|
||
|
||
## 11. Session 生命周期、停止与恢复
|
||
|
||
### 11.1 `/stop`
|
||
|
||
执行顺序：
|
||
|
||
1. 在 Session 锁内关闭 active Turn admission、取出 mailbox durable reservations、递增 worker generation、取出 root Turn cancellation token。
|
||
2. 锁外取消 root token，条件 release admitted/leased inbox events。
|
||
3. 调用 Coordinator cancel 当前 session 的 active background runs。
|
||
4. cancellation terminal event 使用 `requires_continuation=false` 并直接 consumed，防止 stop 后又自动启动“已取消”Turn。
|
||
5. stop 前已经 pending 的其他事件仍保持 pending；Session 下次可调度时处理。
|
||
|
||
现有 oneshot 可在过渡期由 token adapter 驱动，最终移除 `current_cancel: Option<oneshot::Sender<()>>`，统一为 `CancellationToken`。
|
||
|
||
### 11.2 archive/delete
|
||
|
||
Session 归档或软删除必须调用 `AgentCoordinator::cancel_session`。提交事务：
|
||
|
||
- 非 Scheduler 所有且未终态 run → cancelled。
|
||
- 释放所有 completion reservation。
|
||
- pending/leased/admitted events → `dead_letter(session_archived|session_deleted)`。
|
||
- 清理 mailbox reservation，不启动 continuation。
|
||
|
||
客户端仍可通过管理面看到 run/event 审计。当前没有可靠 unarchive 投递语义，因此归档事件不保留 pending。归档/删除属于用户生命周期操作，写 `fallback_suppressed_reason` 并禁止 system fallback，避免用户删除对话后又收到后台通知。
|
||
|
||
### 11.3 restart/reload recovery
|
||
|
||
activation recovery 分批执行，避免长事务：
|
||
|
||
1. 将旧 generation 的 queued/running/waiting_children 条件更新为 interrupted。
|
||
2. 为 background interrupted outcome 转换预留并插入 failure completion；foreground 只保存终态。
|
||
3. group counter 收敛并生成必要的 group completion。
|
||
4. expired leased/admitted events 恢复 pending，attempt +1，写 next retry。
|
||
5. 按每 session 重算 `pending_event_count` 和有效 reservation；差异修复并记录 structured warning。
|
||
6. 对有 pending due events 的 session 只发一次合并 wake。
|
||
|
||
旧代排空期间每个 run 持有 RuntimeAdmission activity guard。超出 reload grace 后 cancellation token 先触发；Supervisor 强制 abort 后留下的非终态记录由新代 recovery 标 interrupted。
|
||
|
||
## 12. ChannelContext 与结果投递
|
||
|
||
当前 `ChannelContext.private` 同时可能含稳定 thread/root ID 和一次性 message/reaction ID，核心无法安全猜测。类型改为：
|
||
|
||
```rust
|
||
pub struct ChannelContext {
|
||
pub reply_to: Option<String>,
|
||
pub private: HashMap<String, String>,
|
||
pub durable_private: HashMap<String, String>,
|
||
}
|
||
```
|
||
|
||
Channel adapter 负责分类：
|
||
|
||
- CLI/WebUI：通常为空。
|
||
- Feishu：thread/root/chat type 等是否可复用由 Feishu adapter 决定；message ID、reaction ID 和本次 reply target 留在 `private/reply_to`。
|
||
|
||
Session 在成功接纳外部用户输入时保存 `durable_private`。continuation 的 `TurnTarget` 使用 session 自身 channel/chat ID 和 durable context，`reply_to=None`。没有 binding 时照常提交历史和 WebSocket 投影，只跳过外部 Channel delivery。
|
||
|
||
## 13. WorkManager 原子性
|
||
|
||
当前 `assign_sub_agent` 和 `finish_sub_agent` 各自开事务，无法与 run 接纳/终态保持原子。实施方案：
|
||
|
||
- 把 plan item 条件 SQL 移入 Storage 的 agent run transaction。
|
||
- run 接纳时按 `(plan_id, item_id, status=pending)` 领取，并把 `execution_id` 写为 run execution ID。
|
||
- terminal commit 时按同 execution ID 更新 completed/blocked 和 plan version。
|
||
- WorkManager 新增 `refresh_after_external_commit(session_id, reason, item_ids)`，只负责重新查询、刷新 cache 和广播，不写数据库。
|
||
- 若 plan item 已被其他执行领取，整个 run 接纳事务回滚；不得创建一个与计划脱节的 run。
|
||
|
||
## 14. 协议、管理 API 与 WebUI
|
||
|
||
### 14.1 Rust protocol
|
||
|
||
增加 DTO 而不直接序列化 Storage row：
|
||
|
||
```text
|
||
WsInbound::GetAgentRuns { session_id, cursor, limit }
|
||
WsInbound::GetAgentRun { session_id, run_id }
|
||
|
||
WsOutbound::SessionAgentRuns { session_id, revision, runs, next_cursor }
|
||
WsOutbound::AgentRunUpdated { session_id, revision, run }
|
||
WsOutbound::AgentEventUpdated { session_id, revision, event }
|
||
```
|
||
|
||
`TurnSnapshot`、`CommittedTurnDelta`、`turn_updated` 和 `turn_committed` 增加 `turn_origin`。DTO 不暴露 task/result 全文以外的敏感 context、reasoning、Provider state、budget internals 或 delivery context。
|
||
|
||
`AgentProjectionHub` 复用 WorkManager 的 broadcast 模式。广播 lag 不补逐条事件，客户端收到 lag 或重连后调用 `GetAgentRuns` 校准。revision 来自 `agent_session_state`，客户端只接受更大的 revision；分页 cursor 使用 `(created_at,id)`，不能用 offset。
|
||
|
||
### 14.2 HTTP 管理 API
|
||
|
||
过渡期 `/api/tasks` 返回统一 projection：
|
||
|
||
- 新 `agent_runs` 映射为 `source=agent_run`。
|
||
- 旧 `background_tasks` 映射为 `source=legacy_background_task`。
|
||
- 按 created_at 合并排序，旧记录只读。
|
||
|
||
新增受设备鉴权保护的：
|
||
|
||
```text
|
||
GET /api/agent-runs?session_id=&cursor=&limit=
|
||
GET /api/agent-runs/:id
|
||
GET /api/agent-runs/:id/events
|
||
POST /api/agent-runs/:id/cancel
|
||
```
|
||
|
||
cancel endpoint 仍通过 Coordinator 做 root session/task-tree 授权，不直接执行 SQL。
|
||
|
||
### 14.3 WebUI
|
||
|
||
现有 `TasksPage.svelte` 的“后台任务”tab 演进为运行树：
|
||
|
||
- group 可折叠展示 children。
|
||
- status、Agent、Provider/model、duration、usage、工具次数。
|
||
- signal 数量、最近 severity、pending/dead-letter 标记。
|
||
- terminal result 有界预览，完整内容按需加载。
|
||
- cancel 只对允许取消的非终态 run 显示。
|
||
|
||
ChatPage 对 `turn_origin=agent_continuation` 显示轻量标签，不创建 user bubble；Signal 卡片来自 `AgentEventUpdated`，不能把 payload 插入普通聊天 history。所有新 Markdown/result 仍经过现有 sanitize 流程。
|
||
|
||
## 15. 可唤醒 sleep 的代码实现
|
||
|
||
`TurnWakeupHandle` 只由 root interactive Turn 创建并放入 ToolExecutionContext。它持有 `watch::Receiver<TurnWakeupState>`；state 使用独立于 durable inbox revision 的 session-local 单调 revision，因为用户 queue/steer 同样需要唤醒：
|
||
|
||
```rust
|
||
pub struct TurnWakeupState {
|
||
pub revision: u64,
|
||
pub pending_user_steer: usize,
|
||
pub pending_user_queue: usize,
|
||
pub pending_agent_steer: usize,
|
||
pub pending_agent_queue: usize,
|
||
pub latest_source: WakeupSource,
|
||
pub latest_safe_preview: Option<String>,
|
||
}
|
||
```
|
||
|
||
以下 admission 成功后递增 revision 并 `send_replace`：用户进入 TurnMailbox、用户进入 next-turn mpsc、Agent event durable admitted、Agent event 保持 pending 并成功 wake Session。先更新事实状态再发 wake，不能让 sleep 醒来却查询不到输入。
|
||
|
||
`SleepTool::execute_with_context`：
|
||
|
||
1. 解析并限制 duration 到 24 小时。
|
||
2. child context 的 `turn_wakeup=None`，只 select timer 与 cancellation。
|
||
3. root context 先读取 `receiver.borrow_and_update()`；若 pending 总数已大于 0，立即返回，不进入等待。
|
||
4. 否则同时等待 timer、`receiver.changed()` 和 cancellation。watch 保留最新 revision，因此 input 在检查与 select 之间到达也不会丢。
|
||
5. wake 后再次读取 state 并构造有界结果。steer 可以返回来源、run ID 和安全摘要；queue 只返回类型/数量，不返回正文。
|
||
6. cancellation 映射为统一 `AgentError::Cancelled`，不能让模型把它当普通 sleep 完成后继续执行。
|
||
|
||
Sleep 只提前结束工具 future，不消费 mailbox/inbox，也不自行改变 queue/steer。工具批次返回后，AgentLoop 在既定安全边界排空 steer；queue 留给下一个 Turn。
|
||
|
||
第一版 `InputInterruptPolicy` 只驱动 sleep 的 `WakeOnly`。不要顺带让 bash、browser、HTTP 或文件工具响应 input wake；以后开放 `CancelSafe` 必须逐工具证明取消、重试和副作用语义。
|
||
|
||
## 16. 分阶段实施清单
|
||
|
||
### 文件级落点
|
||
|
||
| 文件/模块 | 主要改动 |
|
||
|-----------|----------|
|
||
| `src/config/mod.rs` | orchestration config、默认值、边界校验 |
|
||
| `src/agent/definition.rs`（新） | Markdown/frontmatter 类型、严格 parser、definition hash |
|
||
| `src/agent/catalog.rs`（新） | immutable catalog、委托图与引用校验 |
|
||
| `src/agent/run.rs`（新） | run/group/outcome DTO、AgentRunner、ProviderFactory |
|
||
| `src/agent/coordinator.rs`（新） | 授权、预算、接纳、取消、deadline、terminal commit |
|
||
| `src/agent/inbox.rs`（新） | event/lease/projection/notifier contracts |
|
||
| `src/agent/agent_loop.rs` | cancellation、step gate、typed input safe boundaries |
|
||
| `src/agent/steering.rs` | 迁移为 typed TurnMailbox 与 reservation |
|
||
| `src/agent/sub_agent.rs` | legacy adapter，逐阶段缩减并最终删除旧 manager |
|
||
| `src/tools/traits.rs` | ToolExecutionContext、DelegationPolicy、interrupt policy |
|
||
| `src/tools/delegate.rs` | 仅 run/run_many 和兼容参数转换 |
|
||
| `src/tools/agent_task.rs`（新） | scoped get/list/cancel/get_result |
|
||
| `src/tools/emit_signal.rs`（新） | contract-bound signal |
|
||
| `src/tools/sleep.rs` | watch-aware wait 和 cancellation |
|
||
| `src/session/session.rs` | dual lane worker、internal task、atomic continuation、stop release |
|
||
| `src/session/agent_inbox.rs`（新） | claim/admit/release、fair scheduler、lease guard |
|
||
| `src/storage/mod.rs` | schema v6 migration 和领域 API re-export |
|
||
| `src/storage/agent_run.rs`（新） | run/group transaction SQL |
|
||
| `src/storage/agent_inbox.rs`（新） | capacity/event/lease/recovery SQL |
|
||
| `src/storage/message.rs`、`session.rs` | visibility/origin/durable delivery context |
|
||
| `src/gateway/mod.rs`、`reload.rs` | prepare/activation、recovery task、projection relay |
|
||
| `src/protocol.rs`、`src/session/commands.rs` | run query/event DTO 和 Turn origin |
|
||
| `src/gateway/http.rs` | 管理 API、legacy/new projection union |
|
||
| `webui/src/pages/TasksPage.svelte` | run tree、event/dead-letter/cancel UI |
|
||
| `webui/src/pages/ChatPage.svelte` | continuation origin 和 Signal 卡片 |
|
||
|
||
不要让 `session.rs` 继续吸收所有 inbox SQL 和状态机；先抽 Storage 领域 API 与 `session/agent_inbox.rs`，再接 worker，能显著降低竞态代码的审查难度。
|
||
|
||
### Phase 0：契约与 schema 冻结
|
||
|
||
- 固定本文 enums、状态转换、DDL 和默认值。
|
||
- 给现有 delegate、background notification、Session stop/reload 行为补基线测试。
|
||
- 为 config 示例准备 backward-compatible fixture。
|
||
|
||
完成条件：所有后续 PR 可以只引用固定 DTO/Storage contract，不再各自发明状态名。
|
||
|
||
### Phase 1：Catalog 与安全裁剪
|
||
|
||
- `definition.rs`、`catalog.rs`、严格 YAML parser。
|
||
- Config 扩展与候选代校验。
|
||
- Tool delegation metadata、scoped registry、skill wrapper。
|
||
- `foreground/background` schema 和 legacy parameter adapter。
|
||
- built-in general compatibility。
|
||
|
||
完成条件：具名 foreground Agent 能使用不同 Provider 和固定工具集；尚不开放 background 新路径。
|
||
|
||
### Phase 2A：AgentLoop 结构化取消
|
||
|
||
- CancellationToken 进入 root Turn 和 AgentLoop。
|
||
- Provider stream、工具批次、sleep 观察 token。
|
||
- `AgentError::Cancelled/TimedOut`。
|
||
- `/stop` oneshot 兼容桥接和迟到结果测试。
|
||
|
||
完成条件：root 行为不变；Provider、tool、preparation 各阶段 stop 均得到一致 Cancelled 终态。
|
||
|
||
### Phase 2B：Coordinator、run persistence 与 execution gate
|
||
|
||
- schema v6 的 run/group 部分。
|
||
- ProviderFactory、AgentRunner、Coordinator。
|
||
- run quota/provider gate/tool gate。
|
||
- foreground 单/批量、parent waiting_children、agent_task。
|
||
- WorkManager 原子绑定。
|
||
|
||
完成条件：foreground 全量持久化、截断结果可查询、并发上限为 1 时嵌套 foreground 不死锁。
|
||
|
||
### Phase 3：durable inbox 与 queue continuation
|
||
|
||
- `agent_session_state`、inbox Storage API、容量 reservation。
|
||
- late-bound notifier、Session watch wake、公平调度。
|
||
- hidden messages、turn origin、atomic continuation commit。
|
||
- recovery/dead-letter/fallback。
|
||
- WebSocket/HTTP run projection 和 WebUI 基础运行树。
|
||
|
||
完成条件：background completion 不直接通知 Channel；空闲/忙碌/队列满/重启/reload 下最终都能被主 Agent处理或进入可诊断 dead-letter。
|
||
|
||
### Phase 4：signal 与 steer
|
||
|
||
- EmitSignalTool、rate/dedupe/capacity。
|
||
- typed TurnMailbox 和两阶段 steer admission。
|
||
- `/stop` 立即 release、supersede 和 Signal UI。
|
||
|
||
完成条件：steer 在所有 admission 竞态中严格属于当前 Turn 或未来 queue 之一，不能重复或消失。
|
||
|
||
### Phase 5：wake-aware sleep 与清理
|
||
|
||
- TurnWakeupHandle watch revision。
|
||
- root sleep 响应 user/agent queue/steer，child sleep 仅 timer/cancel。
|
||
- 工具 interrupt policy。
|
||
- 移除 direct background notification 默认路径；观察一个版本后删除旧 adapter 和旧表写入。
|
||
|
||
完成条件：sleep 不丢 pre-listen wake，queue 内容不泄漏进当前 Turn，steer 在下一个安全边界可见。
|
||
|
||
## 17. 测试与故障注入
|
||
|
||
除主设计测试矩阵外，实施必须增加以下代码级场景。
|
||
|
||
### 17.1 Storage
|
||
|
||
- fresh database 创建 schema v6。
|
||
- v5 fixture 升级到 v6，原消息默认 visible/user。
|
||
- migration 任一步失败时 `user_version` 和全部表结构回滚。
|
||
- 两个并发 background 接纳只有一个能占最后 completion slot。
|
||
- completion 把 reservation 转 pending，不出现中间负数或超限。
|
||
- terminal transaction 在 plan update/event insert/usage 任一点失败时全回滚。
|
||
- execution ID 不匹配的迟到结果更新 0 行。
|
||
- startup reconciliation 能修复故意破坏的 state counters。
|
||
|
||
### 17.2 AgentLoop/Coordinator
|
||
|
||
- cancellation 发生在 permit wait、Provider connect、stream、工具批次、child wait。
|
||
- parent 等 child 时不持 step permit；global provider permit=1 仍能完成。
|
||
- foreground batch 并发执行但结果按 request index 返回。
|
||
- parent cancel 取消 foreground descendants，不取消已独立接纳的 background run。
|
||
- TaskSupervisor spawn reject 执行补偿事务且 delegate 不返回可用 ID。
|
||
- crash window 留下 queued old-generation run，activation 恢复为 interrupted。
|
||
|
||
### 17.3 Inbox/Session
|
||
|
||
- watch wake 在 worker 开始等待前发生也不会丢。
|
||
- user mpsc 满不影响 durable event。
|
||
- 连续用户输入达到 burst 上限后强制执行一个 event batch。
|
||
- continuation Provider 失败显式 release；进程模拟崩溃后 lease expiry 恢复。
|
||
- hidden trigger 与 assistant/event consume 原子；客户端 history 永远不返回 hidden。
|
||
- hidden user 不增加 title threshold/message_count。
|
||
- `/stop` 与 admit 的每个交错点都只产生 pending 或 consumed/admitted ownership之一。
|
||
- archived/deleted session 不启动 continuation且 reservation 归零。
|
||
|
||
### 17.4 Channel/protocol/UI
|
||
|
||
- durable context round trip 不包含 reply_to、message/reaction ID。
|
||
- 无 delivery binding 时 history commit 成功且不发送其他 chat。
|
||
- event broadcast lag/reconnect 后 full query 校准 revision。
|
||
- legacy/new tasks union 不重复并稳定分页。
|
||
- Signal payload、result Markdown 和错误信息通过 sanitize/redaction。
|
||
|
||
### 17.5 Sleep
|
||
|
||
- input 在 sleep 读取 revision 前、读取后但 select 前、select 后三个时点到达都能提前结束。
|
||
- user/agent 的 queue wake 只返回数量，不泄漏正文；对应输入仍由下一 Turn处理。
|
||
- steer wake 返回后由 AgentLoop 安全边界注入，SleepTool 自身不消费输入。
|
||
- child sleep 不因 root user input 或 sibling signal 唤醒，但 run cancel/timeout 会立即结束。
|
||
- duration 超过 24 小时拒绝；Gateway shutdown 不留下未托管等待任务。
|
||
|
||
建议把 SQLite failpoint、barrier 和暂停钩子限制在 `#[cfg(test)]`，用于精确制造 admission、stop、commit 与 reload 竞态，避免依赖随机 sleep。
|
||
|
||
## 18. 验证命令与合并门槛
|
||
|
||
每个 Rust 阶段至少执行：
|
||
|
||
```bash
|
||
cargo fmt --check
|
||
cargo test --lib
|
||
cargo test --test test_scheduler
|
||
cargo test --test test_request_format
|
||
cargo clippy --all-targets --all-features -- -D warnings
|
||
cargo build
|
||
```
|
||
|
||
涉及 WebUI 时另外执行：
|
||
|
||
```bash
|
||
cd webui
|
||
npm ci
|
||
npm run check
|
||
npm run build
|
||
cd ..
|
||
cargo build
|
||
```
|
||
|
||
文档或配置变更执行 `git diff --check`，并核对 README、配置模板、ARCHITECTURE、AGENTS 和 runtime knowledge 是否需要同步。API-backed ignored tests 只在配置了真实凭据时运行。
|
||
|
||
功能首次合并时按仓库规则提升产品中段版本；本文档本身不改变行为，不单独修改 `1.5.1`（当前功能合并版本 1.7.0）。
|
||
|
||
## 19. 主要风险与回滚
|
||
|
||
| 风险 | 预防 | 回滚方式 |
|
||
|------|------|----------|
|
||
| hidden history 过滤错误泄漏内部输入 | 查询 API 分层和协议测试 | 禁用 continuation worker，保留事件 pending |
|
||
| completion 容量计数漂移 | 单行条件更新 + 启动重算 | reconcile 修复后重启 Router |
|
||
| steer admission 竞态重复 | lease token + 不可排空 reservation | 配置强制所有 Agent delivery=queue |
|
||
| background 新路径影响现有用户 | legacy adapter 与新表分离 | 一个版本内启用 direct-notification rollback flag，二者互斥 |
|
||
| reload 双代同时恢复 | prepare/activation 硬边界 | 关闭新代 admission，旧代继续服务 |
|
||
| 工具权限误放大 | default RootOnly + Catalog fail closed | 从 definition 移除工具并 reload；已启动 run 固定旧快照 |
|
||
| continuation 重试重复外部副作用 | 默认只读 registry | dead-letter，要求用户显式处理 |
|
||
|
||
rollback flag 只能在 Phase 3 过渡期存在，并保证新 inbox continuation 与旧 direct notification 互斥。即使回滚投递方式，新 `agent_runs`/inbox 表仍保留审计事实，不能降 schema 或删除记录。
|
||
|
||
## 20. 最终实施判据
|
||
|
||
只有同时满足下列条件，才能把主设计状态从“提案”改为“已实现”：
|
||
|
||
- 具名 definition、不同 Provider、委托图和工具裁剪全部由运行时代码强制。
|
||
- foreground/background 都有 durable run，batch foreground 真正并发且父同步等待。
|
||
- run quota 与 provider/tool step gate 分离，嵌套委托无 permit 死锁。
|
||
- background completion 和 signal 先落 SQLite，丢 wake、queue 满、重启和 reload 均可恢复。
|
||
- queue continuation 使用 hidden trigger 原子提交；客户端历史没有伪用户消息。
|
||
- steer admission 与 `/stop` 竞态经过故障注入证明无丢失、无双重归属。
|
||
- sleep 的 wake 只改变等待，不破坏 queue/steer 内容边界。
|
||
- session archive/delete、dead-letter、fallback 和 management UI 均可诊断。
|
||
- 全部离线测试、Clippy、build、WebUI check/build 通过，并同步公开文档和产品版本。
|
||
|
||
在达到这些判据前，可以按 Phase 逐步合并内部基础，但不能提前对外宣称已经具备可靠的 background Agent orchestration。
|