[架构] Host 托管 ingestion 长事务等待，避免 Agent 轮询耗尽 max_iterations

[noho]

背景

当前 ingestion download/process 已经被 job 化，但 Agent 仍在同一个 turn 内反复调用 status 工具等待终态。典型 prompt：

下载 META 最新季报，给出摘要

实际链路容易变成：

start_financial_filing_download_job -> get_financial_filing_download_job_status -> ... -> max_iterations -> 基于阶段进度降级答复

这不是 max_iterations 太小，而是等待职责放错层：LLM 负责了机械轮询，Host 没有托管“外部长事务等待 + 终态唤醒”。

当前代码证据

• dayu/fins/ingestion/job_manager.py 已说明 ingestion job 生命周期独立于 AsyncAgent，且 download/process 各自串行执行一个 job。这说明 job 化基础已存在。
• dayu/fins/tools/ingestion_tools.py 的 start/status 描述仍明确要求“下一步只用状态工具轮询，直到终态”。
• _build_next_step() 在 queued/running/cancelling 时返回 next_step.action = "poll_status"、tool_name = status_tool_name、suggested_wait_seconds = 5。
• DuplicateCallGuard 对 poll_until_terminal 的未终态结果显式放行重复调用，不触发重复工具保护。

结论：现状是“LLM 被允许并被提示机械轮询”，所以长下载耗尽 Agent iteration 是架构必然结果。

上游研究

Claude Code

项目/资料：

• GitHub: https://github.com/anthropics/claude-code
• Scheduled tasks 文档: https://code.claude.com/docs/en/scheduled-tasks
• Ralph Wiggum plugin: https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum

观察：

• anthropics/claude-code 是公开仓库，但 README 和 plugins 目录显示它主要承载安装入口、插件、命令、agents、hooks 等外壳/扩展层，不等于完整 CLI 内核源码。
• Claude Code 的 scheduled tasks 文档把长时间等待分成 /loop、Desktop tasks、Cloud tasks；还提到 Monitor tool 可以跑后台脚本并流式返回输出，避免反复重跑 prompt 轮询。
• Ralph Wiggum plugin 展示了另一类 session 内 agent loop：通过 Stop hook 阻止 Claude 结束，并把同一个 prompt 重新喂回去，直到 completion promise 或 max-iterations。它适合测试/编码自我修复，不适合 Dayu ingestion 等待，因为它仍然让 Agent 留在循环里。

可借鉴点：

• “等待一会再检查”应成为 runtime/session 能力，不应只靠 prompt 纪律。
• Monitor/后台脚本模式说明：对于长 I/O，事件或日志流比 LLM 轮询更省 token。
• Stop hook loop 可作为“防止误停”的参考，但不是 ingestion 的主路径。

Codex

项目/资料：

• GitHub: https://github.com/openai/codex
• Codex App 介绍: https://openai.com/index/introducing-the-codex-app/
• Enterprise/Edu release notes: https://help.openai.com/en/articles/10128477-chatgpt-enterprise-edu-release-notes
• Unified Exec source: https://github.com/openai/codex/tree/main/codex-rs/core/src/unified_exec

观察：

• openai/codex 的 Unified Exec 明确把交互式/长命令作为 Host/runtime 管理的 process：
  • mod.rs 定义 ProcessStore、ProcessEntry、process_id、yield time 上限和后台 terminal timeout。
  • process_manager.rs 在 initial yield 之前持久化 live process，避免 turn 中断导致后台进程被释放。
  • async_watcher.rs 启动后台 watcher，持续读取输出，并在进程退出后发出统一的 end event。
• Codex App 层面把多个 agent、长时程/background tasks、isolated worktrees、progress/decisions 展示给用户，形成控制平面。

可借鉴点：

• 工具调用返回“不一定代表底层进程已完成”；返回时可以带 process_id/job_id，由 runtime 继续持有。
• 输出/进度是 runtime event，不必全部进入 LLM 上下文。
• UI 应展示 Host/runtime 进度；LLM 只在语义节点介入。

OpenClaw

项目/资料：

• GitHub: https://github.com/openclaw/openclaw
• Background tasks docs: https://github.com/openclaw/openclaw/blob/main/docs/automation/tasks.md
• Cron docs: https://github.com/openclaw/openclaw/blob/main/docs/automation/cron-jobs.md

观察：

• OpenClaw 明确说 task 是 activity ledger，不是 scheduler：cron/heartbeat 决定何时运行，task 记录发生了什么。
• task 生命周期是 queued -> running -> terminal，终态包括 succeeded/failed/timed_out/cancelled/lost。
• 文档明确说 completion 是 push-driven：detached work 完成后直接通知 channel，或把 system event 放入 requester session，在下一次 heartbeat surfaced；通常不应写 status polling loops。
• Cron 在 Gateway 进程里运行，任务定义持久化到 ~/.openclaw/cron/jobs.json，运行态在 jobs-state.json；所有 cron execution 都创建 background task record。

可借鉴点：

• Dayu 需要 Host 侧 task/await ledger，而不是让 LLM 对每个 job 自己记忆。
• 终态唤醒比轮询 prompt 更适合长事务。
• lost/timed_out/cancelled 这类治理状态应该属于 Host，而不是 ingestion tool 自己临时拼返回文本。

Dayu 设计结论

目标不是删除 ingestion job 工具，而是把 status 轮询的主调用者从 LLM 挪到 Host。

建议引入 Host 托管的 awaitable tool/job 契约：

1. 工具结果仍可返回 next_step.action = "poll_status"，但同时提供机器可识别的 wait spec，例如：

{
  "awaitable": {
    "kind": "tool_job",
    "owner": "fins.ingestion",
    "job_id": "job_xxx",
    "status_tool_name": "get_financial_filing_download_job_status",
    "terminal_statuses": ["succeeded", "failed", "cancelled"],
    "suggested_wait_seconds": 5
  }
}

2. AsyncAgent 不直接理解 ingestion；它只把工具结果事件交给 Host。
3. Host/Executor 识别 wait spec 后：
   • 暂停当前 Agent run，不进入 force_answer。
   • 保留或更新 pending turn 真源。
   • 创建 Host-owned wait record/monitor。
   • 由 Host monitor 按 wait spec 调用 status 工具或对应 service 查询状态。
4. job 进入终态后，Host resume pending turn，把终态 snapshot 注入上下文，让 Agent 继续执行原始目标。
5. UI 从 Host wait record/job snapshot 展示进度，不把“下载中”作为 assistant 最终答案。

目标流程：

用户 prompt -> Agent 启动下载 -> Host 托管等待 -> ingestion job 终态 -> Host resume Agent -> Agent list_documents/read/summarize -> 最终摘要

分层约束

• 不让 dayu.fins 反向依赖 Host。
• 不让 Host 硬编码 ingestion 具体实现；Host 只识别通用 wait spec。
• dayu.fins.storage 仍是财报文档存取唯一入口。
• ingestion_tools 继续只暴露 start/status/cancel 业务工具；是否挂起/恢复由 Host 决定。
• 不通过调大 max_iterations 修复；那只是把等待成本继续塞进 LLM loop。

建议落地阶段

阶段 1：契约与最小闭环

• 定义通用 AwaitableToolJobSpec 类型。
• ingestion start/status 返回 wait spec。
• Host 在工具结果中识别 wait spec，先支持单 job 等待。
• Host monitor 复用现有 status tool schema/tool executor 查询状态。
• 终态后 resume pending turn，并注入一个结构化“等待结果”上下文。

阶段 2：治理

• wait record 增加 timeout、cancel、lost、retryable failure。
• UI 暴露 running wait 状态与取消入口。
• Host 启动恢复时 reconcile 未终态 wait record。

阶段 3：泛化

• 支持多个 awaitable job。
• 支持 push/event-driven ingestion 事件，减少固定轮询。
• 把 process/download 两类 ingestion job 统一到同一 wait contract。

验收标准

• 对“下载 META 最新季报，给出摘要”，下载未完成时 Agent 不再持续调用 status 直到 max_iterations。
• 下载期间 UI 能看到 Host/job 进度。
• 下载完成后，Agent 自动恢复并继续读取财报生成摘要。
• 用户取消 run 时，Host 能取消或标记对应 wait/job，并保持 pending turn/run 状态一致。
• pyright 无新增错误；新增/修改代码有对应测试。

风险与开放问题

• wait spec 应放在工具业务返回里，还是放在 tool result metadata 里？倾向 metadata，避免污染 LLM 认知负担；但现有工具协议是否支持需要确认。
• Host monitor 调用 status tool 还是直接调用 manager/service？倾向调用通用 tool executor 或抽象 status reader，避免 Host 依赖 dayu.fins 具体实现。
• pending turn 的状态机是否需要新增 WAITING_EXTERNAL_JOB，还是复用现有 resumable/cancelled timeout 语义？需要结合 dayu/host 当前状态机设计。
• 进程内 IngestionJobManager 的 job 是否需要持久化到 workspace，避免 Host 重启后只剩 pending turn 但 job manager 内存丢失。

[noho]

补充研究：Host domain 边界、ToolRegistry 归属与权限控制

这次补充先明确一个硬前提：Host 不知道、也不能知道 domain 知识。因此本 issue 不能被实现成“Host 识别 fins ingestion job，然后替 Agent 等待”。那会把 ticker、filing、download、summary 这类领域语义上推到 Host，违背 Dayu 的 UI -> Service -> Host -> Agent 分层。

1. 当前代码事实

1. ToolExecutor 的稳定协议已经在 contracts，不是 engine 私有接口。

   • 证据：dayu/contracts/protocols.py:179 定义 ToolExecutor.execute/get_schemas/clear_cursors/...。
   • 这说明跨层边界的真源已经是“工具执行协议”，不是 ToolRegistry 这个具体类。

2. Host 当前只做 toolset 的机械装配，不解释 domain。

   • 证据：dayu/host/scene_preparer.py:758 加载 registrar，dayu/host/scene_preparer.py:764 构造 registry，dayu/host/scene_preparer.py:773 加载 registrar，然后把 ToolsetRegistrationContext 传进去。
   • Host 只传 workspace / toolset_config / execution_permissions / tool_timeout_seconds 等通用上下文。

3. Fins 领域 runtime 的装配仍在 Fins toolset adapter 内。

   • 证据：dayu/fins/toolset_registrars.py:60 的 register_fins_ingestion_toolset 在 Fins 包内创建 runtime，并调用 register_fins_ingestion_tools(...)。
   • 这条边界是对的：Host 不直接 import Fins ingestion service，也不理解 filing job。

4. 现有卡点在 Engine 的 tool loop 控制点。

   • 证据：dayu/engine/async_agent.py:965-1018 在 TOOL_CALLS_BATCH_DONE 后组装 assistant tool calls 并 append 到 messages。
   • dayu/engine/async_agent.py:1050-1061 把 tool result 注入 role=tool message。
   • dayu/engine/async_agent.py:1130-1136 记录 tool_calls_continued 后直接 continue 下一轮 LLM iteration。
   • 所以 Host 仅监听事件是不够的；一旦工具返回 running，Engine 默认会把它喂回模型，让模型继续轮询，直到耗尽 max_iterations。

2. ToolRegistry 要不要移到 Host？

结论：不建议把 ToolRegistry 整体移到 Host。

第一性原理上，这个问题不是“类放在哪个目录”，而是“谁拥有治理决策，谁拥有工具运行机制，谁拥有 domain 解释”。Host 必须拥有生命周期、取消、等待、审计、权限裁决这些治理能力；但 Host 不应该拥有工具 schema、参数校验、截断分页、fetch_more、文件路径参数检查、response middleware、tool descriptor 等工具运行细节，更不能拥有 fins/doc/web 的领域解释。

更合适的结构是：

1. ToolExecutor 协议继续留在 contracts，作为 Host 与 Engine 之间的稳定契约。
2. ToolRegistry 继续作为无 domain 的工具运行时实现。短期可留在 dayu.engine；长期如果要治理目录语义，可以移到中性包，例如 dayu.tools / dayu.tool_runtime，但不应移入 dayu.host。
3. Host 增加一个通用治理包装器，例如 GovernedToolExecutor：
   • 包裹 ScenePreparer 产出的 PromptToolExecutorProtocol；
   • 做 toolset/tool/capability 粒度的通用权限 gate、审计、取消与 await handoff；
   • 只读取通用 descriptor / capability / wait spec；
   • 不识别 fins、ticker、filing、download 等 domain 字段。
4. Engine 增加“工具结果请求挂起”的通用控制点：
   • ToolExecutor.execute(...) 的结果或 middleware 可以携带结构化 await_spec；
   • AsyncAgent 在 TOOL_CALLS_BATCH_DONE 后、进入下一轮 LLM 前识别它；
   • Engine 产出通用事件，例如 EXTERNAL_WAIT_REQUESTED / TOOL_AWAIT_REQUESTED，并以非成功、非失败的 termination reason 收口本轮；
   • Host 接管等待记录与恢复。

也就是说：ToolRegistry 不搬到 Host；Host 拥有 governed wrapper；Engine 暴露 suspend/await 控制点。

3. 权限控制建议

未来权限控制建议拆成两层：

1. Host-owned generic policy gate

   • 输入：session/run/user、toolset、tool name、capability tags、declared resource class、tool arguments 的通用结构视图。
   • 输出：allow / deny / require confirmation / await handoff。
   • Host 不解释 domain，只根据通用策略裁决。

2. Toolset-owned domain permission interpretation

   • doc toolset 继续解释文件读写路径、白名单、写权限。
   • web toolset 继续解释 private network URL、provider、timeout。
   • fins toolset 继续解释财报下载、存储、job manager。
   • Service 可以把业务选择变成 selected_toolsets / toolset_config / execution_permissions，但 Host 只消费通用契约。

这与当前代码已有方向一致：ExecutionPermissions 是通用执行权限快照，doc/web 的具体解释已经在各自 registrar 内；Fins runtime 也在 dayu.fins.toolset_registrars 内装配。

4. Await spec 必须是通用契约

为了守住 Host domain 盲性，等待契约不能写成 fins_ingestion_job，而应是通用形状，例如：

kind: tool_awaitable
tool_call_id: <opaque id>
tool_name: <tool name>
correlation_id: <opaque job id>
status_reader:
  tool_name: <status tool name>
  arguments: <structured arguments>
terminal_condition:
  status_path: <generic path>
  success_values: [...]
  failure_values: [...]
poll:
  interval_seconds: ...
  timeout_seconds: ...
cancel:
  tool_name: <optional cancel tool>
  arguments: <structured arguments>
resume:
  inject_result_policy: append_tool_result | replace_tool_result | call_resume_tool

Host 可以存储和调度这个 spec，但不能理解 correlation_id 代表的业务含义。是否是 SEC 下载、巨潮下载、Docling 转换、OCR、音频转录，都应由 toolset 自己声明和恢复。

5. 风险与开放问题（更新版）

1. Engine 现在缺少“tool result 后暂停下一轮”的稳定控制点。仅在 Host 层监听 TOOL_CALL_RESULT 不能阻止 AsyncAgent 继续下一轮。
2. ToolRegistry 整体移入 Host 会扩大 Host 职责，容易把工具运行机制和 domain adapter 泄漏进 Host；更推荐 Host wrapper + ToolExecutor 协议。
3. await_spec 的序列化要进入 Host pending turn / run snapshot，否则进程重启后无法恢复等待。
4. IngestionJobManager 如果仍是进程内状态，Host 即使持久化了 wait record，重启后也可能找不到底层 job；需要 job 状态持久化或可重建策略。
5. Run 状态机需要新增“等待外部工具任务”的非终态，不能混同为 succeeded / failed / cancelled / max_iterations。
6. Tool transcript 需要定义清楚：触发 await 的 running 结果是否立即注入 messages？建议至少保存原始 tool call 与 await spec，但不要让 LLM 形成“下载中”的最终回答。
7. 一轮多个 tool call 时，如果其中一个返回 awaitable，其他 tool result 如何处理需要明确。阶段一建议只支持单 awaitable batch，或要求 awaitable 工具声明独占 batch。
8. 用户取消等待时，Host 是否调用 cancel tool 应由通用 cancel spec 决定；Host 不解释取消的业务后果。
9. 权限控制不能演化成 Host 里的 if doc/web/fins 分支；应引入通用 capability/permission descriptor，由 toolset adapter 负责把 domain 能力映射成通用声明。
10. 如果未来把 ToolRegistry 从 dayu.engine 移走，应按“中性工具运行时包”迁移，而不是 Host 化；迁移目标是降低目录语义误导，不是改变 Host/Engine 职责边界。

6. 推荐阶段计划修订

1. 阶段一：定义通用 ToolAwaitSpec 与 Engine suspend event，不改 domain 逻辑。
2. 阶段二：为 Host 增加 GovernedToolExecutor 包装器，接入审计、权限 gate、await handoff。
3. 阶段三：让 fins ingestion 的 start_*_job 返回通用 await_spec，status/cancel 仍由 fins toolset 提供。
4. 阶段四：持久化 Host wait record，并补齐恢复、取消、超时、单 awaitable batch 测试。
5. 阶段五：评估是否把 ToolRegistry 从 dayu.engine 搬到中性包；不把它搬到 dayu.host。