# Agent Module Rules

## 范围与职责

适用于 `src/host/agent/`。

治理「一个角色节点 ⇄ 一个可延续子代理」这一执行单元，并承担父代理会话能力的宿主适配：

- 把节点配置确定性翻译为官方子代理运行时的创建参数；
- 创建/复用节点子代理，并把本轮任务块投递进去；
- 在该子代理作用域内注入 Agent 语义；
- 为编排层与工具层提供父代理会话宿主能力。

判断归属：该修改是否改变「节点 → 子代理」的创建/复用/投递/作用域装配语义，或改变本模块对官方 Agent 能力的适配契约？若主要属于其他领域，应放到对应模块。

## 依赖边界

- 官方能力仅经 `ctx.get()` / 注入缝**运行时解析**，并以本模块自带的最小结构守卫收窄；允许 `import type` 官方纯类型（如 `Context`），不得有官方运行时 import；
- orchestrator 仅允许**类型**导入其公共入口（`NodeRunner` / `AgentHost` / `NodeStartInput` 等契约缝）；本模块不得成为 orchestrator 的运行时依赖；
- storage 仅类型与读取缝；graph 仅纯函数事实推导；shared 仅共享类型与协议常量；Node 内置模块（fs / async_hooks）。

**官方适配必须可追溯**：改官方 seam 适配时，注释中必须写明包名与符号、取证结论（含版本差异）、失效或缺失时的降级路径与后果。不得凭记忆或推断编写官方契约。

## 状态所有权

- 模块外只能经公开方法/事件请求变化，不得直接修改内部表；
- 新增按 child / 会话维度持有的状态必须定义释放条件；生命周期长于「单次子代理运行」的表必须有明确上界与回收路径，不允许只增不减；

## 生命周期

执行单元生命周期：创建 → 复用派发 → 进行中（不等待）→ 结束/失败/中断 → 清理（宿主统一）。

必须保证：
- **复用由配置签名决定**：签名必须覆盖一切影响子代理组成的输入。
- 创建/复用路径**不得等待子代理完成**；完成事实只经官方事件观察，由编排层回写。
- 中断是**尽力而为**：目标不存在或已停止视为成功；调用方不得依赖中断同步生效。
- **重建子代理时，旧子代理的处置语义必须明确**（保留/中断/归属回收），并在注释中说明其事件对节点结论的影响；不得让旧子代理的事件静默影响新子代理。

## 验证补充

- 涉及官方适配、宿主装配或产物契约时追加构建验证；
- 复用签名组成与作用域装配（安装/撤销）有测试锁定；
- 面向模型文本与工具白名单未意外改变。

## 核心原则

1. 节点配置确定性映射为官方子代理调用。
2. 复用由签名决定，签名必须完整。
3. 作用域装配的生命周期归宿主，模块不私建撤销表。
4. 创建即推理、不等待完成，完成只经事件观察。
5. 官方适配必须取证可追溯；官方能力零运行时依赖，允许 `import type` 官方纯类型。
6. 每子代理状态必须有释放条件与上界。
7. 面向模型的文本、工具白名单与官方消息 payload 是对外契约。