IronClaw 的 ironclaw_turn_runner 源码剖析：Agent Turn 执行器、驱动注册表与 loop-host 工厂

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载ironclaw_turn_runner是 IronClaw 这个 Agent OS 中承担认领运行claimed run执行职责的核心 crate它既是内核进程监督器ProcessKind::AgentTurn注册的执行器也是驱动注册表与 loop-host 工厂所在的位置充当内核认领的运行与 loop 用户态之间的可信适配器。读完本文你将掌握该 crate 的公共表面、执行主流程、驱动注册与就绪校验、退出应用与证据验证、await-edge 子代理机制、失败消毒策略以及它与ironclaw_composition之间的唯一消费关系并能在改动驱动、装饰器顺序、失败/重试处置或退出应用时快速定位正确的代码位置。一句话定位依赖倒置下的可信适配器按照 crate 自带 README 的官方表述本 crate 是内核认领运行与 loop 用户态之间的可信适配器。它把ProcessKind::AgentTurn执行器注册进内核的进程监督器——注意这里的依赖倒置方向内核ironclaw_processes定义端口本 crate 向端口注册实现而不是反向依赖它只把每次认领到的运行claimed run所需的那组端口交给它并把 loop 声明的退出exit交给 turn 内核的退出应用器exit applier由后者在任何持久化提交之前完成验证。用一句话概括它永远不自行决定持久化never decides durability itself。从分层看它在 PROPOSAL §6.7.3 中属于loop/loops层layer loops包名为ironclaw_turn_runner清单位于 Cargo.toml。需要说明的是ironclaw_turn_runner是一个内部装配构件lib.rs 明确指出它唯一的合法下游消费者是ironclaw_composition架构测试ironclaw_architecture_tests会强制这一依赖边界。什么时候用这个 crate按 README 的边界划分用在这里改驱动drivers、驱动就绪driver readiness、能力端口装饰器的顺序capability-port decorator ordering、失败车道/重试处置failure-lane / retry disposition、退出应用exit application、子代理 await-edge 解析器。不在这里改loop 策略本身 → ironclaw_agent_loop端口适配器实现 → ironclaw_loop_host调度机制认领/租约/心跳/恢复→ ironclaw_processes。公共表面Public surfacelib.rs 刻意采用模块目录而非类型货架的形态每个模块按路径可达如ironclaw_turn_runner::driver_registry::DriverRegistry、ironclaw_turn_runner::planned_driver_factory::register_default_planned_driver但不做一墙pub use扁平化重导出——那是边界测试要防止的投机性公共 API模式。RebornTurnRunExecutor注册进内核监督器的执行器RebornTurnRunExecutorturn_run_executor.rs是注册到进程监督器的具体TurnRunExecutor。它把三样东西适配到TurnRunScheduler消费的TurnRunExecutortraitArcLoopExitApplier——可信的退出应用器ArcDriverRegistry——驱动注册表Arcdyn HostFactory——每个认领运行构造一个AgentLoopDriverHost的工厂OptionArcdyn GateRecordStorePort——auth gate 的持久化凭证需求回源§5.2.9 render-from-recordArcdyn AwaitEdgeSettler——运行启动前的后台 await-edge 清扫器。turn_scheduler.rs中的 TurnRunScheduler 本身只是一个agent-turn 投影自 #6696 起基于ironclaw_processes::ProcessSupervisor构建并不是独立的调度器——认领/心跳/租约/恢复机制都在内核该文件只负责把它们翻译成 turn 词汇。DriverRegistry与两个生产驱动驱动注册表driver_registry.rs持有具体驱动实例在启动时冻结描述符元数据并在接流量之前校验配置的和持久化的运行身份都能被服务。两个生产驱动PlannedDriverplanned_driver.rs——把 runner 侧的AgentLoopDrivertrait 桥接到密封的ironclaw_agent_loop框架内部持有一个不透明的LoopFamily和规范执行器CanonicalAgentLoopExecutor默认描述符 ID 为reborn:planned-default、版本 1且必须携带 checkpoint schema否则InvalidRequesttext_loop_driver.rs——支持的最小行为只构建纯文本 prompt 包、流式拿一次 host 管理的模型响应、只接受最终 assistant 回复并终结到 transcript 端口工具/能力调用一律拒绝。其驱动 ID 为reborn:text-only-model-reply、版本 1默认context_limit为 16text_loop_driver.rs。两者之间的回退必须是显式的 profile/就绪决策绝不静默发生AGENTS.md 的Do Not Move In Here也把hidden fallback from planned to text-only列为红线。loop_driver_host.rs/runtime.rsloop-host 工厂与装饰器链loop_driver_host.rs负责为一个认领运行装配端口集合runtime.rs负责 planned-runtime 组合与能力端口装饰器链——装饰器的顺序ordering按章程就是本 crate 的属地。源码里可以看到大量装饰器与安全适配器能力表面过滤工厂SurfaceFilteringCapabilityPortFactory、表面状态追踪SurfaceTrackingLoopCapabilityPort在builtin.extension_install等可能改变可见表面的能力调用后清空缓存、hook 能力输入解析适配器默认输入字节预算DEFAULT_HOOK_CAPABILITY_INPUT_MAX_BYTES 64 KiB超限按未解析失败关闭、事件触发 hook 订阅含租户/线程隔离的有效读作用域派生防止跨线程/跨项目事件泄漏等。loop_exit_applier.rs对宿主铸造证据的退出验证loop_exit_applier.rs提供两个证据端口适配器InMemoryLoopExitEvidencePort——严格测试/本地证据端口默认不信任一切宽松证据 mutator 全部#[cfg(test)]门控生产构建无法通过该适配器铸造完全可信的退出证据ThreadCheckpointLoopExitEvidencePort——生产可用的文本/checkpoint 背书证据适配器完成证据要求每个回复引用与结果引用都有同 run 终结化的线程证据背书blocked 证据要求 checkpoint 的gate_ref与 blocked 退出报告的 gate 完全一致防止用同 run 其它 gate 的BeforeBlockcheckpoint 冒充 Auth 证据失败证据要求recent_failure_kinds命中且解释消息引用都已终结化。subagent/await_edge/await-edge 机制await-edge 的store是对ironclaw_processes::ProcessDependencyPort的纯投影不是第二份日志resolver留在本 crate 作为真正的 loop 层职责PROPOSAL §12.13 D-S涵盖 owner 恢复、未信任文本栅栏后的子转录物物化、批量门排空与父级恰好一次恢复、BlockedDependentRunGate恢复策略。await_edge/mod.rs 定义了 CAS 状态机AwaitEdgeStateOpen → Settled → Drained后台子结果还会走ResultAppended → AttentionScheduled投递链AttentionDeferredStreakCap是达到连续打断上限后的绕行停车态绝非终点。trace_capture.rsWS6 trace-capture 拆分的 runner 半trace_capture.rs 是 WS6 trace-capture 拆分的观察者半边持有TurnEventSink实现、历史读取端口与 record→message 适配捕获流水线本体在ironclaw_trace_commons::capture。读取走模型上下文replay视图而非list_thread_history否则历史投影会清空tool_result_provider_call导致 trace 退化为纯文本且捕获绝不允许阻塞或失败 turn 生命周期路径错误只debug!级记录。执行主流程源码级走读以execute_claimed_runturn_run_executor.rs为入口一次认领运行的执行分为三个阶段Run-start 清扫驱动运行前先调用await_edge_settler.sweep_thread_on_run_start治愈该线程上遗留的后台 await-edge。human_initiated镜像 streak-cap 准入规则——Human或缺失 provenance 允许启动System/ParentAgent不允许。清扫失败只记日志、不阻断运行启动。invoke_driverL373-L525从claimed.resolved_run_profile.loop_driver解析出LoopDriverRegistryKey查注册表拿驱动用HostFactory::create_host构造一次性 host然后按checkpoint_id.is_some()决定走driver.resume还是driver.run重排队 blocked 运行保留 checkpointcheckpoint 身份就是恢复信号。驱动返回LoopExit后先host.finalize_terminal_output终结化再在 host 存活期间快照supplemental_model_usage并合并进退出或类型化失败元数据。apply_exitL537-L660把LoopExit交给可信应用器loop_exit_applier.apply_with_supplemental_model_usage。若为Completed随后触发两个后终结、尽力而为、带超时的副作用after-turn 记忆录制mem0addseam超时AFTER_TURN_MEMORY_RECORD_TIMEOUT 30s则跳过与after_turn生命周期 hook 分发每次运行现造一个 dispatcher 以保证 hook 毒化只作用于当前 run外层超时AFTER_TURN_HOOK_DISPATCH_TIMEOUT 30s必须严格大于dispatcher 单 hook 5s 上限否则外层取消会与内层同时落地、把慢 hook 从分类中偷走。值得注意的两处安全细节Auth gate 凭证需求回源§5.2.9 flip 之后auth block 的credential_requirements从 loop 通道移到了 host 持久化的GateRecord::Auth上LoopBlocked.credential_requirements到达时为空。执行器通过前缀gate:auth-剥离出gate_id用确定性GateRef::for_auth_gate(gate_id)重建键并从gate_record_store回源若 store 已装配却查不到缺记录、类型错误、读失败返回Err(tag)让退出失败并记录终结失败——宁可失败也不让用户停在一个无法提交的 auth 门上。双重失败才上抛只有当退出应用失败 回退record_runner_failure也失败时apply_exit才返回Err(metadata)由调度器记录终结失败且不会丢弃 exit 已认领的用量快照TurnRunFailureMetadata携带累积LoopModelUsage。驱动注册与就绪验证DriverRegistry::register_driverdriver_registry.rs在注册时校验描述符版本必须大于 0checkpoint schema id 与 version 必须同时存在或同时缺失。重复注册同一 key 报DuplicateRegistration。每个驱动还带一份DriverRequirementsmodel / prompt / transcript / checkpoint / input_polling / capabilities / progress_events 七项每项Required | Optional | Unsupported和DriverKindProduction/Referencefake 驱动只允许显式 standalone/test 就绪。validate_readiness综合三类输入生成报告host 图可用性HostGraphReadiness、启用的运行 profileConfiguredRunProfile、非终结的持久化运行PersistedRunDriverIdentity。产出ProductionReady | NonProductionDegradedReference | NotReady三态并给出阻塞/非阻塞诊断如MissingConfiguredDriver、MissingNonTerminalRunDriver、ReferenceDriverNotProductionReady。production_readiness.rs则是一个没有生产调用方的报告切片validate_reborn_loop_production_readiness等待被接入启动门或删除CHECKLIST WS4/WS8README 明确告诫不要在其上构建。组合层 ironclaw_composition/src/lib.rs 展示了真实的装配样例依次注册 text-only 驱动、默认 planned 驱动、subagent planned 驱动、unbound planned 驱动与 unbound 结构化 planned 驱动并构建默认 planned run profile 解析器runtime.rs则装配 trace-capture sink、after-turn hook、CancelReconcilingTurnCoordinator等。调度配置与心跳预算TurnRunSchedulerConfigturn_scheduler.rs把通用ProcessSupervisorConfig包了一层关键约束是心跳失败预算绝不能超出进程租约 TTLTURN_RUN_MAX_CONSECUTIVE_HEARTBEAT_FAILURES 8turn-run 上限通用默认仍为 3因为能力路径 30s 心跳一次8 次会远超租约一次失败心跳的成本是2 * interval等一个 interval 一次心跳超时所以MAX_HEARTBEAT_INTERVAL_WITHIN_LEASE DEFAULT_PROCESS_LEASE_DURATION / 2是能支付第一次失败的最宽 interval超过它的配置值会被钳制而非静默接受一个兑现不了的 budget1默认 shipped 的 15s interval 对应 budget 3with_runner_heartbeat_interval会联动重算 budgetwith_max_consecutive_heartbeat_failures也以租约推导值为上限封顶。测试hosted_heartbeat_interval_absorbs_one_postgres_checkout_timeout验证了 5s 心跳budget 8容忍窗口 80s能扛住一次 30s 的 Postgres checkout 卡顿——这正是托管环境池饥饿事故的回归防线。失败处理与错误消毒turn_runner.rs提供两个共享失败助手sanitized_failure与sanitized_driver_failure。后者对一组合法的模型侧类别model_credits_exhausted、model_credentials_unavailable、model_spend_budget_exhausted、budget_accounting_failed、transcript_write_failed、checkpoint_rejected、model_context_overflow、model_output_truncated、interrupted_unexpectedly原样保留类别并附带受限 detail其余一律折叠为driver_failed任何类别校验失败最终回退到unknown_failure。interrupted_unexpectedly的保留是刻意的§5a.5 loop 失败矩阵planned driver 把执行中Cancelled映射到它折叠成driver_failed会从持久化失败记录里抹掉原始类别。失败分类的标识符与类别→摘要表在 WS1.7 已迁移到ironclaw_host_api::failurePROPOSAL §6.1.1本 crate 的failure_categories/failure_summary已降为 runner 私有。依赖边界与不变量README 与 AGENTS.md 共同划定的红线17 个普通工作区依赖ironclaw_agent_loop、ironclaw_loop_host、ironclaw_hooks声明的装饰器链、内核ironclaw_turns、ironclaw_processes、ironclaw_host_runtime、ironclaw_approvals、契约ironclaw_host_api、ironclaw_loop_contracts以及ironclaw_event_log、ironclaw_filesystem、ironclaw_memory、ironclaw_observability、ironclaw_outbound、ironclaw_safety、ironclaw_threads、ironclaw_trace_commons。明确不含ironclaw_llm——provider 锥体在 WS3 已随 model gateway 迁出重新引入它意味着 provider 行为回归reborn_runner_llm_wiring_is_isolated是仲裁者。被 1 个 crate 消费ironclaw_composition绝不反向。shed 项留在ironclaw_loop_hostmodel gateway、model routes、driver-host 适配器、tool disclosure由reborn_runner_sheds测试钉住以及 runner 的 LLM 隔离reborn_dependency_boundaries下的reborn_runner_llm_wiring_is_isolated。await-edge store 是投影而非第二份日志由集成测试 tests/integration/subagent_await_edge.rs 的runner_await_edge_is_a_projection_over_process_dependencies钉在集成层。不通过公共 API 暴露任何 planner 策略槽不从ironclaw_turns/ironclaw_loop_contracts复制中性词汇DTO 单一归属。测试与验证cargo test -p ironclaw_turn_runner cargo test -p ironclaw_architecture_tests # 依赖/API 变更后必跑crate 内测试目录 tests/ 覆盖driver_registry、planned_driver_e2e、production_readiness、turn_run_executor其中用NoOpAwaitEdgeSettler假件隔离不需要真实进程日志的用例另有after_turn_hook_context.rs验证 after-turn hook 上下文派生。turn_run_executor.rs内的单测则验证失败路径下累积用量的保真合并如apply_exit_failure_preserves_cumulative_usage_already_on_exit。延伸阅读家族规则crates/loop/AGENTS.md工作规则crates/loop/ironclaw_turn_runner/AGENTS.md设计记录docs/internal/reborn/target-architecture/families/loop.md§6.7.3 PROPOSAL §12.13 D-S调度机制归属crates/kernel/ironclaw_processes/README.md端口适配器归属crates/loop/ironclaw_loop_host/README.mdloop 策略归属crates/loop/ironclaw_agent_loop/README.md。综上ironclaw_turn_runner的价值不在于发明新机制而在于精确地守住那条可信边界执行器只负责把内核认领的运行用正确的驱动跑起来退出是否合法由证据端口与内核退出应用器裁决持久化永远不在这里发生对任何想要理解或修改 IronClaw turn 执行语义的开发者它都是绕不开的入口。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw 的 claimed-work 控制平面深入解读 ironclaw_turn_runner 的执行器、驱动注册表与 loop-host 工厂IronClaw 的 claimed work 控制平面深入解读 ironclaw_turn_runner 的执行器、驱动注册表与 loop host 工厂人工智能AI 应用交互助手AI AgentIronClaw turn_runner 控制平面解析回合执行器、驱动注册表与循环主机工厂的职责边界IronClaw turn_runner 控制平面解析回合执行器、驱动注册表与循环主机工厂的职责边界 ironclaw_turn_runner 是 IronC人工智能AI 应用交互助手AI AgentIronClaw loop 层契约解析ironclaw_loop_contracts 如何让 agent loop 与 turn 内核解耦IronClaw loop 层契约解析ironclaw_loop_contracts 如何让 agent loop 与 turn 内核解耦 本文是 IronC人工智能AI 应用交互助手AI Agent上一篇PostgreSQL pgvector扩展5步快速构建高效的向量搜索数据库下一篇OpenJarvis 本地优先个人 AI 框架实战指南安装、预设配置、技能系统与内置 Agent 全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考